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

# Conventions

> Authentication, the response envelope, rate limits, and error shapes shared across the API.

## Base path

Every endpoint is mounted under `/api`. Paths in the reference already include it
(e.g. `POST /api/agencies`).

## Authentication

Public API requests use bearer API keys:

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

Create and manage keys from the API Keys page in the dashboard. Some endpoints
also require a customer role, tenant boundary, project access, or module scope.
Those constraints are noted on each operation.

## CSRF

Public API requests authenticated with bearer API keys do not use CSRF tokens.
CSRF protection applies to browser dashboard sessions, not API key requests.

## Response envelope

Success responses use:

```json theme={"dark"}
{ "success": true, "data": { } }
```

The payload key varies by endpoint (`data`, `result`, or a named field). Errors use:

```json theme={"dark"}
{ "success": false, "error": "ERROR_CODE", "message": "Human-readable explanation" }
```

`error` is a short machine-readable code (for example `Unauthorized`, `VALIDATION`,
or `InsufficientScope`); `message` is the human-readable explanation. Some errors
add fields, such as `requiredScope` on `InsufficientScope`.

## Common status codes

| Status | Meaning                                                                       |
| ------ | ----------------------------------------------------------------------------- |
| `400`  | Validation failed / malformed request                                         |
| `401`  | Missing or invalid authentication                                             |
| `403`  | Authenticated but not permitted (role, tenant boundary, or missing API scope) |
| `404`  | Resource not found                                                            |
| `429`  | Rate limit exceeded                                                           |
| `500`  | Unexpected server error                                                       |

## Rate limiting

All `/api` routes pass through shared source-IP rate limits. API-key requests
also use API key and API key plus source-IP limits. Exceeding a limit returns
`429` with the standard error envelope.