Your visibility data,
in your own stack.
The CiteSurge API gives agencies and enterprises programmatic access to everything the dashboard shows: scores, citations, mentions, findings, and board-ready reports — plus audit triggers and signed webhooks so your reporting pipeline stays current without polling.
The full machine-readable specification lives at /api/v1/openapi.json (OpenAPI 3.1). Import it into Postman, Insomnia, or your generator of choice. API access is included on every paid plan — Pro, Agency, and Enterprise — and turns on automatically once your account has a paid project. Working inside Claude Code, Claude Desktop, or Cursor? The same data is available over the CiteSurge MCP server.
Authentication
Account owners create API keys in Settings → API access. Each key has a role — read-only, or read and trigger audits — and can be scoped to specific projects. The full key is shown once at creation; only a fingerprint is stored. Send it on every request:
Authorization: Bearer cs_live_...Keys can be revoked instantly from the same settings page. Revoked and expired keys stop working immediately.
Endpoints
GET /api/v1/projects
Projects visible to the key, with the latest completed audit summary.
POST /api/v1/projects
Create a project (agencies onboarding clients programmatically).
GET /api/v1/projects/{slug}
Project detail with current scores and deltas.
GET /api/v1/projects/{slug}/score-history
Scores over time, newest first.
GET /api/v1/projects/{slug}/citations
Sources AI answers cited, with domain ownership flags.
GET /api/v1/projects/{slug}/mentions
Brand and competitor mentions inside AI answers.
GET /api/v1/projects/{slug}/findings
Prioritized recommendations from an audit.
GET /api/v1/projects/{slug}/report
The client audit report as Markdown.
GET /api/v1/projects/{slug}/report.pdf
The client audit report as a PDF.
POST /api/v1/projects/{slug}/audits
Trigger an audit; returns a run id to poll.
GET /api/v1/audit-runs/{id}
Poll an audit run's status and scores.
List endpoints use cursor pagination: pass the previous response's nextCursor as cursor until it returns null. Time-series endpoints accept from and to timestamps, and engine-level data can be filtered with engine.
Rate limits and usage
Reads are limited to 60 requests per minute per key, writes to 10 per minute. A 429 response carries a Retry-After header. Audits can be requested at most once per hour per project, and audit requests are refused while a project is at its plan's usage cap — the API never spends beyond what your plan already allows.
Webhooks
Instead of polling, register a webhook endpoint in Settings → API access. CiteSurge sends audit_run.completed and audit_run.failed events with the run id, project, and overall score; fetch detail through the API. Every delivery is signed. The X-CiteSurge-Signature header has the form t=<unix>,v1=<hex>, where v1 is the HMAC-SHA256 of <t>.<raw body> using your endpoint's signing secret. Reject deliveries whose timestamp is older than five minutes or whose signature does not match. Endpoints that keep failing are paused automatically and can be re-enabled from settings.
Errors
Errors return JSON with a stable error code: 401 for key problems, 403 for disabled API access or insufficient role, 404 for anything outside the key's project scope, 429 for limits, and 5xx when something failed on our side. Error bodies never include internal details.