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

# Overview

> Pull your own campaign data over HTTP, authenticated with a personal API key.

The External API gives you programmatic access to **your own** campaigns —
visibility scores, prompts and the AI answers behind them, brand sentiment, and
traffic. It's the same data you see in the app, in JSON.

Reads only, with one exception: [Create prompts](/api/endpoints#create-prompts)
adds tracked prompts to a campaign.

Included on every plan.

<Card title="Prefer to ask questions instead of writing requests?" icon="robot" href="/api/mcp">
  The same data is available over MCP, so Claude, Cursor or any other MCP
  client can query your campaigns directly.
</Card>

## Authentication

Requests are authenticated with a personal API key sent as a bearer token.

<Steps>
  <Step title="Create a key">
    In the app, go to **Settings → API** and choose **Create key**. Give it a
    name you'll recognise later — `Looker Studio`, `nightly-export` — because
    the name is all you'll have to go on when deciding what to revoke.
  </Step>

  <Step title="Copy it once">
    The full key is shown **only once**, right after creation. Store it
    somewhere safe. You can't view it again, only revoke it and create another.
  </Step>

  <Step title="Send it as a bearer token">
    ```bash theme={null}
    curl -H "Authorization: Bearer <your-key>" \
      https://app.theaitracker.com/api/v1/campaigns
    ```
  </Step>
</Steps>

Requests without a valid key return `401 Unauthorized`. A key only ever reaches
campaigns owned by the user who created it.

<Warning>
  Keys are **not** read-only. A key can create prompts, through this API and
  through the [MCP server](/api/mcp). Treat one like a password: keep it out of
  client-side code and public repositories, and revoke anything you no longer
  recognise. Revocation takes effect immediately.
</Warning>

## Base URL

```
https://app.theaitracker.com/api/v1
```

Your exact base URL is shown on the **Settings → API** tab — copy it from there
rather than typing it.

## Conventions

**Campaigns are addressed by `uuid`.** Start from
[`GET /campaigns`](/api/endpoints#list-campaigns) to get them. Requesting a
campaign you don't own returns `404`, not `403` — the API deliberately doesn't
confirm whether someone else's campaign exists.

**Response envelope.** Every response wraps its payload in a `data` key, with
`links` and `meta` added on paginated lists:

```json theme={null}
{
  "data": [ /* … */ ],
  "links": { "first": "…", "last": "…", "prev": null, "next": "…" },
  "meta": { "current_page": 1, "per_page": 25, "total": 42 }
}
```

**Pagination.** List endpoints accept `page` and `per_page` — default `25`,
maximum `100`.

**Date filters.** Where supported, `from` and `to` take ISO dates
(`YYYY-MM-DD`).

**Rate limits.** Two throttles apply in order:

| Limit | Scope |
| - | - |
| 120 requests/minute | Per IP, before authentication |
| 60 requests/minute | Per user, after authentication |

Exceeding either returns `429 Too Many Requests`. Rate limits are the same on
every plan.

## Errors

| Status | Meaning |
| - | - |
| `401` | Missing, invalid or revoked API key |
| `404` | The campaign doesn't exist, or isn't yours |
| `422` | Invalid query parameters, or an invalid body on a write |
| `429` | Rate limit exceeded |

Errors are always returned as JSON.

## A first request

```bash theme={null}
# 1. List your campaigns and grab a uuid
curl -H "Authorization: Bearer <your-key>" \
  https://app.theaitracker.com/api/v1/campaigns

# 2. Get that campaign's visibility for the last 30 days
curl -H "Authorization: Bearer <your-key>" \
  "https://app.theaitracker.com/api/v1/campaigns/<uuid>/visibility?days=30"
```

Full details for every endpoint are in the
[endpoint reference](/api/endpoints).


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