API reference · v1 · not offered

API reference.

This page documents the API design CitationDesk drafted for programmatic access to citation events, Citation Readiness Scores, test queries, and webhook subscriptions — endpoint shapes, auth model, rate limits, example payloads. It is kept online as a design reference.

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

The design called for an API key in the Authorization header. No keys were ever issued and there is no dashboard to issue them from:

Authorization: Bearer cd_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keys were designed to be scope-restricted (read-only / read-write / webhook-management) and bound to a single account, with cross-account use returning 403.

Rate limits

The drafted budget was 600 requests / minute and 30,000 requests / day per key. None of this is enforced today because the API is not running.

The design also specified rate-limit headers on every response (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) with a 429 plus retry-after on overage.

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 has no public API. This endpoint does not exist.",
    "documentation_url": "https://citationdesk.com/api/docs/"
  }
}

SDKs (planned)

• TypeScript / JavaScript — @citationdesk/sdk (never published)
• Python — citationdesk (never published)
• Go — github.com/citationdesk/sdk-go (never published)

Status + uptime

There is no API to report uptime for, and no SLA is offered. Operational status for what CitationDesk does run — the site and the free tools — is published at citationdesk.com/status.