> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usequotable.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Prompt for AI coding assistants

> A copy-paste prompt that teaches Claude Code, Cursor or any coding assistant the Quotable API's base URL, auth, pagination, errors, rate limits and webhooks.

Coding assistants write better integrations when they know the API's rules up front. Copy this prompt into your assistant's project instructions, or paste it at the start of a conversation, before asking it to build against Quotable.

Quotable API and webhook conventions for coding assistants

You are writing code that integrates with the Quotable API (AI-search visibility data). Follow these conventions exactly.

## Basics

* Base URL: [https://app.usequotable.com/api/v1](https://app.usequotable.com/api/v1). HTTPS only. Almost every endpoint is GET and safe to retry. The facts endpoints also take POST, PATCH and DELETE, which change data; retry a POST only with the same Idempotency-Key header.
* A "brand" in the product is called a "project" in the API. project\_id is a brand's UUID.
* Field names are snake\_case. Timestamps are ISO 8601 UTC strings. Days are YYYY-MM-DD; months are YYYY-MM. All ids are UUIDs.
* Ignore unknown response fields. New fields can appear at any time without a version change.
* OpenAPI 3.1 document (public): [https://app.usequotable.com/api/v1/openapi.json](https://app.usequotable.com/api/v1/openapi.json)

## Authentication

* Header: `Authorization: Bearer <key>`. Keys look like `quotable_live_` followed by 32 letters and digits. Read the key from the QUOTABLE\_API\_KEY environment variable. Never hard-code it, log it, or send it to a browser.
* Read scopes: read:projects (brands), read:visibility (prompts, visibility, citations, reporting rows), read:content (articles), read:demand (demand terms), read:facts (facts and fact-check verdicts), read:agents and read:tables (used by the MCP server). Write scopes: write:facts (add, change and remove facts), run:agents (MCP server only). GET /me needs no scope and returns the key's scopes, project\_ids allowlist (null = all brands) and expires\_at.
* 401 = missing, malformed, unknown, revoked or expired key, or the key's creator lost access. 403 insufficient\_scope = key lacks the scope named in the "scope" member. Don't retry either.

## Endpoints

* `GET /me`
* `GET /projects` (read:projects), `GET /projects/{project_id}` (read:projects)
* `GET /projects/{project_id}/prompts?active=true|false` (read:visibility). Oldest first.
* `GET /projects/{project_id}/visibility?from=YYYY-MM-DD&to=YYYY-MM-DD` (read:visibility). Not paginated. Defaults to the last 30 days ending today UTC; max 366 days. Returns `{ project_id, from, to, data: [{ date, score, mention_rate, share_of_voice }] }` where score is 0-100, mention\_rate is 0-1 and share\_of\_voice maps each brand name to a 0-1 share; points are oldest first, only days with a tracking run.
* `GET /projects/{project_id}/citations?domain=substring` (read:visibility). Most cited first. Items: id, url, domain, times\_cited, times\_retrieved, first\_seen, last\_seen.
* `GET /projects/{project_id}/articles?status=...` (read:content). Newest first, no content. The status filter takes one of the values the OpenAPI document lists for it; read them from there and treat status as an opaque string.
* `GET /projects/{project_id}/articles/{article_id}` (read:content). Adds meta\_title, meta\_description, outline, content\_html.
* `GET /projects/{project_id}/demand/terms?q=&location_code=&language=` (read:demand). Alphabetical. Returns 404 on plans without Prompt Volumes.
* `GET /projects/{project_id}/facts?status=&active=` (read:facts). Oldest first; approved facts by default.
* `POST /projects/{project_id}/facts` (write:facts). Body `{ statements: [string] }`. All or nothing: 409 conflict for a fact already in the list, 402 plan\_limit for more active facts than the plan allows. Returns 201, or 200 with Idempotent-Replayed: true when an Idempotency-Key (8-255 chars) is repeated.
* `PATCH /projects/{project_id}/facts/{fact_id}` (write:facts). Body `{ statement?, active? }`, at least one. `DELETE /projects/{project_id}/facts/{fact_id}` (write:facts) archives the fact.
* `GET /projects/{project_id}/fact-checks?from=&to=&engine=&verdict=supported|contradicted` (read:facts). Newest first; defaults to the last 30 days.
* `GET /projects/{project_id}/fact-checks/{claim_id}/sources` (read:facts). The pages behind one checked claim.
* `GET /reporting/answers`, `GET /reporting/mentions`, `GET /reporting/citations` (read:visibility). Flat rows for BI tools across the brands the key may read. Query: from, to, project\_id (comma-separated), engine (comma-separated), runs=all|complete. limit is 1-5000 (default 1000) and a page holds whole days.

## Pagination

* List endpoints return `{ data: [...], next_cursor: string | null }`.
* Query params: limit (integer 1-100, default 50; out of range is a 400, not clamped) and cursor (pass next\_cursor back unchanged).
* Loop until next\_cursor is null. Never build, decode or modify cursors. Use limit=100 for exports.
* 400 invalid\_cursor means start again from the first page.

## Errors

* Errors are RFC 9457 problem documents with Content-Type application/problem+json: `{ type, title, status, detail?, instance, ...extensions }`.
* Branch on the code = last path segment of "type" (for example `/api/v1/problems/rate_limited` means rate\_limited). Never parse title or detail.
* Codes: invalid\_parameter (400, with `"errors": [{ parameter, message }]`), invalid\_cursor (400), invalid\_body (400, with `errors`), unauthorized (401), plan\_limit (402), insufficient\_scope (403, "scope"), forbidden (403, the key's creator can't make this change), unavailable (403, the feature isn't enabled for the workspace), not\_found (404, also for ids outside the key's brand allowlist and malformed ids), method\_not\_allowed (405), conflict (409), rate\_limited (429), internal (500).
* instance is `urn:request:<id>`, the same as the X-Request-Id response header. Log it with every failure.
* Retry only 429 and 5xx, with backoff. Everything else needs a code or config change.

## Rate limits

* 300 requests per minute per key, shared between the REST API and the MCP server. Every authenticated request counts, including 304s.
* Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (seconds until the window resets). On 429, wait Retry-After seconds, then retry.
* In bulk jobs, when X-RateLimit-Remaining reaches 0, sleep X-RateLimit-Reset seconds before the next request.

## Caching and request ids

* Every 200 has a strong ETag. Send If-None-Match with the last ETag for that URL to get a 304 with no body.
* Responses are Cache-Control: private, no-store.
* Optionally send X-Request-Id (1-128 chars of letters, digits, . \_ : -); it's echoed back. X-Api-Version is the contract date (currently 2026-09-18).

## Webhooks

* Quotable POSTs JSON to an HTTPS endpoint. Events: tracking.run.finalized.
* Envelope: `{ id, type, schema_version, occurred_at, org_id, project_id, resource: { type, id, href }, data }`. schema\_version is 1; resource.href may be null.
* Headers: X-Quotable-Event-Id, X-Quotable-Event-Type, X-Quotable-Delivery-Id, X-Quotable-Timestamp (unix seconds), X-Quotable-Signature.
* Verify every delivery BEFORE parsing: signature = hex(HMAC-SHA256(key = the full secret string including its `whsec_` prefix, message = `<timestamp>.<raw body bytes>`)). The header holds one or more comma-separated `v1=<hex>` values (two during a 24-hour secret rotation); accept if any matches, using a constant-time comparison. Reject timestamps more than 300 seconds from now.
* Read the raw body (request.text() in Next.js, express.raw() in Express, request.get\_data() in Flask). Never verify against re-serialized JSON.
* Respond 2xx within 10 seconds; do slow work asynchronously. Non-2xx, redirects and timeouts are retried after 1m, 5m, 30m, 2h, 8h and 24h.
* Delivery is at-least-once and unordered: deduplicate on the event id and order by occurred\_at.
* Fetch the full record from resource.href with an API key when needed (read:projects for brands).

## What the prompt covers

| Area | What your assistant learns |
| - | - |
| Basics | Base URL, which methods change data, naming, ids, tolerant parsing |
| Authentication | Header format, the read and write scopes, what `401` and `403` mean |
| Endpoints | Every v1 path with its scope, sort order and filters |
| Pagination | `limit`, `cursor`, `next_cursor`, never building cursors |
| Errors | Problem documents, the error codes, which to retry |
| Rate limits | 300 per minute per key, headers, `Retry-After` |
| Webhooks | Envelope, headers, signature verification, retries, deduplication |

> [!NOTE]
>
> The prompt reflects API version `2026-09-18`. Check the [API changelog](https://docs.usequotable.com/api-reference/changelog.md) for anything added since.

## Prefer live tools?

If your assistant supports MCP, connect it to the [Quotable MCP server](https://docs.usequotable.com/mcp-server/overview.md) as well. The prompt teaches it to write code against the API; MCP lets it read your data directly while it works.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.