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

# Introduction to the API

> Authentication, permissions, response format, errors and rate limits of the ChatNorris public API.

# Public API v2

The ChatNorris API v2 lets you integrate and automate your AI agent platform from any external application. You can manage agents, send messages, read conversations, leads and more.

**Base URL:**

```text theme={null}
https://app.chatnorris.ai/api/v2
```

> [!NOTE]
>
> API access is available on the **Standard** and **Premium** plans. To enable it, you need an active API key. On the Free plan, the API keys section appears locked — if you try to create a key, you're redirected to the plans page.

***

## Generate an API key

1. Sign in to your account and go to **Settings → API Keys**.
2. Enter a descriptive name for the key (e.g. "Production" or "Zapier").
3. Click **New key**.
4. Copy the generated key — it's shown only once. Store it somewhere safe.

If you lose the key, you have to delete it and create a new one. Each organization can have up to **10 API keys**.

> [!WARNING]
>
> Each key has full API access on behalf of your organization. Treat it like a password and don't share it or expose it in a website's code.

> [!TIP]
>
> The API v2 is also the foundation of the automation integrations listed on the [Integrations](https://chatnorris.ai/integrations) page: **Zapier** (public app, no credentials of your own) and the **n8n community node** (`n8n-nodes-chatnorris`, open source). Both connect with your API key and the endpoints in this reference — see [Zapier](https://docs.chatnorris.ai/en/api-referencia/zapier.md) and [n8n](https://docs.chatnorris.ai/en/api-referencia/n8n.md).

***

## Authentication

Every request must include the API key in the `Authorization` header as a Bearer token:

```http theme={null}
Authorization: Bearer <your_api_key>
```

Requests without a key or with an invalid key receive `401 Unauthorized`. The `X-API-Key` header isn't accepted.

***

## Permissions (scopes)

Each endpoint requires a permission (scope). The API keys you create in **Settings → API Keys** always have **full access** (`*`), so they can use every endpoint in this reference: you don't have to choose permissions when you create the key.

For reference, this is the permission each group of endpoints requires:

| Scope | Access |
| - | - |
| `chatbots:read` | List and get agents and knowledge sources |
| `chatbots:write` | Create, update and delete agents and sources |
| `chat:write` | Send messages through an agent and upload attachments |
| `conversations:read` | List and get conversations and messages |
| `leads:read` | List and get leads |
| `channels:read` | List connected channels |
| `*` | Full access to all scopes |

The **project**, **members** and **usage** endpoints don't require a specific scope — only valid authentication.

***

## Response format

All responses are JSON with the following structure:

### Success

```json theme={null}
{
  "status": "success",
  "data": { ... }
}
```

### Success with pagination

```json theme={null}
{
  "status": "success",
  "data": { ... },
  "pages": {
    "current_page": 1,
    "last_page": 4,
    "per_page": 25,
    "total": 98
  }
}
```

### Error

```json theme={null}
{
  "status": "error",
  "message": "Error description",
  "code": "ERROR_CODE"
}
```

***

## Pagination

List endpoints support pagination through query params:

| Parameter | Type | Default | Description |
| - | - | - | - |
| `page` | integer | `1` | Page number (starts at 1) |
| `per_page` | integer | `25` | Results per page (maximum `100`) |

***

## Error codes

| HTTP code | Code | Description |
| - | - | - |
| 400 | `INVALID_INPUT` | The request body fails validation |
| 401 | `AUTH_REQUIRED` | The `Authorization` header is missing |
| 401 | `INVALID_API_KEY` | The API key doesn't exist, was deleted, or has an invalid format |
| 401 | `API_KEY_EXPIRED` | The API key has expired |
| 403 | `ORG_SUSPENDED` | The organization that owns the key isn't active |
| 403 | `FEATURE_NOT_ALLOWED` | Your organization's plan doesn't include API access (for example, the Free plan) |
| 403 | `INSUFFICIENT_SCOPE` | The key doesn't have the scope required for this endpoint |
| 403 | `PLAN_LIMIT_REACHED` | A plan limit was reached (agents, credits, etc.) |
| 404 | `NOT_FOUND` | The requested resource doesn't exist or doesn't belong to your organization |
| 429 | `RATE_LIMIT_EXCEEDED` | The requests-per-minute limit was exceeded |
| 429 | `PLAN_LIMIT_REACHED` | The plan's AI credit limit was reached |
| 500 | `INTERNAL_ERROR` | Internal server error |

***

## Rate limiting

The API allows **300 requests per minute** per API key.

When the limit is exceeded, the response includes the `Retry-After` header with the number of seconds to wait before retrying.

```http theme={null}
HTTP/1.1 429 Too Many Requests
Retry-After: 15
```

```json theme={null}
{
  "status": "error",
  "message": "Too many requests",
  "code": "RATE_LIMIT_EXCEEDED"
}
```


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