API Documentation

Access your CiteHawk data programmatically. All endpoints use REST conventions and return JSON.

Authentication

All API requests require an API key passed in the Authorization header.

Authorization: Bearer YOUR_API_KEY

Generate API keys in Settings > API Keys within your workspace.

All requests without a valid API key return 401 Unauthorized. Expired and revoked keys are treated identically. Requests are rate-limited per key.

Keys can optionally be created with an expiry (30 days, 90 days, or 1 year) and restricted to specific scopes (read:scores, read:metrics, read:brands, read:responses, write:prospect-scans). A key with no scopes selected has full read access; calling an endpoint outside a key's scopes returns 403 Forbidden. The write:prospect-scans scope is never implied: it must be checked explicitly when the key is created. The MCP server is a full-access surface: connect it with an unscoped key (or OAuth); scoped keys are REST-only.

Base URL

https://www.citehawk.com/api/v1

Endpoints

GET/api/v1/brands

Returns all brands in your workspace.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://www.citehawk.com/api/v1/brands

{
  "brands": [
    {
      "id": "abc123",
      "name": "Acme Corp",
      "keywords": ["acme", "acme corporation"]
    }
  ],
  "workspaceId": "ws_123"
}

GET/api/v1/metrics

Returns visibility metrics and latest KPIs for your workspace.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://www.citehawk.com/api/v1/metrics?days=7"

{
  "timeseries": [
    {
      "date": "2026-07-06",
      "visibilityScore": 72,
      "citationCount": 15
    }
  ],
  "kpis": {
    "visibilityScore": 72,
    "citationCount": 145,
    "responseCount": 892
  },
  "days": 7
}

GET/api/v1/scores

Returns your latest Visibility and Brand Health scores plus their full history, the same canonical series the dashboard charts. Ideal for pulling CiteHawk scores into client dashboards or Looker Studio.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://www.citehawk.com/api/v1/scores?days=90"

{
  "latest": { "date": "2026-07-21", "visibility": 24, "brandHealth": 78 },
  "history": [
    {
      "date": "2026-07-21",
      "visibility": 24,
      "brandHealth": 78,
      "presence": 20.4,
      "authority": 4.8,
      "sentiment": 46.1,
      "accuracy": 32
    }
  ]
}

GET/api/v1/responses

Returns recent AI platform responses mentioning your brands.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://www.citehawk.com/api/v1/responses?limit=10&offset=0"

{
  "responses": [
    {
      "id": "resp_123",
      "provider": "chatgpt",
      "model": "gpt-4o",
      "responseText": "According to Acme Corp...",
      "citations": ["https://acme.com/about"]
    }
  ],
  "total": 892
}

Prospect scans (Agency plan)

Run the full AI-visibility audit headlessly from your own site or app: start a scan against a prospect's domain, then poll for the result or receive a signed webhook. Each scan runs the same engine as the dashboard's prospect audits and consumes one prospect-audit slot from the same allowance (included monthly audits first, then purchased credits). Requires an Agency plan and an API key with the write:prospect-scans scope; other keys receive 403 Forbidden.

Repeat targets are cached: a scan of the same domain within 7 days returns the existing scan with "cached": true and consumes nothing.

POST/api/v1/prospect-scans

Starts a prospect scan. Returns immediately; scans take a few minutes.

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target_url": "prospect.com", "lead": {"email": "owner@prospect.com"}, "webhook_url": "https://youragency.com/hooks/citehawk"}' \
  https://www.citehawk.com/api/v1/prospect-scans

{
  "scan_id": "5f0c9f6e-...",
  "status": "queued",
  "cached": false
}

{
  "scan_id": "5f0c9f6e-...",
  "status": "complete",
  "cached": true,
  "report_url": "https://youragency.citehawk.com/report/..."
}

Cached responses never fire a webhook: the answer is inline, or (for a still-running cached scan) polled via the endpoint below. Additional error statuses: 402 when the monthly allowance and credits are exhausted, 403 for plan or scope, 422 for an invalid body, 429 for daily, concurrent, or per-target limits.

GET/api/v1/prospect-scans/:id

Status and results for a scan. Requires the same write scope as the POST.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://www.citehawk.com/api/v1/prospect-scans/5f0c9f6e-...

{
  "scan_id": "5f0c9f6e-...",
  "target_domain": "prospect.com",
  "brand": "Prospect Inc",
  "status": "complete",
  "pct": 100,
  "created_at": "2026-08-18T09:00:00.000Z",
  "completed_at": "2026-08-18T09:07:42.000Z",
  "report_url": "https://youragency.citehawk.com/report/...",
  "summary": {
    "visibility_score": 34,
    "engine_count": 8,
    "category_rank": 4,
    "mention_rate_pct": 22.5,
    "battleground": { "won": 6, "contested": 11, "lost": 28, "total": 45 },
    "geo_audit": { "score": 61, "grade": "C" }
  }
}

status is one of queued, running, complete, or failed; pct is coarse 0-100 progress. report_url is the hosted white-label report on your branded domain: share it with the prospect as-is.

Webhooks

When a scan you created with a webhook_url completes or fails, CiteHawk POSTs a JSON payload to that URL:

{
  "event": "prospect_scan.completed",
  "scan_id": "5f0c9f6e-...",
  "target_domain": "prospect.com",
  "brand": "Prospect Inc",
  "status": "complete",
  "report_url": "https://youragency.citehawk.com/report/...",
  "summary": { "visibility_score": 34, "engine_count": 8 },
  "created_at": "2026-08-18T09:00:00.000Z",
  "completed_at": "2026-08-18T09:07:42.000Z"
}

Events are prospect_scan.completed and prospect_scan.failed (failed payloads carry an error instead of report_url and summary). Deliveries are retried on failure.

Every delivery is signed. The X-CiteHawk-Signature header has the form t=<unix seconds>,v1=<hex> where v1 is an HMAC-SHA256 of `${t}.${rawBody}`. The signing secret is the SHA-256 hex digest of your API key: compute it once on your side and verify each delivery.

const crypto = require('crypto')

const secret = crypto.createHash('sha256').update(process.env.CITEHAWK_API_KEY).digest('hex')
const [tPart, v1Part] = signatureHeader.split(',')
const t = tPart.slice(2)
const expected = crypto.createHmac('sha256', secret).update(t + '.' + rawBody).digest('hex')
const valid = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1Part.slice(3)))

MCP server (connect your own AI)

CiteHawk ships a Model Context Protocol server so you can connect your own AI client and ask it about your AI visibility. Works with Claude Code, the Claude desktop and web apps (custom connectors), Cursor, and any MCP client that supports streamable HTTP.

https://www.citehawk.com/api/mcp

Authentication is the same workspace API key used above, passed as a Bearer token. Generate one in Settings > API Keys.

claude mcp add --transport http citehawk https://www.citehawk.com/api/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Claude.ai / Claude Desktop

Add a custom connector pointing at https://www.citehawk.com/api/mcp and set the Authorization: Bearer YOUR_API_KEY header.

Available tools

Every tool is read-only and scoped to the workspace the API key belongs to. A missing or invalid key returns 401 Unauthorized.

Rate limits

API requests are rate-limited to ensure fair usage. If you exceed the limit, you will receive a 429 Too Many Requests response.

Error codes