Citare

Showing 25 of 59 from the live probe.

• Ping

  Smoke endpoint — confirms auth chain works Returns the authenticated user's id + plan + the scope the key carried for this call. Useful for verifying API key setup end-to-end. **HTTP:** `GET /api/v1/ping` **Scope:** `read:projects`

• Get Me

  Authenticated user + plan + project memberships Identity for the bearer token: user id, email, name, resolved plan (highest across all the user's projects), the calling key's metadata, and the list of projects the user is a member of with role. Use this on first API call to discover available project ids. **HTTP:** `GET /api/v1/account/me` **Scope:** `read:projects`

• List Projects

  List projects you have access to Every project the authed user is a member of, with role. Mirrors the dashboard's project switcher. **HTTP:** `GET /api/v1/projects` **Scope:** `read:projects`

• Get Project

  Project details by id or slug Single project with the caller's role. Returns 404 (not 403) when the user isn't a member — deliberately doesn't leak existence. **HTTP:** `GET /api/v1/projects/{projectId}` **Scope:** `read:projects` **Parameters:** - `projectId` (path) (required): Project UUID or slug. Slugs are accepted for ergonomics; the API normalizes to the canonical UUID internally.

• List Audits

  Audit history + latest result Latest completed audit (or null) + history. Failed runs filtered out by default; pass `?include_failed=true` to see them too. **Why filter:** the audit runner writes a row on every run, including failures (status='failed' + score=0). Defaulting to completed-only matches the dashboard's MetricsRow / Alerts / Report Builder reads. **HTTP:** `GET /api/v1/projects/{projectId}/audits` **Scope:** `read:audits` **Parameters:** - `projectId` (path) (required): Project UUID

• List Keywords

  Tracked keywords for the project Keywords the user has subscribed to daily rank snapshots for. `lastPosition` + `lastUrl` are denormalized for the list view; full rank history lives in `seo_daily_metrics` and will be exposed via `?include_history=true` in v1.5. **HTTP:** `GET /api/v1/projects/{projectId}/keywords` **Scope:** `read:keywords` **Parameters:** - `projectId` (path) (required): Project UUID or slug. Slugs are accepted for ergonomics; the API normalizes to the canonical UUID internally

• Get Backlinks

  Cached backlinks summary DFS backlink summary for the project's domain. Cached for 24h in KV; to force a fresh pull (consumes DFS quota), POST `/refresh` with the `write:backlinks` scope — shipping Day 6+. Returns `null` when neither the cache nor DFS has been populated for this domain yet. **HTTP:** `GET /api/v1/projects/{projectId}/backlinks` **Scope:** `read:backlinks` **Parameters:** - `projectId` (path) (required): Project UUID or slug. Slugs are accepted for ergonomics; the API normalizes

• Get Bot Analytics

  Bot Analytics dashboard payload Headline counts + daily sparkline + by-bot table + by-path table + recent hits + property list in one round trip. Property rows omit raw key material (use `write:bot-analytics` to rotate or create). **HTTP:** `GET /api/v1/projects/{projectId}/bot-analytics` **Scope:** `read:bot-analytics` **Parameters:** - `projectId` (path) (required): Project UUID or slug. Slugs are accepted for ergonomics; the API normalizes to the canonical UUID internally. - `period` (query):

• Get Alerts

  Alert rules + recent fired events Rules the project has set up + recent fired events. Events are immutable (one row per fire); rules are mutable (create/update/delete with `write:alerts`, Day 6+). **HTTP:** `GET /api/v1/projects/{projectId}/alerts` **Scope:** `read:alerts` **Parameters:** - `projectId` (path) (required): Project UUID or slug. Slugs are accepted for ergonomics; the API normalizes to the canonical UUID internally. - `event_limit` (query): Recent events to return.

• Get Reports

  Report templates + recent runs Templates the project has configured + runs (history). Each run with a rendered PDF includes a `pdfUrl` pointing at our auth-gated proxy (`/api/reports/{runId}/pdf`) that re-checks project membership before streaming the R2 object. The PDF proxy works for both browser sessions and bearer-tokened API callers — pass `Authorization: Bearer cit_api_...` on the proxy URL to fetch from a script. **HTTP:** `GET /api/v1/projects/{projectId}/reports` **Scope:** `read:repor

• Get Competitive Analysis

  Saved competitor sets for the project Lists the project's saved competitor sets (up to 5 domains per set). To run a fresh analysis (consumes DFS quota), POST with `write:competitive-analysis` — Day 6+. **HTTP:** `GET /api/v1/projects/{projectId}/competitive-analysis` **Scope:** `read:competitive-analysis` **Parameters:** - `projectId` (path) (required): Project UUID or slug. Slugs are accepted for ergonomics; the API normalizes to the canonical UUID internally.

• Get Ai Search Traffic

  AI-tool referral traffic (GA4-derived) 30-day summary of human clicks from ChatGPT / Perplexity / Gemini / Claude / Copilot etc. through to the project's domain. `connected: false` when GA4 isn't connected for this project (no other fields populated). **HTTP:** `GET /api/v1/projects/{projectId}/ai-search` **Scope:** `read:ai-search` **Parameters:** - `projectId` (path) (required): Project UUID or slug. Slugs are accepted for ergonomics; the API normalizes to the canonical UUID internally.

• Get Integrations

  Connection status for inbound data integrations GSC / BWT / GA4 / DataForSEO / etc. — null when not connected. Originating a connection requires the browser-based OAuth flow; disconnect is a `write:integrations` POST endpoint shipping Day 6+. **HTTP:** `GET /api/v1/projects/{projectId}/integrations` **Scope:** `read:integrations` **Parameters:** - `projectId` (path) (required): Project UUID or slug. Slugs are accepted for ergonomics; the API normalizes to the canonical UUID internally.

• Get Brand Radar

  Recent Brand Radar dispatch runs + dispatches Recent dispatch runs (Brand Radar's primary unit of work) with their per-run dispatched queries. KG read + aggregate analytics ship in v1.5; for v1 this is the 'show me recent activity' surface. **HTTP:** `GET /api/v1/projects/{projectId}/brand-radar` **Scope:** `read:brand-radar` **Parameters:** - `projectId` (path) (required): Project UUID or slug. Slugs are accepted for ergonomics; the API normalizes to the canonical UUID internally. - `limit` (qu

• List Webhooks

  List webhook endpoints Returns endpoints + their subscriptions + last-delivery status. Secret material (raw + encrypted) is never returned; rotation requires write:webhooks + POST /rotate-secret (v1.5). **HTTP:** `GET /api/v1/projects/{projectId}/webhooks` **Scope:** `read:webhooks` **Parameters:** - `projectId` (path) (required): Project UUID or slug. Slugs are accepted for ergonomics; the API normalizes to the canonical UUID internally.

• List Webhook Deliveries

  Recent delivery attempts for an endpoint Each row carries the event, response code, response body snippet, and the error message on failure. Useful for debugging 'why didn't my Slack channel get the alert'. **HTTP:** `GET /api/v1/projects/{projectId}/webhooks/{endpointId}/deliveries` **Scope:** `read:webhooks` **Parameters:** - `projectId` (path) (required): Project UUID or slug. Slugs are accepted for ergonomics; the API normalizes to the canonical UUID internally. - `endpointId` (path) (requir

• Create Webhook

  Register a webhook endpoint Generates a signing secret server-side and returns it ONCE. Use it to verify HMAC-SHA256(`${t}.${body}`) against the `v1=` portion of the `X-Citare-Signature` header on incoming requests. **HTTP:** `POST /api/v1/projects/{projectId}/webhooks` **Scope:** `write:webhooks` **Parameters:** - `projectId` (path) (required): Project UUID or slug. Slugs are accepted for ergonomics; the API normalizes to the canonical UUID internally.

• Update Webhook

  Update a webhook endpoint Partial update. Pass `enabled: false` to pause without losing config or history. **HTTP:** `PATCH /api/v1/projects/{projectId}/webhooks/{endpointId}` **Scope:** `write:webhooks` **Parameters:** - `projectId` (path) (required): Project UUID or slug. Slugs are accepted for ergonomics; the API normalizes to the canonical UUID internally. - `endpointId` (path) (required):

• Delete Webhook

  Delete a webhook endpoint Endpoint + its delivery history removed. Cannot be undone. **HTTP:** `DELETE /api/v1/projects/{projectId}/webhooks/{endpointId}` **Scope:** `write:webhooks` **Parameters:** - `projectId` (path) (required): Project UUID or slug. Slugs are accepted for ergonomics; the API normalizes to the canonical UUID internally. - `endpointId` (path) (required):

• Create Project

  Create a project Creates a project and adds the caller as `agency_admin`. Slug auto-derived from name when omitted. Domain must be bare. **HTTP:** `POST /api/v1/projects` **Scope:** `write:projects`

• Update Project

  Update project metadata Admin only. Partial update of name + domain. **HTTP:** `PATCH /api/v1/projects/{projectId}` **Scope:** `write:projects` **Parameters:** - `projectId` (path) (required): Project UUID or slug. Slugs are accepted for ergonomics; the API normalizes to the canonical UUID internally.

• Delete Project

  Delete a project + all its data Admin only. Cascades to audits, alerts, reports, integrations, etc. Irreversible. **HTTP:** `DELETE /api/v1/projects/{projectId}` **Scope:** `write:projects` **Parameters:** - `projectId` (path) (required): Project UUID or slug. Slugs are accepted for ergonomics; the API normalizes to the canonical UUID internally.

• Run Audit

  Kick off a site audit Long-running. Returns 202 with `auditId`; poll `/audits` to track status. `maxPages` 10-500 (default 50). `url` defaults to the project's domain root. **HTTP:** `POST /api/v1/projects/{projectId}/audits/run` **Scope:** `write:audits` **Parameters:** - `projectId` (path) (required): Project UUID or slug. Slugs are accepted for ergonomics; the API normalizes to the canonical UUID internally.

• Add Keyword

  Add a tracked keyword Idempotent. Subscribes to daily SERP-rank snapshots. Defaults: locationCode=2356 (India), languageCode=en. **HTTP:** `POST /api/v1/projects/{projectId}/keywords` **Scope:** `write:keywords` **Parameters:** - `projectId` (path) (required): Project UUID or slug. Slugs are accepted for ergonomics; the API normalizes to the canonical UUID internally.

• Remove Keyword

  Untrack a keyword Idempotent. Pass keyword + locationCode + languageCode via query string or JSON body. **HTTP:** `DELETE /api/v1/projects/{projectId}/keywords` **Scope:** `write:keywords` **Parameters:** - `projectId` (path) (required): Project UUID or slug. Slugs are accepted for ergonomics; the API normalizes to the canonical UUID internally. - `keyword` (query) (required): - `locationCode` (query): - `languageCode` (query):