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

# Introdução à API

> Autenticação, permissões, formato de resposta, erros e limites de taxa da API pública do ChatNorris.

# API Pública v2

A API v2 do ChatNorris permite integrar e automatizar sua plataforma de agentes de IA a partir de qualquer aplicação externa. Você pode gerenciar agentes, enviar mensagens, ler conversas, leads e muito mais.

**Base URL:**

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

> [!NOTE]
>
> O acesso à API está disponível nos planos **Standard** e **Premium**. Para habilitá-lo, você precisa de uma API key ativa. No plano Free, a seção de chaves de API aparece bloqueada — ao tentar criar uma key, você é redirecionado para a página de planos.

***

## Gerar uma API key

1. Entre na sua conta e acesse **Configurações → Chaves de API**.
2. Digite um nome descritivo para a chave (ex.: "Produção" ou "Zapier").
3. Clique em **Nova chave**.
4. Copie a key gerada — ela é exibida uma única vez. Guarde-a em um lugar seguro.

Se você perder a key, precisa excluí-la e criar uma nova. Cada organização pode ter até **10 API keys**.

> [!WARNING]
>
> Cada chave tem acesso completo à API em nome da sua organização. Trate-a como uma senha e não a compartilhe nem a exponha no código de um site.

> [!TIP]
>
> A API v2 também é a base das integrações de automação listadas na página de [Integrações](https://chatnorris.ai/integrations): **Zapier** (app pública, sem credenciais próprias) e o **community node do n8n** (`n8n-nodes-chatnorris`, código aberto). Ambas se conectam com a sua API key e os endpoints desta referência — veja [Zapier](https://docs.chatnorris.ai/pt/api-referencia/zapier.md) e [n8n](https://docs.chatnorris.ai/pt/api-referencia/n8n.md).

***

## Autenticação

Todas as requests devem incluir a API key no header `Authorization` como Bearer token:

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

As requests sem key ou com key inválida recebem `401 Unauthorized`. O header `X-API-Key` não é aceito.

***

## Permissões (scopes)

Cada endpoint exige uma permissão (scope). As API keys que você cria em **Configurações → Chaves de API** sempre têm **acesso completo** (`*`), então podem usar todos os endpoints desta referência: não é preciso escolher permissões ao criar a chave.

Como referência, esta é a permissão que cada grupo de endpoints exige:

| Scope | Acesso |
| - | - |
| `chatbots:read` | Listar e obter agentes e fontes de knowledge |
| `chatbots:write` | Criar, atualizar e excluir agentes e fontes |
| `chat:write` | Enviar mensagens por meio de um agente e enviar anexos |
| `conversations:read` | Listar e obter conversas e mensagens |
| `leads:read` | Listar e obter leads |
| `channels:read` | Listar canais conectados |
| `*` | Acesso completo a todos os scopes |

Os endpoints de **projeto**, **membros** e **uso** não exigem um scope específico — apenas autenticação válida.

***

## Formato de resposta

Todas as respostas são JSON com a seguinte estrutura:

### Sucesso

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

### Sucesso com paginação

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

### Erro

```json theme={null}
{
  "status": "error",
  "message": "Descrição do erro",
  "code": "CODIGO_ERROR"
}
```

***

## Paginação

Os endpoints de listagem suportam paginação por meio de query params:

| Parâmetro | Tipo | Default | Descrição |
| - | - | - | - |
| `page` | integer | `1` | Número da página (começa em 1) |
| `per_page` | integer | `25` | Resultados por página (máximo `100`) |

***

## Códigos de erro

| Código HTTP | Code | Descrição |
| - | - | - |
| 400 | `INVALID_INPUT` | O corpo da request não passa na validação |
| 401 | `AUTH_REQUIRED` | Falta o header `Authorization` |
| 401 | `INVALID_API_KEY` | A API key não existe, foi excluída ou o formato é inválido |
| 401 | `API_KEY_EXPIRED` | A API key expirou |
| 403 | `ORG_SUSPENDED` | A organização dona da key não está ativa |
| 403 | `FEATURE_NOT_ALLOWED` | O plano da sua organização não inclui acesso à API (por exemplo, o plano Free) |
| 403 | `INSUFFICIENT_SCOPE` | A key não tem o scope necessário para este endpoint |
| 403 | `PLAN_LIMIT_REACHED` | O limite do plano foi atingido (agentes, créditos etc.) |
| 404 | `NOT_FOUND` | O recurso solicitado não existe ou não pertence à sua organização |
| 429 | `RATE_LIMIT_EXCEEDED` | O limite de requests por minuto foi ultrapassado |
| 429 | `PLAN_LIMIT_REACHED` | O limite de créditos de IA do plano foi atingido |
| 500 | `INTERNAL_ERROR` | Erro interno do servidor |

***

## Limite de taxa (Rate limiting)

A API permite **300 requests por minuto** por API key.

Quando o limite é ultrapassado, a resposta inclui o header `Retry-After` com os segundos que é preciso esperar antes de tentar novamente.

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