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

# Getting Started

> Authentication, rate limits, idempotency, pagination, and errors for the Searchable REST API

## Overview

The Searchable REST API (`/api/mcp/*` and `/api/v1/projects/{projectId}/audits`) exposes the same AI-visibility, sources, sentiment, traffic, and content data available in the Searchable dashboard and [MCP server](https://docs.searchable.com/integrations/mcp.md), over plain HTTP with a bearer API key. Most endpoints are reads (GET). The ones that change something — creating a report, starting an audit or sitemap sync, and managing projects, prompts, topics, competitors, the brand profile and opportunities — are listed under [Scopes](#scopes) and [Capabilities](#capabilities) below. Like the app's own controls, they act straight away: there's no confirm step, and `dryRun: true`, where an endpoint takes it, previews the call and changes nothing.

Every endpoint in the left sidebar is interactive — send a real request from the browser using your own API key.

> [card] [Advanced API Usage](https://docs.searchable.com/advanced/api-usage.md)
>
> Narrative walkthroughs + curl/JavaScript examples per data area.

> [card] [Error Reference](https://docs.searchable.com/api/errors.md)
>
> Every error `code` this API returns, and how to fix it.

## Base URL

```
https://app.searchable.com
```

Every path in this reference (e.g. `/api/mcp/projects`) is relative to that base URL.

## Authentication

Create an API key in **Manage Account → Integrations → API Keys** in your Searchable dashboard. Keys start with `sea_` and are shown only once — store it securely. API access requires a paid Searchable plan; keys can't be created on the Free plan.

Send it as a bearer token on every request:

```
Authorization: Bearer sea_your_key_here
```

> [!NOTE]
>
> This REST surface authenticates with a static `sea_` API key only. The MCP server additionally
> supports an OAuth 2.1 login flow for interactive AI clients — see [MCP
> integration](https://docs.searchable.com/integrations/mcp.md) if you're connecting Claude, Cursor, or another MCP client instead
> of calling REST directly.

### Scopes

Each key carries one or more scopes. Scopes are independent grants, not tiers — `write` does **not** implicitly include `read`:

| Scope | Grants |
| - | - |
| `read` | GET endpoints — visibility, sources, sentiment, traffic, content, audits, … — plus `POST /reports` (sharing a report needs only `read`, as in the app) |
| `write` | The action endpoints `POST /audits` and `POST /sitemap/refresh`, and the page writes `POST /pages` and `DELETE /pages` |
| `admin` | Every endpoint, including the ones that need a capability |

A key that only reads needs `read`. A key that also starts audits or sitemap syncs needs `write` requested alongside `read` (or `admin`, which covers both). A key missing the required scope gets `403 { code: "missing_scope" }` — see [missing\_scope](https://docs.searchable.com/api/errors.md#missing-scope).

### Capabilities

The endpoints that change a project's setup need a **capability** rather than `write`. Capabilities are narrower than `write`, and `write` includes none of them, so a key can use only the ones requested for it (or `admin`, which covers them all):

| Capability | Endpoints |
| - | - |
| `project:provision` | `POST /projects` (create a project), `POST /pitches` (create a pitch) |
| `project:manage` | `POST /projects/{projectId}/lifecycle` (archive or reactivate), `POST /pitches/{pitchId}/lifecycle`, and a reseller's move: `GET` / `POST /pitches/{pitchId}/client-move`, `POST …/client-move/preview` |
| `prompt:draft` | `POST /prompts`, `PATCH /prompts/{promptId}`, `POST /prompts/sync`, `POST /prompts/{promptId}/revisions/{revision}/restore`, `POST /prompt-generation/import`, `POST /topics`, `PATCH /topics/{topicId}` |
| `prompt:activate` | `POST /prompts/{promptId}/tracking` (archive or restore a prompt) |
| `competitor:match` | `POST /competitors`, `PATCH /competitors/{competitorId}` |
| `knowledge:manage` | `PATCH /brand-profile`, `PATCH /brand-profile/alternative-names`, `PATCH /brand-profile/facts/{factId}` |
| `opportunity:manage` | `PATCH /opportunities/{opportunityId}` |
| `source:classify` | `POST /sources/rules`, `PATCH /sources/rules/{ruleId}`, `DELETE /sources/rules/{ruleId}`, `DELETE /sources/rules`, `POST /sources/rules/preview` |

A key without the capability an endpoint needs gets `403 { code: "missing_scope" }`, the same as a missing scope.

A source classification rule change (the `source:classify` endpoints) takes a few minutes to show in the numbers: poll `GET /sources/rules` until `status.applying` is `false`.

### Write access

A key you create is read-only (`read`) unless you turn on **Allow write access** when you create it. That adds `write` and every capability above. `admin` can't be self-served. A key's scopes can't be changed after it's created, so to let an integration write, create a new key with the switch on and revoke the old one.

A key can't do more than you can. A write on a project your role only lets you view returns `403 { code: "forbidden" }`, as it would in the app.

### Project binding

A key can optionally be **bound to a single project** at creation time. A project-bound key can only ever act on that one project — even a request for a project its owning user can otherwise access in the dashboard returns `404 { code: "not_found" }`, indistinguishable from a project that doesn't exist. Leave a key unbound to use it across every project you can access. Bind a key when handing it to a single-tenant integration; leave it unbound for an integration that manages multiple projects.

## Pagination

Two conventions appear across this API, depending on the endpoint:

**Offset pagination** (`limit` + `offset`) — the standard shape for most list endpoints:

```json theme={null}
{
  "limit": 20,
  "offset": 0,
  "returnedCount": 20,
  "totalCount": 143,
  "hasMore": true,
  "nextOffset": 20
}
```

Pass `nextOffset` as the next request's `offset` until `hasMore` is `false`. `totalCount` is occasionally `null` on endpoints where an exact cross-partition total isn't cheap to compute (e.g. `GET /traffic/bots`) — `hasMore`/`nextOffset` still work correctly in that case.

Every offset-paginated endpoint — including `GET /issues`, `GET /opportunities`, and `GET /competitors` — now returns this full block (`hasMore` + `nextOffset` included), so one pagination loop works across the whole API. `GET /competitors` additionally keeps its legacy `total` alias inside `pagination` and its top-level `totalCount`, for backward compatibility.

**Cursor pagination** (`cursor` + `nextCursor`) — used by the Sources domain's URL-listing endpoints (`GET /sources/domains/{domain}/urls`, `GET /sources/urls`), which read from a keyset-ordered store:

```json theme={null}
{ "urls": [/* … */], "totalUrls": 812, "nextCursor": "eyJvZmZzZXQiOjIwfQ", "hasMore": true }
```

Pass the previous response's `nextCursor` as the next request's `cursor`. Omit `cursor` for the first page. Treat the cursor as opaque — don't parse or construct it.

`limit` defaults vary by endpoint (typically 20-50). The big list endpoints — cited domains, cited URLs, prompts, opportunities — accept up to **1,000 rows per page** (issues up to 5,000); values above an endpoint's cap are clamped, never rejected. See each operation's description in the sidebar.

## CSV export

The five biggest list endpoints — `GET /sources/domains`, `GET /sources/urls`, `GET /prompts`, `GET /issues`, `GET /opportunities` — accept `?format=csv` and return the operation's main row set as a downloadable **UTF-8 CSV** (RFC 4180, BOM-prefixed so Excel handles non-ASCII, and spreadsheet-formula-hardened) instead of the JSON envelope:

```bash theme={null}
curl -H "Authorization: Bearer $SEARCHABLE_API_KEY" \
  "https://app.searchable.com/api/mcp/projects/PROJECT_ID/sources/urls?limit=1000&format=csv" \
  -o cited-urls.csv
```

Pagination parameters apply unchanged — export beyond one page by walking `offset`. Nested JSON fields serialize as minified JSON inside their cell, except a split domain's `types` in `GET /sources/domains`, which is `;`-joined (`social;brand`).

## Rate limiting

Every API key is limited to **600 requests/minute** across this REST surface (`/api/mcp/*`, `/api/v1/*`, and the Looker Studio connector — MCP *tool calls* don't count against this budget). Every response carries rate-limit headers, whether it succeeds or errors:

```
RateLimit: "default";r=598;t=42
RateLimit-Policy: "default";q=600;w=60
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 598
X-RateLimit-Reset: 1755000042
```

`RateLimit`/`RateLimit-Policy` follow the [IETF rate-limit header draft](https://www.ietf.org/archive/id/draft-ietf-httpapi-ratelimit-headers-08.html) (`r` = remaining, `t` = seconds until reset, `q` = quota, `w` = window in seconds). `X-RateLimit-*` is kept alongside for clients that read the older convention.

The limiter fails open: if its backing store is briefly unavailable, requests are **allowed** and the rate-limit headers are simply omitted from that response — don't hard-require the headers in client code.

Exceeding the limit returns `429` with a `Retry-After` header (seconds) and a `rate_limited` problem+json body.

## Idempotency

These write endpoints accept an `Idempotency-Key` header: `POST /reports`, `POST /audits`, `POST /sitemap/refresh`, `POST /pages`, `DELETE /pages`, `POST /projects`, `POST /lifecycle`, `POST /pitches`, `POST /pitches/{pitchId}/lifecycle`, `POST /pitches/{pitchId}/client-move`, `POST /prompts`, `PATCH /prompts/{promptId}`, `POST /prompts/sync`, `POST /prompts/{promptId}/tracking`, `POST /prompts/{promptId}/revisions/{revision}/restore` and `POST /prompt-generation/import`. Send the same key on a retry (after a timeout or a dropped connection) and the API replays the original response instead of repeating the side effect:

```javascript theme={null}
const idempotencyKey = crypto.randomUUID();

const res = await fetch("https://app.searchable.com/api/mcp/projects/PROJECT_ID/reports", {
  method: "POST",
  headers: {
    Authorization: "Bearer sea_YOUR_KEY",
    "Content-Type": "application/json",
    "Idempotency-Key": idempotencyKey,
  },
  body: JSON.stringify({ reportType: "sentiment" }),
});
// A retry with the SAME idempotencyKey returns the same body and adds:
//   X-Idempotent-Replay: true
```

Notes:

* Keys are scoped per API key and held for **24 hours**.
* Only a **successful (2xx)** response is stored — a failed attempt (4xx/5xx) is never replayed; retrying after a real failure with the same key simply runs the request again.
* Two **concurrent** requests with the same key never both execute: the second gets `409 { code: "idempotency_in_flight" }` with `Retry-After: 5` while the first is still running.
* Reusing a key with a **different** request body returns `409 { code: "idempotency_conflict" }` rather than replaying the first response. Use a new key for a new request.
* A `dryRun: true` call's `200` is stored like any other successful response. Sending its key again with `dryRun` removed is a **different** body and returns `409 idempotency_conflict`: use a new key to act after a preview.
* `POST /pitches/{pitchId}/lifecycle` and `POST /pitches/{pitchId}/client-move` also scope the key to the pitch in the path, so the same key and body sent for another pitch is a new request, not a replay of the first pitch's answer.
* A stored response body over 100KB isn't cached — the request still runs normally, and the response carries `X-Idempotent-Skipped: body-too-large` instead of `X-Idempotent-Replay`.
* No `Idempotency-Key` header — the request behaves exactly as before. Fully opt-in.

## Errors

Every non-2xx response is [`application/problem+json`](https://www.rfc-editor.org/rfc/rfc9457) — a machine-readable envelope that additively extends the API's original `{ error: "..." }` shape, so existing integrations that only read `error` keep working unmodified:

```json theme={null}
{
  "type": "https://docs.searchable.com/api/errors#not_found",
  "title": "Not Found",
  "status": 404,
  "code": "not_found",
  "error": "Project not found or access denied",
  "message": "Project not found or access denied",
  "requestId": "b3f1c2a0-4e9d-4a11-9c3a-8e2f6d1a7c55"
}
```

`code` is the field to branch on — it's stable across releases. Full catalog, per-code remediation, and additive fields (`requiresUpgrade`, `retryable`, `current`/`limit`, …): **[API Error Reference](https://docs.searchable.com/api/errors.md)**.

Beyond the statuses listed per operation, any endpoint may also return a generic `500` or `502` problem+json with `code: "internal_error"` on an unexpected internal failure (the `502` variant carries `retryable: true`) — treat both as transient and retry with exponential backoff.

Every response — success or error — also carries `X-Request-Id`. Include it when contacting **[support@searchable.com](mailto:support@searchable.com)** about a specific request.

## Typed clients

There's no official SDK — the OpenAPI spec **is** the contract. Call the API directly with `fetch`/`curl`/your HTTP client of choice, or generate TypeScript types straight from the spec with the MIT-licensed [`openapi-typescript`](https://openapi-ts.dev):

```bash theme={null}
npx openapi-typescript https://docs.searchable.com/api-reference/openapi.json -o searchable-api.d.ts
```

That produces a `paths` / `components` type tree covering every endpoint and schema on this page — pair it with a typed `fetch` wrapper (e.g. [`openapi-fetch`](https://openapi-ts.dev/openapi-fetch/)) for end-to-end type safety with no generated SDK to maintain. An official SDK isn't planned unless customer demand shows up.

## Next steps

> [card] [Agent API](https://docs.searchable.com/api-reference/agent-api.md)
>
> Programmatic access to the Searchable agent, for approved customers.

> [card] [Changelog](https://docs.searchable.com/changelog.md)
>
> What's new on this API, and the deprecation policy.


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