> ## 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.

# API overview

> Read your brands, AI visibility, citations, articles, demand and fact-check data from your own tools, and manage your brand facts, with the Quotable REST API.

The Quotable API gives your scripts, dashboards and data pipelines the same data you see in the app: the brands you track, their daily visibility in AI answers, the pages those answers cite, the articles stored for each brand, the demand behind your prompts, and how AI answers check against your brand facts.

Version 1 is **read-only** except for brand facts. Every `GET` is safe to retry. The facts endpoints that add, change or remove facts need the `write:facts` scope; send an `Idempotency-Key` header when you add facts so a retry is safe. See [Retry writes safely](https://docs.usequotable.com/api-reference/errors.md#retry-writes-safely).

> [!NOTE]
>
> The API calls a brand a **project**. A project id is the id of a brand in your workspace, and `project_id` in a path means "this brand".

## Base URL

```text theme={"system"}
https://app.usequotable.com/api/v1
```

All requests use HTTPS. Responses are JSON (`application/json`), and errors are JSON problem documents (`application/problem+json`).

The machine-readable contract is an OpenAPI 3.1 document. It's public and needs no key:

```bash theme={"system"}
curl https://app.usequotable.com/api/v1/openapi.json
```

## What you can call

Each key is granted one or more **scopes**. An endpoint answers only when the key holds the scope it needs.

| Resource | Endpoints | Scope |
| - | - | - |
| The calling key | `GET /me` | Any valid key |
| Brands | `GET /projects`, `GET /projects/{project_id}` | `read:projects` |
| Prompts | `GET /projects/{project_id}/prompts` | `read:visibility` |
| Daily visibility | `GET /projects/{project_id}/visibility` | `read:visibility` |
| Cited sources | `GET /projects/{project_id}/citations` | `read:visibility` |
| Articles | `GET /projects/{project_id}/articles`, `GET /projects/{project_id}/articles/{article_id}` | `read:content` |
| Demand terms | `GET /projects/{project_id}/demand/terms` | `read:demand` |
| Reporting | `GET /reporting/answers`, `GET /reporting/mentions`, `GET /reporting/citations` | `read:visibility` |
| Facts | `GET /projects/{project_id}/facts` | `read:facts` |
| Fact checks | `GET /projects/{project_id}/fact-checks`, `GET /projects/{project_id}/fact-checks/{claim_id}/sources` | `read:facts` |
| Manage facts | `POST /projects/{project_id}/facts`, `PATCH` and `DELETE /projects/{project_id}/facts/{fact_id}` | `write:facts` |

The same keys also work with the [MCP server](https://docs.usequotable.com/mcp-server/overview.md), which exposes this data as tools for AI assistants. Three scopes apply only there: `read:agents`, `read:tables` and `run:agents`. See [Scopes](https://docs.usequotable.com/api-reference/authentication.md#scopes). To be told when something happens instead of polling, use [webhooks](https://docs.usequotable.com/webhooks/overview.md).

## Conventions at a glance

| Topic | Behavior |
| - | - |
| Authentication | `Authorization: Bearer quotable_live_…` on every request. See [Authentication](https://docs.usequotable.com/api-reference/authentication.md). |
| Rate limit | 300 requests per 60-second window per key, shared with MCP. See [Rate limits](https://docs.usequotable.com/api-reference/rate-limits.md). |
| Pagination | Cursor-based. `limit` from 1 to 100 (default 50; the reporting endpoints take up to 5000), follow `next_cursor` until it's `null`. See [Pagination](https://docs.usequotable.com/api-reference/pagination.md). |
| Errors | RFC 9457 problem details with a stable `type`. See [Errors](https://docs.usequotable.com/api-reference/errors.md). |
| Caching | Every `200` carries an `ETag`; send `If-None-Match` to get a `304`. See [Caching and request IDs](https://docs.usequotable.com/api-reference/caching-and-request-ids.md). |
| Request IDs | Every response carries `X-Request-Id`. Quote it when you contact support. |
| Versioning | Major version in the path (`/api/v1`), contract date in `X-Api-Version`. See [Versioning](https://docs.usequotable.com/api-reference/versioning.md). |
| Field names | `snake_case`. Timestamps are ISO 8601 in UTC; days are `YYYY-MM-DD`. |
| IDs | UUIDs. An id that is malformed, unknown or outside your key's reach returns `404`. |

## Next steps

> [card] [Quickstart](https://docs.usequotable.com/api-reference/quickstart.md)
>
> Create a key and make your first three calls in five minutes.

> [card] [Authentication](https://docs.usequotable.com/api-reference/authentication.md)
>
> Key format, scopes, brand allowlists, expiry and revocation.

> [card] [Cookbook](https://docs.usequotable.com/guides/introduction.md)
>
> Runnable recipes: trend charts, cited-domain rankings, CSV exports and Slack alerts.


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