API reference · v1

API reference.

This page is the full design reference for the API CitationDesk drafted for programmatic access to citation events, Citation Readiness Scores, test queries, and webhook subscriptions — endpoint shapes, auth model, rate limits, and example payloads. None of it was ever shipped; the document stays online because the shapes are still the clearest statement of how the data is modelled.

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)

So why is there no API?

Because the thing an API would serve — continuous, per-query citation monitoring across four LLMs — is the one part of CitationDesk that costs real money to run, and the free tools are deliberately not funded by it. The audit and generator tools stay free and unmetered precisely because they need no keys, no accounts, and no per-call budget: every one of them runs a single server-side fetch of a page you already own.

Where continuous monitoring is genuinely what you need, the honest answer is a dedicated platform that already runs that infrastructure, not a version of it bolted onto a free tool. The paid product CitationDesk does offer — the weekly Pro report — is delivered as an email, not an endpoint.

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.