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

> ## Agent Instructions
> Use the public API base URL: https://api.teamfollowup.ai/api.
> Authenticate public API requests with Authorization: Bearer YOUR_API_KEY.
> Use product-owned terms: agents, calls, campaigns, contacts, phone numbers, billing, and configuration.

# Authentication

> Authenticate public API requests with bearer API keys.

Every public API request must include your API key as a bearer token in the
`Authorization` header:

```http theme={"dark"}
Authorization: Bearer YOUR_API_KEY
```

The public API base URL is:

```text theme={"dark"}
https://api.teamfollowup.ai/api
```

Example:

```bash theme={"dark"}
curl https://api.teamfollowup.ai/api/agent-builder/agents \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Only send API keys over HTTPS. Do not expose API keys in browser code, mobile
app bundles, client-side logs, screenshots, or support tickets.

## Manage keys

Create, rotate, and revoke API keys from the **API Keys** page in the dashboard.
Keys are shown once when created or rotated. Store the value securely before
leaving the page.

The same bearer API keys authenticate the [MCP action endpoint](/mcp-actions).
Its advertised tool list is filtered by these scopes.

That endpoint also accepts OAuth 2.1, which is the better fit for a hosted AI
assistant: the user approves the scopes in a browser instead of pasting a key
into a chat. The scopes below are the same ones the consent screen grants. See
[MCP action tools](/mcp-actions) for the flow.

Agency admins can manage keys for their own agency. Staff-only full-access keys
are internal and are not part of the public API launch contract.

## Scopes

API keys are scoped by module. Launch scopes are:

| Scope                      | Allows                                                                   |
| -------------------------- | ------------------------------------------------------------------------ |
| `agents:read`              | List agent types, list agents, get one agent, and read outcome prompts   |
| `agents:write`             | Create, update, clone, and update outcome prompts                        |
| `voices:read`              | Browse the voice catalog                                                 |
| `calls:read`               | Read call history, filters, exports, call details, and execution history |
| `calls:write`              | Trigger test calls and campaign tests                                    |
| `campaigns:read`           | List campaigns and campaign metadata                                     |
| `campaigns:write`          | Create, update, link, and rescan campaign resources                      |
| `campaign_workflows:read`  | Read campaign workflow configuration                                     |
| `campaign_workflows:write` | Save campaign workflow configuration                                     |
| `contacts:read`            | Read contacts, filters, exports, and contact call history                |
| `contacts:write`           | Add or remove contact kill switch status                                 |
| `ghl:read`                 | Read custom fields, values, calendars, tags, pipelines, and workflows    |
| `ghl:write`                | Create contacts and update approved workflow settings                    |
| `phone_numbers:read`       | List and search phone numbers                                            |
| `phone_numbers:write`      | Buy, attach, assign, unassign, and move phone numbers                    |
| `phone_numbers:release`    | Permanently release phone numbers from the agency pool                   |
| `power_dialer:read`        | Read pipeline, callback, and cadence data                                |
| `power_dialer:write`       | Run, requeue, remove, and update cadence actions                         |
| `projects:read`            | Read projects, systems, cadences, calendars, and validation results      |
| `projects:write`           | Create and update projects and project campaign configuration            |
| `projects:delete`          | Disconnect and hide projects from the customer workspace                 |
| `dashboard:read`           | Read dashboard metrics and project filters                               |
| `dashboard:write`          | Manage dashboard layouts and saved views                                 |
| `events:read`              | Read tenant-scoped events and event types                                |
| `configuration:read`       | Read agency configuration                                                |
| `configuration:write`      | Update agency configuration                                              |
| `whitelabel:read`          | Read agency branding and custom-domain status                            |
| `whitelabel:write`         | Manage agency branding, logos, and custom domains                        |
| `billing:read`             | Read approved billing status, usage, balances, ledgers, and plans        |
| `billing:write`            | Manage subscriptions, top-ups, auto-recharge, and wallet configuration   |

For module scopes with both read and write variants, write scope also covers the
same module's read scope. For example, `agents:write` covers `agents:read`.

If a key is missing the required scope, the API returns:

```json theme={"dark"}
{
  "success": false,
  "error": "InsufficientScope",
  "message": "This API key does not have the required scope.",
  "requiredScope": "agents:write"
}
```

<Note>
  Sensitive operations use explicit write, delete, or release scopes in addition
  to the existing role, tenant, ownership, billing, and resource-state checks.
  Internal tools and staff-only surfaces remain outside the public API.
</Note>

## Rate limits

API requests are rate limited by source IP. API-key-authenticated requests also
use API key limits and API key plus source-IP limits. Large export endpoints can
have stricter limits than normal read endpoints.

When a request is rate limited, the API returns `429`:

```json theme={"dark"}
{
  "success": false,
  "error": "TooManyRequests",
  "message": "Rate limit exceeded for this API key. Please try again later."
}
```