REST API v1

A small read-only surface for pulling visibility data and recommendations into your own dashboards, warehouses and reports.

What can the REST API do?

Five endpoints, all GET, all read-only. If you need to start work — run a scan, generate prompts, draft content — that lives on the MCP server, not here. v1 is deliberately a reporting surface.

All requests need Authorization: Bearer <your key>. See Authentication.

Is there an OpenAPI spec?

Yes. The full OpenAPI 3.1 description is at /openapi.json (also served at /api/v1/openapi.json). It declares every endpoint, query parameter, response shape and error, so an AI agent or a client generator can work from a contract rather than from this prose. It needs no key to read.

A test pins the spec to the routes that actually exist in both directions, so an endpoint cannot be added, removed or renamed without the spec failing the build.

What are the REST API endpoints?

Method	Path	Returns
`GET`	`/api/v1/brands`	Every brand the key's owner can see
`GET`	`/api/v1/brands/:id`	One brand's detail
`GET`	`/api/v1/brands/:id/visibility`	Visibility scores over time
`GET`	`/api/v1/brands/:id/recommendations`	The recommendation queue, each with its fix prompt
`GET`	`/api/v1/brands/:id/runs`	Scan run history

Example

curl https://citeagentic.com/api/v1/brands \
  -H "Authorization: Bearer $CITEAGENTIC_KEY"

Then pull the recommendations for one of them:

curl https://citeagentic.com/api/v1/brands/<brand-id>/recommendations \
  -H "Authorization: Bearer $CITEAGENTIC_KEY"

Each recommendation carries payload.fixPrompt — the paste-ready prompt we generate for it. That is included on purpose: if you are building your own workflow on top of CiteAgentic, the fix prompt is the part worth having.

What do the error responses mean?

Response	Meaning
`401 missing_bearer_token`	No `Authorization: Bearer` header
`401 invalid_api_key`	Unknown or revoked key
`403 tier_disallows_api`	Valid key, but the plan does not include API access
`404`	The brand does not exist, or the key's owner cannot see it

A brand belonging to another account returns 404, not 403 — an API should not confirm that something exists to someone who cannot read it.

What are the rate limits?

Requests are rate-limited per IP, shared with the rest of the application. There is no separate per-key quota today, so a busy integration and a busy browser session draw on the same allowance.

What is missing from v1?

Four things: write endpoints, pagination, webhooks, and per-key rate limits. Being straight about the edges, because guessing wastes your time:

No write endpoints. Creating prompts, competitors or drafts is MCP-only for now.
No pagination or cursors. Collections return in full.
No webhooks or event subscriptions. Poll, or use MCP.
No per-key rate limits or usage endpoint. Calls are logged against the key, but there is no endpoint to read that log.

If one of these is blocking something you are building, tell us — the order we build them in follows what customers actually ask for.