REST API v1Agency Ready

CiteMind API Documentation

Connect agency workflows to CiteMind with secure REST endpoints for product context, visibility snapshots, and recommendations.

Getting StartedAPI ReferenceGenerate Token

Getting Started

Go Live in 5 Minutes

A simple setup path for agencies integrating with n8n, Make, Zapier, or internal systems.

Step 1

Generate a token

Open Integrations in your workspace and generate an API access token.

Step 2

List products

Call `GET /api/v1/products` and select the target `product_id`.

Step 3

Call `/api/v1/query`

Send a POST request with an `operation` name and validated input.

Step 4

Use the response

Use the outputs to automate reporting and execution workflows.

List Products (cURL)

curl -X GET https://<your-domain>/api/v1/products \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Quick Query (cURL)

curl -X POST https://<your-domain>/api/v1/query \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "get_product_context",
    "input": { "product_id": "00000000-0000-0000-0000-000000000000" }
  }'

API Reference

Request Format, Operations, and Responses

All query calls use one endpoint with operation-dispatched inputs and outputs.

Endpoints

GET  https://<your-domain>/api/v1/products
POST https://<your-domain>/api/v1/query
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

list_products

GET /api/v1/products

Returns all products available for the agency linked to the bearer token.

cURL

curl -X GET https://<your-domain>/api/v1/products \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Response

{
  "ok": true,
  "agency_id": "uuid",
  "products": [
    {
      "id": "uuid",
      "name": "Acme",
      "website_url": "https://acme.com",
      "normalized_domain": "acme.com",
      "status": "active",
      "created_at": "2026-03-01T10:00:00.000Z",
      "updated_at": "2026-03-04T12:00:00.000Z"
    }
  ]
}

get_product_context

POST /api/v1/query

Returns core product metadata and analysis context.

Input

{
  "product_id": "uuid"
}

Output

{
  "ok": true,
  "operation": "get_product_context",
  "result": { "product": { "id": "...", "name": "...", "website_url": "..." } }
}

get_visibility_snapshot

POST /api/v1/query

Returns visibility summary, LLM segmentation, and prompt-level rows.

Input

{
  "product_id": "uuid",
  "from": "2026-03-01T00:00:00.000Z",
  "to": "2026-03-04T23:59:59.999Z",
  "llms": ["chatgpt", "gemini", "perplexity"]
}

Output

{
  "ok": true,
  "operation": "get_visibility_snapshot",
  "result": {
    "summary": { "visibility_score": 61.3, "answered_prompts": 42 },
    "by_llm": [{ "llm": "chatgpt", "visibility_score": 66.7 }],
    "prompts": [{ "question_id": "...", "llm": "chatgpt", "best_rank": 4 }]
  }
}

list_recommendations

POST /api/v1/query

Returns recommendation list and summary counts with optional filters.

Input

{
  "product_id": "uuid",
  "status": "open",
  "limit": 20
}

Output

{
  "ok": true,
  "operation": "list_recommendations",
  "result": {
    "summary": { "total": 23, "open": 9, "in_progress": 8, "done": 6 },
    "recommendations": [{ "recommendation_key": "...", "status": "open" }]
  }
}

JavaScript Example

const res = await fetch("https://<your-domain>/api/v1/query", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CITEMIND_API_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    operation: "list_recommendations",
    input: { product_id: "<uuid>", status: "open", limit: 20 },
  }),
});

const data = await res.json();

Common Errors

401 Unauthorized: missing bearer token

403 Forbidden: revoked/expired token, invalid scope

400 Bad request: invalid input for selected operation

404 Product not found in your agency