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

# Introducción a la API

> Autenticación, scopes, formato de respuesta, errores y límites de tasa de la API pública de ChatNorris.

# API Pública v2

La API v2 de ChatNorris te permite integrar y automatizar tu plataforma de agentes IA desde cualquier aplicación externa. Podés gestionar agentes, enviar mensajes, leer conversaciones, leads y más.

**Base URL:**

```
https://app.chatnorris.ai/api/v2
```

<Note>
  El acceso a la API está disponible en los planes **Standard** y **Plus**. Para habilitarlo, necesitás una API key activa. En el plan Free, la sección de API keys aparece bloqueada — al intentar crear una key se te redirige a la página de planes.
</Note>

***

## Generar una API key

1. Ingresá a tu cuenta y andá a **Configuración → API Keys**.
2. Hacé clic en **+ Nueva API key**.
3. Asignale un nombre descriptivo (ej. "Integración CRM").
4. Seleccioná los **scopes** que necesitás (ver más abajo).
5. Copiá la key generada — se muestra una sola vez. Guardala en un lugar seguro.

Si perdés la key, debés eliminarla y crear una nueva.

<Tip>
  La API v2 es también la base de las integraciones externas listadas en la página de [Integraciones](https://chatnorris.ai/integrations), como **Zapier**: no hay una app dedicada, se conecta usando tu API key y los endpoints de esta referencia (por ejemplo `chat:write` para disparar respuestas del agente desde un Zap).
</Tip>

***

## Autenticación

Todas las requests deben incluir la API key en el header `Authorization` como Bearer token:

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

Las requests sin key o con key inválida reciben `401 Unauthorized`.

***

## Scopes

Cada API key tiene uno o más scopes que limitan qué endpoints puede usar. Al crear la key, elegís los permisos que necesitás:

| Scope                | Acceso                                         |
| -------------------- | ---------------------------------------------- |
| `chatbots:read`      | Listar, obtener agentes y fuentes de knowledge |
| `chatbots:write`     | Crear, actualizar, eliminar agentes y fuentes  |
| `chat:write`         | Enviar mensajes a través de un agente          |
| `conversations:read` | Listar y obtener conversaciones y mensajes     |
| `leads:read`         | Listar y obtener leads                         |
| `channels:read`      | Listar canales conectados                      |
| `*`                  | Acceso completo a todos los scopes             |

Los endpoints de **proyecto**, **miembros** y **uso** no requieren scope específico — solo autenticación válida.

Si la key no tiene el scope necesario, la respuesta es `403 INSUFFICIENT_SCOPE`.

***

## Formato de respuesta

Todas las respuestas son JSON con la siguiente estructura:

### Éxito

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

### Éxito con paginación

```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": "Descripción del error",
  "code": "CODIGO_ERROR"
}
```

***

## Paginación

Los endpoints de listado soportan paginación mediante query params:

| Parámetro  | Tipo    | Default | Descripción                          |
| ---------- | ------- | ------- | ------------------------------------ |
| `page`     | integer | `1`     | Número de página (comienza en 1)     |
| `per_page` | integer | `25`    | Resultados por página (máximo `100`) |

***

## Códigos de error

| Código HTTP | Code                  | Descripción                                                      |
| ----------- | --------------------- | ---------------------------------------------------------------- |
| 400         | `INVALID_INPUT`       | El cuerpo de la request no pasa la validación                    |
| 401         | `AUTH_REQUIRED`       | Falta el header `Authorization`                                  |
| 401         | `INVALID_API_KEY`     | La API key no existe, está inactiva o el formato es inválido     |
| 403         | `INSUFFICIENT_SCOPE`  | La key no tiene el scope necesario para este endpoint            |
| 403         | `PLAN_LIMIT_REACHED`  | Se alcanzó el límite del plan (agentes, mensajes, etc.)          |
| 404         | `NOT_FOUND`           | El recurso solicitado no existe o no pertenece a tu organización |
| 429         | `RATE_LIMIT_EXCEEDED` | Se superó el límite de requests por minuto                       |
| 429         | `PLAN_LIMIT_REACHED`  | Se alcanzó el límite de mensajes del plan                        |
| 500         | `INTERNAL_ERROR`      | Error interno del servidor                                       |

***

## Límite de tasa (Rate limiting)

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

Cuando se supera el límite, la respuesta incluye el header `Retry-After` con los segundos que hay que esperar antes de reintentar.

```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"
}
```