API Reference

Base URL: https://citedmonitor.com/api/v1

Authentication

All requests require a Bearer token. Create API keys in Settings → Developer API. API access is available on Growth and Pro plans.

Request
curl https://citedmonitor.com/api/v1/brands \
  -H "Authorization: Bearer cm_live_your_api_key_here"

Error responses

Error format
{
  "error": "Authentication required. Provide a Bearer token."
}
StatusMeaning
401Missing or invalid API key
403API access not available on your plan
404Resource not found
422Validation error
429Rate limit exceeded

Rate limiting

Requests are rate limited per team. Check response headers: X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After.

Brands

GET /api/v1/brands

Returns all entities (brands, products, competitors) tracked by your team.

Parameters

own_onlybooleanOnly return your own brands
favourites_onlybooleanOnly return favourited entities
cursorstringPagination cursor
Request
curl https://citedmonitor.com/api/v1/brands?own_only=1 \
  -H "Authorization: Bearer cm_live_abc123"
Response — 200
{
  "data": [
    {
      "id": 1,
      "name": "Acme Hotels",
      "slug": "acme-hotels",
      "domain": "acmehotels.com",
      "is_own_brand": true,
      "is_favourite": false,
      "entity_type": "business",
      "entity_subtype": "hotel",
      "schedule": "weekly",
      "first_seen_at": "2026-06-01T10:00:00.000000Z",
      "aliases": [
        { "id": 1, "alias": "Acme Hotel Group" }
      ]
    }
  ],
  "meta": {
    "next_cursor": null,
    "has_more": false
  }
}
GET /api/v1/brands/{id}/mentions

Returns every time a brand was mentioned in an AI response.

Parameters

sincedatetimeOnly return mentions after this date (ISO 8601)
sentimentstringpositive negative neutral
cursorstringPagination cursor
Response — 200
{
  "data": [
    {
      "id": 284,
      "prompt_run_id": 91,
      "entity_id": 1,
      "entity_type": "business",
      "position": 2,
      "sentiment": "positive",
      "context_snippet": "Acme Hotels in Bakewell offers a modern boutique experience...",
      "confidence": 0.95,
      "created_at": "2026-06-13T14:22:00.000000Z",
      "prompt_run": {
        "id": 91,
        "model": "gpt-4o",
        "provider": { "id": 1, "name": "OpenAI", "slug": "openai" },
        "prompt": { "id": 12, "body": "Best boutique hotels in the Peak District" }
      }
    }
  ],
  "meta": {
    "next_cursor": "eyJpZCI6MjgzfQ",
    "has_more": true
  }
}
GET /api/v1/brands/{id}/citations

Returns URLs cited alongside a brand in AI responses.

Parameters

sincedatetimeOnly return citations after this date
domainstringFilter by cited domain
cursorstringPagination cursor
Response — 200
{
  "data": [
    {
      "id": 55,
      "prompt_run_id": 91,
      "entity_id": 1,
      "url": "https://acmehotels.com/bakewell",
      "domain": "acmehotels.com",
      "created_at": "2026-06-13T14:22:00.000000Z",
      "prompt_run": {
        "id": 91,
        "model": "sonar-pro",
        "provider": { "id": 6, "name": "Perplexity", "slug": "perplexity" },
        "prompt": { "id": 12, "body": "Best boutique hotels in the Peak District" }
      }
    }
  ],
  "meta": { "next_cursor": null, "has_more": false }
}

Prompts

GET /api/v1/prompts

Returns all prompts configured for your team.

Response — 200
{
  "data": [
    {
      "id": 12,
      "entity_id": 1,
      "body": "What are the best boutique hotels in the Peak District?",
      "is_active": true,
      "created_at": "2026-06-01T10:30:00.000000Z",
      "entity": {
        "id": 1,
        "name": "Acme Hotels",
        "is_own_brand": true
      }
    }
  ],
  "meta": { "next_cursor": null, "has_more": false }
}
POST /api/v1/prompts

Create a new monitoring prompt. Subject to your plan's prompt limit.

Body parameters

bodystringrequiredThe prompt text (max 1000 chars)
entity_idintegerrequiredThe brand this prompt monitors
schedulestringrequireddaily weekly manual
Request
curl -X POST https://citedmonitor.com/api/v1/prompts \
  -H "Authorization: Bearer cm_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "What are the best boutique hotels in the Peak District?",
    "entity_id": 1,
    "schedule": "weekly"
  }'
Response — 201 Created
{
  "data": {
    "id": 13,
    "entity_id": 1,
    "body": "What are the best boutique hotels in the Peak District?",
    "schedule": "weekly",
    "is_active": true,
    "created_at": "2026-06-14T09:15:00.000000Z"
  }
}
GET /api/v1/prompts/{id}/runs

Returns run history for a prompt, including extracted entities and citations.

Response — 200
{
  "data": [
    {
      "id": 91,
      "prompt_id": 12,
      "model": "gpt-4o",
      "status": "completed",
      "token_count_input": 42,
      "token_count_output": 856,
      "estimated_cost": 0.0034,
      "created_at": "2026-06-13T14:22:00.000000Z",
      "provider": { "id": 1, "name": "OpenAI", "slug": "openai" },
      "mentions": [
        {
          "entity": { "id": 1, "name": "Acme Hotels" },
          "position": 2,
          "sentiment": "positive",
          "confidence": 0.95
        },
        {
          "entity": { "id": 7, "name": "The Peacock at Rowsley" },
          "position": 1,
          "sentiment": "positive",
          "confidence": 0.92
        }
      ],
      "citations": [
        {
          "url": "https://acmehotels.com/bakewell",
          "domain": "acmehotels.com"
        }
      ]
    }
  ],
  "meta": { "next_cursor": null, "has_more": false }
}
POST /api/v1/prompts/{id}/run

Trigger a prompt run. Dispatched asynchronously to all configured models.

Request
curl -X POST https://citedmonitor.com/api/v1/prompts/12/run \
  -H "Authorization: Bearer cm_live_abc123"
Response — 200
{
  "message": "Prompt run dispatched."
}

Results arrive asynchronously. Poll the runs endpoint or use webhooks to be notified.

Reports

GET /api/v1/reports/share-of-voice

Returns share of voice for all entities across your runs.

Parameters

daysintegerLookback period in days (default: 30)
provider_idintegerFilter to a specific provider
Response — 200
{
  "data": [
    {
      "entity": {
        "id": 7,
        "name": "The Peacock at Rowsley",
        "domain": null,
        "is_own_brand": false,
        "is_favourite": true
      },
      "run_count": 32,
      "mention_count": 38,
      "share_of_voice": 68.09
    },
    {
      "entity": {
        "id": 1,
        "name": "Acme Hotels",
        "domain": "acmehotels.com",
        "is_own_brand": true,
        "is_favourite": false
      },
      "run_count": 24,
      "mention_count": 28,
      "share_of_voice": 51.06
    }
  ],
  "meta": { "total_runs": 47, "days": 30, "provider_id": null }
}