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

# API Introduction

> The Mavel REST API: authentication, rate limits, pagination, and errors.

The Mavel REST API gives you programmatic access to everything the dashboard
shows: projects, brands, prompts, topics, tags, captured answers, and
reports. The interactive reference in this tab is generated from the live
OpenAPI 3.0 spec at
[`app.mavel.ai/api/v1/openapi.json`](https://app.mavel.ai/api/v1/openapi.json).

<Note>
  API access is available on the Growth plan and above. See
  [Plans](/account/plans).
</Note>

## Authentication

Pass your API key in the `X-API-Key` header on every request:

```bash theme={null}
curl https://app.mavel.ai/api/v1/projects \
  -H "X-API-Key: <your-api-key>"
```

Create and manage keys in the dashboard. See [API keys](/account/api-keys).
Keys are project-scoped; keep them out of URLs, logs, and client-side code.

## Base URL and versioning

```
https://app.mavel.ai/api/v1
```

The API is versioned in the path. Breaking changes only ship in a new version.

## Rate limits

**200 requests / minute / project.** Exceeding the limit returns HTTP 429;
back off and retry after the window resets.

## Pagination

List endpoints paginate with `limit` and `offset` query parameters. Iterate by
increasing `offset` by `limit` until a page comes back with fewer than `limit`
items.

## Errors

Errors return a machine-readable envelope with an HTTP status, a
SCREAMING\_SNAKE\_CASE `code`, and a human-readable message:

```json theme={null}
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Project not found."
  }
}
```

| Status | Typical codes       |
| ------ | ------------------- |
| 400    | `VALIDATION_ERROR`  |
| 403    | `FORBIDDEN`         |
| 404    | `NOT_FOUND`         |
| 409    | `CONFLICT`          |
| 429    | rate limit exceeded |
| 500    | `INTERNAL_ERROR`    |