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"

Pagination

List endpoints use cursor-based pagination. Pass ?cursor=... to fetch the next page.

Response structure

{
  "data": [...],
  "meta": {
    "next_cursor": "eyJpZCI6NDJ9",
    "has_more": true
  }
}

Error responses

Error format

{
  "error": "Authentication required. Provide a Bearer token."
}

Status	Meaning
401	Missing or invalid API key
403	API access not available on your plan
404	Resource not found
422	Validation error
429	Rate limit exceeded

Rate limiting

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

Resource IDs

All resource IDs in the API are opaque hash strings (e.g. yr3DL301), not sequential integers. Always use the id returned in API responses when constructing URLs or referencing resources.

Foreign key fields such as entity_id, prompt_id, and prompt_run_id also use hash IDs. Do not assume any ordering or structure from these values.

Brands

GET /api/v1/brands

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

Parameters

own_only	boolean	Only return your own brands
favourites_only	boolean	Only return favourited entities
cursor	string	Pagination cursor

Request

curl https://citedmonitor.com/api/v1/brands?own_only=1 \
  -H "Authorization: Bearer cm_live_abc123"

Response — 200

{
  "data": [
    {
      "id": "yr3DL301",
      "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": "pW4xJ8Tn", "alias": "Acme Hotel Group" }
      ]
    }
  ],
  "meta": {
    "next_cursor": null,
    "has_more": false
  }
}

POST /api/v1/brands

Create a new brand or entity to monitor.

Body parameters

name	string	required	Brand name (max 255 chars)
domain	string	optional	Primary domain (e.g. acmehotels.com)
is_own_brand	boolean	optional	Whether this is your own brand
is_favourite	boolean	optional	Mark as favourite
entity_type	string	optional	e.g. business, competitor, influencer
entity_subtype	string	optional	e.g. hotel, restaurant, agency
schedule	string	optional	`daily` `weekly` `manual`

Request

curl -X POST https://citedmonitor.com/api/v1/brands \
  -H "Authorization: Bearer cm_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Hotels",
    "domain": "acmehotels.com",
    "is_own_brand": true,
    "entity_type": "business",
    "entity_subtype": "hotel",
    "schedule": "weekly"
  }'

Response — 201 Created

{
  "data": {
    "id": "yr3DL301",
    "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": null,
    "aliases": []
  }
}

GET /api/v1/brands/{id}

Returns a single brand by ID.

Response — 200

{
  "data": {
    "id": "yr3DL301",
    "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": "pW4xJ8Tn", "alias": "Acme Hotel Group" }
    ]
  }
}

PUT /api/v1/brands/{id}

Update an existing brand. Only include fields you want to change.

Body parameters

name	string	Brand name (max 255 chars)
domain	string	Primary domain
is_own_brand	boolean	Whether this is your own brand
is_favourite	boolean	Mark as favourite
entity_type	string	e.g. business, competitor, influencer
entity_subtype	string	e.g. hotel, restaurant, agency
schedule	string	`daily` `weekly` `manual`

Request

curl -X PUT https://citedmonitor.com/api/v1/brands/yr3DL301 \
  -H "Authorization: Bearer cm_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Hotels Group", "schedule": "daily" }'

Response — 200

{
  "data": {
    "id": "yr3DL301",
    "name": "Acme Hotels Group",
    "slug": "acme-hotels-group",
    "domain": "acmehotels.com",
    "is_own_brand": true,
    "is_favourite": false,
    "entity_type": "business",
    "entity_subtype": "hotel",
    "schedule": "daily",
    "first_seen_at": "2026-06-01T10:00:00.000000Z",
    "aliases": []
  }
}

DELETE /api/v1/brands/{id}

Delete a brand and all associated prompts, mentions, and citations. This action cannot be undone.

Request

curl -X DELETE https://citedmonitor.com/api/v1/brands/yr3DL301 \
  -H "Authorization: Bearer cm_live_abc123"

Response — 204 No Content

(empty response body)

GET /api/v1/brands/{id}/mentions

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

Parameters

since	datetime	Only return mentions after this date (ISO 8601)
sentiment	string	`positive` `negative` `neutral`
cursor	string	Pagination cursor

Response — 200

{
  "data": [
    {
      "id": "Qm5vHd9K",
      "prompt_run_id": "Kx9mBp2Q",
      "entity_id": "yr3DL301",
      "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": "Kx9mBp2Q",
        "model": "gpt-4o",
        "provider": { "id": "eDKQWMJ0", "name": "OpenAI", "slug": "openai" },
        "prompt": { "id": "aB3kM9Wx", "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

since	datetime	Only return citations after this date
domain	string	Filter by cited domain
cursor	string	Pagination cursor

Response — 200

{
  "data": [
    {
      "id": "Zt8wF3Lq",
      "prompt_run_id": "Kx9mBp2Q",
      "entity_id": "yr3DL301",
      "url": "https://acmehotels.com/bakewell",
      "domain": "acmehotels.com",
      "created_at": "2026-06-13T14:22:00.000000Z",
      "prompt_run": {
        "id": "Kx9mBp2Q",
        "model": "sonar-pro",
        "provider": { "id": "gH2jN5Yp", "name": "Perplexity", "slug": "perplexity" },
        "prompt": { "id": "aB3kM9Wx", "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": "aB3kM9Wx",
      "entity_id": "yr3DL301",
      "body": "What are the best boutique hotels in the Peak District?",
      "is_active": true,
      "created_at": "2026-06-01T10:30:00.000000Z",
      "entity": {
        "id": "yr3DL301",
        "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

body	string	required	The prompt text (max 1000 chars)
entity_id	string	required	Hash ID of the brand this prompt monitors

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": "yr3DL301"
  }'

Response — 201 Created

{
  "data": {
    "id": "cL6nP4Rs",
    "entity_id": "yr3DL301",
    "body": "What are the best boutique hotels in the Peak District?",
    "is_active": true,
    "created_at": "2026-06-14T09:15:00.000000Z"
  }
}

GET /api/v1/prompts/{id}

Returns a single prompt by ID, including its associated entity.

Response — 200

{
  "data": {
    "id": "aB3kM9Wx",
    "entity_id": "yr3DL301",
    "body": "What are the best boutique hotels in the Peak District?",
    "is_active": true,
    "created_at": "2026-06-01T10:30:00.000000Z",
    "entity": {
      "id": "yr3DL301",
      "name": "Acme Hotels",
      "is_own_brand": true
    }
  }
}

PUT /api/v1/prompts/{id}

Update an existing prompt. Only include fields you want to change.

Body parameters

body	string	The prompt text (max 1000 chars)
entity_id	string	Hash ID of a different brand to move prompt to
is_active	boolean	Enable or disable the prompt

Request

curl -X PUT https://citedmonitor.com/api/v1/prompts/aB3kM9Wx \
  -H "Authorization: Bearer cm_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{ "body": "Best luxury hotels in the Peak District?", "is_active": false }'

Response — 200

{
  "data": {
    "id": "aB3kM9Wx",
    "entity_id": "yr3DL301",
    "body": "Best luxury hotels in the Peak District?",
    "is_active": false,
    "created_at": "2026-06-01T10:30:00.000000Z",
    "entity": {
      "id": "yr3DL301",
      "name": "Acme Hotels",
      "is_own_brand": true
    }
  }
}

DELETE /api/v1/prompts/{id}

Delete a prompt and all associated run history. This action cannot be undone.

Request

curl -X DELETE https://citedmonitor.com/api/v1/prompts/aB3kM9Wx \
  -H "Authorization: Bearer cm_live_abc123"

Response — 204 No Content

(empty response body)

GET /api/v1/prompts/{id}/runs

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

Response — 200

{
  "data": [
    {
      "id": "Kx9mBp2Q",
      "prompt_id": "aB3kM9Wx",
      "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": "eDKQWMJ0", "name": "OpenAI", "slug": "openai" },
      "mentions": [
        {
          "entity": { "id": "yr3DL301", "name": "Acme Hotels" },
          "position": 2,
          "sentiment": "positive",
          "confidence": 0.95
        },
        {
          "entity": { "id": "Nk7qR2Vm", "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/aB3kM9Wx/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/trends

Returns daily mention counts over time, grouped by entity.

Parameters

days	integer	Lookback period in days (default: 30)
entity_id	string	Filter to a specific entity (hash ID, defaults to own brands)

Response — 200

{
  "data": [
    {
      "entity": { "id": "yr3DL301", "name": "Acme Hotels" },
      "data": [
        { "date": "2026-06-07", "mentions": 3 },
        { "date": "2026-06-08", "mentions": 5 },
        { "date": "2026-06-09", "mentions": 4 },
        { "date": "2026-06-10", "mentions": 6 },
        { "date": "2026-06-11", "mentions": 4 },
        { "date": "2026-06-12", "mentions": 7 },
        { "date": "2026-06-13", "mentions": 5 }
      ]
    }
  ],
  "meta": { "days": 7 }
}