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

# Advanced API Usage

> Query your AI visibility data and generate reports programmatically with the Searchable API

## Overview

Searchable exposes three programmatic surfaces. Pick the one that fits your use case:

<CardGroup cols={3}>
  <Card title="MCP (AI assistants)" icon="robot" href="/integrations/mcp">
    35 read-only tools for Claude, Cursor, and other MCP clients — the richest way to query your data.
  </Card>

  <Card title="REST API" icon="code">
    Fetch audits & issues and generate shareable reports with an API key.
  </Card>

  <Card title="Ingest API" icon="database" href="/setup/rest-api">
    Send AI-bot traffic events from any language or platform.
  </Card>
</CardGroup>

<Info>
  API access requires a **paid plan** (Starter, Professional, or Scale). API keys can't be created on the Free plan.
</Info>

## Authentication

Create an API key in **Settings → Workspace → Integrations** in your Searchable dashboard. Keys start with `sea_` and are shown only once — store it securely.

Send it as a Bearer token on every request:

```
Authorization: Bearer sea_your_key_here
```

| Base URL | `https://app.searchable.com` |
| -------- | ---------------------------- |

### Scopes

Each key carries one or more scopes. Read endpoints require `read` (the default); write endpoints require `write`.

| Scope   | Grants                                       |
| ------- | -------------------------------------------- |
| `read`  | Fetch audits, issues, and visibility data    |
| `write` | Everything in `read`, plus report generation |
| `admin` | All scopes                                   |

A key can also be **bound to a single project**. A project-bound key only works against that project; leave a key unbound to use it across all projects you can access.

## Fetch audits + issues

Retrieve the latest audit per page, when each was last completed, and optionally the open issues for each page.

```
GET /api/v1/projects/{projectId}/audits?includeIssues=true
```

```javascript theme={null}
const res = await fetch(
  'https://app.searchable.com/api/v1/projects/PROJECT_ID/audits?includeIssues=true',
  { headers: { Authorization: 'Bearer sea_YOUR_KEY' } }, // requires the `read` scope
);
const { summary, audits } = await res.json();
// summary.totalPages     — pages with at least one completed audit (not all tracked pages)
// summary.lastCompletedAt — newest completed audit across all pages
// audits[].openIssues     — present only when includeIssues=true
```

## Generate a shareable report

Generate and publish a report, and get back its public share URL. This is a write action, so it isn't an MCP tool — use this endpoint.

```
POST /api/mcp/projects/{projectId}/reports
```

Requires the `write` scope and a plan that includes report sharing.

```javascript theme={null}
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',
    },
    body: JSON.stringify({
      reportType: 'combined',   // "sentiment" | "visibility" | "combined" (default "sentiment")
      timeRange: '30d',         // "7d" | "30d" | "90d" | "365d" (default "30d")
      status: 'published',      // "published" | "draft" (default "published")
      // optional filters: platforms, topicIds, locationIds (string arrays)
      // optional: title, unbrandedOnly, brandedOnly
    }),
  },
);
const { shareUrl, shareToken, reportType, success } = await res.json();
```

## Query visibility, sources & sentiment

For visibility scores, share of voice, sources, sentiment, and GA4/GSC data, connect the **[MCP server](/integrations/mcp)** — it exposes 35 read-only tools over the same data and handles auth for you. It's the fastest path for read-heavy automation and works directly inside Claude, Cursor, and other assistants.

## Send AI-bot traffic

To report request events from your own app or CDN (so crawlers like GPTBot and ClaudeBot show up in your dashboard), use the **[REST Ingest API](/setup/rest-api)**. That endpoint uses a separate ingest key (`sk_live_…`) and a signed edge path — see its page for the full contract.

## Error handling

| Status | Meaning                                                                               |
| ------ | ------------------------------------------------------------------------------------- |
| `400`  | Bad request — check parameters / body                                                 |
| `401`  | Missing or malformed API key                                                          |
| `403`  | Insufficient scope, or your plan doesn't include the action (`requiresUpgrade: true`) |
| `404`  | Project not found, or the key isn't allowed to reach it                               |
| `429`  | Rate limited — back off and retry                                                     |
| `500`  | Server error — retry with exponential backoff                                         |
| `504`  | Report generation timed out — retryable                                               |

## API key best practices

<Check>Never commit API keys to version control — use environment variables</Check>
<Check>Scope each key to the minimum it needs (`read` unless it must write)</Check>
<Check>Bind a key to a single project when it only ever touches that project</Check>
<Check>Use separate keys for dev and prod, and rotate them regularly</Check>
<Check>Revoke compromised keys immediately in Settings → Integrations</Check>

## Need more?

Higher rate limits, custom endpoints, or a dedicated integration? Contact **[support@searchable.com](mailto:support@searchable.com)**.

## Next steps

<CardGroup cols={2}>
  <Card title="MCP Integration" icon="robot" href="/integrations/mcp">
    Connect Claude, Cursor, and other assistants to your Searchable data.
  </Card>

  <Card title="REST Ingest API" icon="braces" href="/setup/rest-api">
    Send AI-bot traffic events from any stack.
  </Card>
</CardGroup>