API reference · v1 · Team tier and above

API reference.

The CitationDesk public API gives you programmatic access to citation events, Citation Readiness Scores, test queries, and webhook subscriptions. Available on Team tier (€149/mo) and Enterprise. This page is the canonical reference — endpoint shapes, auth model, rate limits, example payloads.

Base URL + versioning

https://citationdesk.com/api/v1

API is versioned via URL prefix. Breaking changes go in a new major version with parallel availability for ≥12 months. Backwards-compatible changes (new fields on response objects, new optional query params) ship within v1.

Authentication

All requests authenticate via an API key in the Authorization header. Generate keys from the Team tier dashboard at /settings/api-keys (Phase 1B):

Authorization: Bearer cd_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

API keys are scope-restricted (read-only / read-write / webhook-management). Keys are bound to a single Team-tier account; cross-account use returns 403.

Rate limits

• Pro tier: API not available (upgrade to Team).
• Team tier: 600 requests / minute, 30,000 requests / day.
• Enterprise: custom — talk to us.

Rate-limit headers ship on every response: X-RateLimit-Limit, X-RateLimit-Remaining,X-RateLimit-Reset. Exceeding the limit returns 429 with a retry-after header.

Endpoints

GET /api/v1/sites

List sites the API key has access to.

{
  "data": [
    {
      "id": "site_01H8K2QXYZRG7A",
      "domain": "example.com",
      "archetype": "publisher",
      "status": "active",
      "created_at": "2026-04-15T08:42:00Z",
      "last_polled_at": "2026-05-19T04:00:00Z",
      "queries_count": 47,
      "citation_count_7d": 13,
      "citation_count_30d": 58,
      "citation_readiness_score": 67
    }
  ],
  "meta": { "total": 12, "page": 1, "per_page": 50 }
}

GET /api/v1/sites/{id}/citations

List citation events for a site. Query params: window (7d / 30d / 90d / all), llm(chatgpt / claude / perplexity / gemini), cited (true / false).

{
  "data": [
    {
      "id": "cite_01H8K9XYZRG7B",
      "site_id": "site_01H8K2QXYZRG7A",
      "query": "What is sourdough hydration?",
      "llm": "perplexity",
      "model_version": "sonar-pro-2026-05",
      "polled_at": "2026-05-18T04:00:23Z",
      "cited": true,
      "url": "https://example.com/sourdough-hydration/",
      "position_in_response": 1,
      "paragraph_quoted": "Sourdough hydration is calculated as water weight divided by flour weight times 100...",
      "competitors_also_cited": [
        "https://kingarthurbaking.com/...",
        "https://breadbakers.org/..."
      ],
      "confidence": 0.95
    }
  ],
  "meta": { "total": 58, "page": 1, "per_page": 50, "window": "30d" }
}

GET /api/v1/sites/{id}/score

Latest Citation Readiness Score for the site (5-dimension breakdown + overall).

{
  "data": {
    "site_id": "site_01H8K2QXYZRG7A",
    "overall": 67,
    "dimensions": {
      "seo_foundation": 0.81,
      "geo_readiness": 0.62,
      "dual_fit": 0.58,
      "entity_coherence": 0.55,
      "bot_crawl_health": 0.88
    },
    "computed_at": "2026-05-19T04:00:00Z",
    "highest_leverage_fix": "Rewrite first paragraph of top-traffic page to lead with a fact-shaped sentence."
  }
}

POST /api/v1/sites/{id}/queries

Add a test query for a site.

POST /api/v1/sites/site_01H8K2QXYZRG7A/queries
Authorization: Bearer cd_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "query_text": "What is the best sourdough hydration for beginners?",
  "archetype_relevance": "definitional",
  "expected_topic": "sourdough hydration calculator"
}

{
  "data": {
    "id": "query_01H8KAZXYZRG7C",
    "site_id": "site_01H8K2QXYZRG7A",
    "query_text": "What is the best sourdough hydration for beginners?",
    "archetype_relevance": "definitional",
    "expected_topic": "sourdough hydration calculator",
    "created_at": "2026-05-19T20:15:42Z",
    "last_polled_at": null
  }
}

Webhooks

Subscribe to citation events as they happen. Configure webhook URLs from the dashboard at/settings/webhooks. CitationDesk POSTs JSON to your URL with the following event types:

• citation.gained — a query newly returned a citation pointing at one of your tracked URLs
• citation.lost — a query that previously cited you no longer does
• citation.decay — a previously-cited URL stops being cited for 3 consecutive polls
• score.dropped — Citation Readiness Score for a site dropped >0.1 since last computation
• competitor.displaced — a query that cited you now cites a specific competitor instead

Example payload (citation.gained):

POST [your webhook URL]
Content-Type: application/json
X-CitationDesk-Signature: sha256=<HMAC of payload using webhook secret>
X-CitationDesk-Event: citation.gained

{
  "id": "evt_01H8KBZXYZRG7D",
  "event": "citation.gained",
  "site_id": "site_01H8K2QXYZRG7A",
  "site_domain": "example.com",
  "occurred_at": "2026-05-19T04:00:23Z",
  "data": {
    "query": "What is sourdough hydration?",
    "llm": "perplexity",
    "url": "https://example.com/sourdough-hydration/",
    "paragraph_quoted": "Sourdough hydration is calculated as...",
    "position_in_response": 1
  }
}

Webhook delivery: at-least-once. Verify signature against your webhook secret + reject duplicates by theid field. Failed deliveries retry exponentially for 24 hours.

Error format

{
  "error": {
    "code": "not_yet_available",
    "message": "CitationDesk API ships in Phase 1B. Subscribe to /changelog for release notice.",
    "documentation_url": "https://citationdesk.com/api/docs/"
  }
}

SDKs (planned)

• TypeScript / JavaScript — npm i @citationdesk/sdk (Phase 1B)
• Python — pip install citationdesk (Phase 1B)
• Go — go get github.com/citationdesk/sdk-go (Phase 1C)

Status + uptime

API status is reported at citationdesk.com/status. Team tier targets 99.5% availability; Enterprise customers get a contractual 99.9% SLA. Incident communication via the status page + email to API key owners.