API Reference

Authentication

All API requests require an API key. Generate one in your dashboard under Settings > API Keys.

Include the key in the Authorization header:

curl https://app.citedspy.com/api/v1/brands \
  -H "Authorization: Bearer cspy_your_api_key_here"

API keys are prefixed with cspy_ for easy identification. Each key is scoped to a single workspace - all data returned is automatically filtered to that workspace.

Errors

CitedSpy uses standard HTTP status codes. All error responses follow this format:

{
  "error": "Description of what went wrong"
}

Rate Limits

API requests are limited to 100 requests per minute per API key. Rate limit information is included in response headers:

When you exceed the limit, the API returns a 429 response with a message indicating when you can retry.

Pagination

List endpoints support pagination via limit and offset query parameters:

Paginated responses include a pagination object:

{
  "data": [...],
  "pagination": {
    "limit": 50,
    "offset": 0
  }
}

Brands

Response

{
  "data": [
    {
      "id": "uuid",
      "name": "My Brand",
      "domain": "mybrand.com",
      "category": "SaaS",
      "description": "Project management tool",
      "aliases": ["MyBrand", "MB"],
      "owned_domains": ["mybrand.com", "mybrand.io"],
      "logo_url": "https://assets.citedspy.com/brands/...",
      "created_at": "2026-05-01T00:00:00.000Z",
      "updated_at": "2026-05-10T12:00:00.000Z"
    }
  ]
}

Path parameters

Response

{
  "data": {
    "id": "uuid",
    "name": "My Brand",
    "domain": "mybrand.com",
    "category": "SaaS",
    "description": "Project management tool",
    "aliases": ["MyBrand", "MB"],
    "competitors": [
      { "id": "uuid", "name": "Competitor A", "domain": "competitor-a.com" }
    ],
    "prompt_count": 12
  }
}

Prompts

Query parameters

Response

{
  "data": [
    {
      "id": "uuid",
      "brand_id": "uuid",
      "text": "What is the best project management tool?",
      "category": "comparison",
      "status": "active",
      "tags": ["productivity", "tools"],
      "created_at": "2026-05-01T00:00:00.000Z"
    }
  ],
  "pagination": { "limit": 100, "offset": 0 }
}

Response

{
  "data": {
    "id": "uuid",
    "brand_id": "uuid",
    "text": "What is the best project management tool?",
    "category": "comparison",
    "status": "active",
    "tags": ["productivity"],
    "run_count": 45,
    "created_at": "2026-05-01T00:00:00.000Z"
  }
}

Request body

Example

curl -X POST https://app.citedspy.com/api/v1/prompts \
  -H "Authorization: Bearer cspy_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "brand_id": "abc-123",
    "text": "What are the top CRM tools for small business?",
    "category": "comparison",
    "tags": ["crm", "small-business"]
  }'

Response (201)

{
  "data": {
    "id": "new-uuid",
    "brand_id": "abc-123",
    "text": "What are the top CRM tools for small business?",
    "category": "comparison",
    "status": "active",
    "tags": ["crm", "small-business"],
    "created_at": "2026-05-17T10:00:00.000Z"
  }
}

Request body (all fields optional)

Response

{ "success": true }

Runs

Query parameters

Response

{
  "data": [
    {
      "id": "uuid",
      "prompt_id": "uuid",
      "engine_id": "uuid",
      "engine_name": "ChatGPT",
      "status": "completed",
      "scheduled_at": "2026-05-17T08:00:00.000Z",
      "completed_at": "2026-05-17T08:00:03.200Z",
      "raw_response_text": "Based on my research, the top project...",
      "token_cost_usd": 0.0034
    }
  ],
  "pagination": { "limit": 50, "offset": 0 }
}

Response

{
  "data": {
    "id": "uuid",
    "prompt_id": "uuid",
    "engine_id": "uuid",
    "engine_name": "Perplexity",
    "status": "completed",
    "raw_response_text": "Here are the top tools...",
    "token_cost_usd": 0.0021,
    "citations": [
      {
        "id": "uuid",
        "url": "https://mybrand.com/features",
        "domain": "mybrand.com",
        "position_in_response": 2,
        "snippet": "MyBrand offers advanced analytics..."
      }
    ],
    "mentions": [
      {
        "id": "uuid",
        "brand_or_competitor_id": "uuid",
        "entity_type": "brand",
        "sentiment": "positive",
        "snippet": "MyBrand is highly recommended for...",
        "position_in_response": 1
      }
    ]
  }
}

Request body

Example

curl -X POST https://app.citedspy.com/api/v1/runs/trigger \
  -H "Authorization: Bearer cspy_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt_id": "abc-123",
    "engines": ["ChatGPT", "Perplexity"]
  }'

Response

{
  "data": {
    "runs": [
      { "run_id": "uuid", "engine": "ChatGPT", "status": "completed" },
      { "run_id": "uuid", "engine": "Perplexity", "status": "completed" }
    ],
    "completed": 2,
    "failed": 0,
    "total": 2
  }
}

Competitors

Query parameters

Response

{
  "data": [
    {
      "id": "uuid",
      "brand_id": "uuid",
      "name": "Competitor A",
      "domain": "competitor-a.com",
      "aliases": ["CompA", "Comp-A"],
      "category": "SaaS",
      "description": "A competing product",
      "created_at": "2026-05-01T00:00:00.000Z"
    }
  ]
}

Dashboard

Path parameters

Query parameters

Response

{
  "data": {
    "brand_id": "uuid",
    "snapshot_date": "2026-05-17",
    "computed_at": "2026-05-17T06:00:00.000Z",
    "mention_rate": 72,
    "mention_rate_delta": 5,
    "avg_position": 2.3,
    "avg_position_delta": -0.4,
    "share_of_voice": 34,
    "share_of_voice_delta": 2,
    "prompts_tracked": 25,
    "sentiment_score": 0.78,
    "total_runs": 150,
    "total_mentions": 108,
    "engine_breakdown": [
      { "engine": "ChatGPT", "mention_rate": 80, "avg_position": 1.8 },
      { "engine": "Perplexity", "mention_rate": 65, "avg_position": 3.1 }
    ],
    "competitor_stats": [
      { "name": "Competitor A", "mention_rate": 45, "share_of_voice": 22 }
    ],
    "top_citations": [
      { "domain": "mybrand.com", "count": 34, "url": "https://mybrand.com/features" }
    ],
    "trend_data": [
      { "date": "2026-05-10", "mention_rate": 68, "position": 2.5 },
      { "date": "2026-05-11", "mention_rate": 70, "position": 2.4 }
    ]
  }
}

Metrics explained

Citations

Query parameters

Response

{
  "data": [
    {
      "id": "uuid",
      "run_id": "uuid",
      "url": "https://mybrand.com/blog/guide",
      "domain": "mybrand.com",
      "position_in_response": 1,
      "snippet": "According to MyBrand's guide..."
    }
  ],
  "pagination": { "limit": 50, "offset": 0 }
}

Mentions

Query parameters

Response

{
  "data": [
    {
      "id": "uuid",
      "run_id": "uuid",
      "brand_or_competitor_id": "uuid",
      "entity_type": "brand",
      "sentiment": "positive",
      "snippet": "MyBrand is one of the leading solutions for...",
      "position_in_response": 2
    }
  ],
  "pagination": { "limit": 50, "offset": 0 }
}

Sentiment values

Engines

Response

{
  "data": [
    { "id": "uuid", "name": "ChatGPT", "available": true },
    { "id": "uuid", "name": "Perplexity", "available": true },
    { "id": "uuid", "name": "Gemini", "available": true },
    { "id": "uuid", "name": "Claude", "available": true },
    { "id": "uuid", "name": "Copilot", "available": false }
  ]
}

The available field indicates whether the engine is currently configured and ready to accept runs on your workspace.