Referencia de Endpoints¶

Referencia técnica completa de la API de Neuron AI Studio. Cada endpoint documenta método, path, parámetros, ejemplos de request/response, autenticación, scope, rate limit y códigos de error.

La misma referencia, en otras dos formas

· Probar los endpoints — esta misma información, desplegable y con botón para ejecutar las consultas de lectura contra tu organización. · Ciclo de vida de una campaña — si buscabas el recorrido completo en orden en vez del contrato suelto.

Base URL (todos los endpoints):

https://api.neuronstudio.ai

La URL de Producción se aprovisiona durante tu onboarding. Todos los ejemplos de esta documentación usan https://api.neuronstudio.ai.

Autenticación en una línea¶

Server-to-server (recomendado): API Key en el header X-API-Key.
Sesión / navegador: JWT vía POST /api/auth/login → Authorization: Bearer <token>.
La organización va implícita en tu API Key — no existe un header de tenant.
Detalle completo en auth.md.

Los 18 endpoints¶

Autenticación → auth.md ¶

#	Método	Path	Auth	Scope	Rate limit
1	`POST`	`/api/auth/login`	—	—	5 / 5 min por IP

Campañas → campaigns.md ¶

#	Método	Path	Auth	Scope	Rate limit
2	`POST`	`/api/campaign/start`	API Key / JWT	`full`	5 / min por org
3	`POST`	`/api/campaign/start-upload`	API Key / JWT	`full`	5 / min por org
4	`GET`	`/api/campaign/status`	API Key / JWT	lectura	—
5	`POST`	`/api/campaign/stop`	API Key / JWT	`full`	—
6	`POST`	`/api/campaign/pause`	API Key / JWT	`full`	—
7	`POST`	`/api/campaign/resume`	API Key / JWT	`full`	—
8	`POST`	`/api/campaign/schedule`	API Key / JWT	`full`	10 / 5 min por org
9	`GET`	`/api/campaign/scheduled`	API Key / JWT	lectura	—
10	`DELETE`	`/api/campaign/scheduled/{campaign_id}`	API Key / JWT	`full`	—
11	`GET`	`/api/campaigns`	API Key / JWT	lectura	100 / min
12	`GET`	`/api/csv-template`	API Key / JWT	lectura	—
13	`GET`	`/api/campaigns/{campaign_id}/skip-log`	API Key / JWT	lectura	—

Analítica y resultados → analytics.md ¶

#	Método	Path	Auth	Scope	Rate limit
14	`GET`	`/api/analytics/stats`	API Key / JWT	lectura	30 / min
15	`GET`	`/api/analytics/calls`	API Key / JWT	lectura	—
16	`GET`	`/api/analytics/call/{call_id}`	API Key / JWT	lectura	—
17	`GET`	`/api/analytics/export`	API Key / JWT	lectura	60 / hora por org

Agentes → agents.md ¶

#	Método	Path	Auth	Scope	Rate limit
18	`GET`	`/api/agents`	API Key / JWT	lectura	—

Scopes¶

Scope	Qué puede hacer
`read`	Solo métodos `GET` (lecturas). Un `POST` / `PATCH` / `DELETE` con scope `read` devuelve 403.
`full`	Todo el ciclo: iniciar, detener, pausar, reanudar, programar campañas + todas las lecturas.

Las API Keys las emite un administrador de tu organización. Solicita tu API Key a tu contacto de Neuron o al administrador de tu organización.

Tipos de campaña / agente¶

El campo campaign_type (y agent_type) admite estos valores:

Valor	Uso
`collections`	Cobranza (valor por defecto).
`sdr`	Prospección / ventas (SDR).
`cx`	Experiencia de cliente / soporte.
`interviewer`	Entrevistas.

Obtener resultados¶

No existen webhooks salientes hacia el cliente. Los resultados se obtienen por polling con GET /api/analytics/calls (paginación por cursor) más GET /api/analytics/call/{call_id} para el detalle. Patrón recomendado en results-polling.md.

La entrega por webhooks (push) está en desarrollo; hoy la sincronización es por consulta (polling).

Forma de los errores¶

Todas las respuestas de error comparten esta forma sanitizada:

{
  "success": false,
  "error": "<mensaje genérico>",
  "error_id": "<uuid>",
  "request_id": "<uuid>"
}

Código	Significado
`400`	Error de validación (CSV inválido, campos faltantes).
`401`	No autenticado (API Key o token inválido / ausente).
`403`	Scope insuficiente, o agente no asignado a la organización.
`404`	Recurso no encontrado.
`409`	Límite de campañas: ya hay una campaña corriendo.
`422`	Funcionalidad no habilitada para tu organización.
`429`	Límite de tasa excedido. Incluye el header `Retry-After`.

No se devuelven headers X-RateLimit-*. El cliente infiere el límite a partir del 429 y del header Retry-After. Cita error_id y request_id cuando contactes a soporte.