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

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.

---

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.

La API v2 es también la base de las integraciones externas listadas en la página de Integraciones, 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).

---

Autenticación

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

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

{
  "status": "success",
  "data": { ... }
}

Éxito con paginación

{
  "status": "success",
  "data": { ... },
  "pages": {
    "current_page": 1,
    "last_page": 4,
    "per_page": 25,
    "total": 98
  }
}

Error

{
  "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/1.1 429 Too Many Requests
Retry-After: 15

{
  "status": "error",
  "message": "Too many requests",
  "code": "RATE_LIMIT_EXCEEDED"
}