REST API v1Agency Ready

CiteMind API Documentation

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

Getting Started API ReferenceOAuth Required

Getting Started

Go Live in 5 Minutes

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

Step 1

Authenticate via OAuth

Complete OAuth 2.1 Authorization Code + PKCE and use the resulting bearer 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_OAUTH_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Quick Query (cURL)

curl -X POST https://<your-domain>/api/v1/query \
  -H "Authorization: Bearer YOUR_OAUTH_ACCESS_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_OAUTH_ACCESS_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_OAUTH_ACCESS_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_OAUTH_ACCESS_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