REST API v1

The citepath REST API lets you trigger scans and read brand analytics from your own tooling. Every endpoint lives under /api/v1, speaks JSON, and requires a per-account API key. API access is included on the Growth plan and above.

Creating an API key

Sign in and open Settings → API keys (or POST /api/keys with a { "name" } body from an authenticated session). Keys are prefixed cp_live_ in production and cp_test_ elsewhere. The full key is shown exactly once — store it somewhere safe, because only its SHA-256 hash is kept on our side. Revoke a key any time from the same screen or via DELETE /api/keys/{id}.

Authentication

Send the key as a Bearer token on every request. Requests without a valid, unrevoked key get 401; keys whose account lacks the Growth plan get 403.

curl https://citepath.app/api/v1/scans \
  -H "Authorization: Bearer cp_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"domain": "yourbrand.com"}'

Endpoints

• POST /api/v1/scans — start a scan. Body: { "domain": "example.com" } or { "brandId": "<uuid>" } (the brand must belong to your account). Returns 201 with the scan object; the scan runs asynchronously.
• GET /api/v1/scans/{id} — poll a scan you own. status moves pending → complete | failed; shareOfAnswer populates on completion.
• GET /api/v1/brands/{id}/share-of-answer — latest Share of Answer summary (overallCitedRatio, per-engine stats, competitor frequency) plus a trend of recent scans.
• GET /api/v1/brands/{id}/opportunities — backlink and citation opportunities ranked for the brand.

Example: create and poll a scan

# create
curl -X POST https://citepath.app/api/v1/scans \
  -H "Authorization: Bearer cp_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"brandId": "8f9f…-your-brand-uuid"}'
# → {"scan": {"id": "…", "status": "pending", …}}

# poll
curl https://citepath.app/api/v1/scans/<scan-id> \
  -H "Authorization: Bearer cp_live_xxxxxxxx"
# → {"scan": {"id": "…", "status": "complete", "shareOfAnswer": {…}}}

Rate limits and plan gating

• 120 requests per minute per API key across all /api/v1 endpoints.
• Scan creation additionally consumes your plan's scansPerHour budget (20/hour on Growth, 100/hour on Enterprise).
• API keys require the Growth plan or above — authenticated requests on lower plans return 403 plan_required.

Errors

Errors share one envelope so you can branch on code:

{ "error": { "code": "rate_limited", "message": "Rate limit exceeded — 120 requests per minute per key" } }

• 401 unauthorized — missing/malformed Bearer header
• 401 invalid_api_key — unknown or revoked key
• 403 plan_required — plan without API access
• 429 rate_limited — per-key or per-plan limit hit
• 400 bad_request — invalid JSON payload
• 404 not_found — the id doesn't exist on your account (other accounts' ids are 404, never 403)

The machine-readable OpenAPI document is at /openapi.json, and the same capabilities are exposed to agents over MCP at /api/mcp. Questions: support@citepath.app.