Referencia de API — Vista General

URL base, autenticación JWT, rate limits por plan, formato de errores, codigos de estado y versionado.

URL Base

Todas las solicitudes se dirigen a:

https://api.relaai.com/api/v1/

Las solicitudes internas entre microservicios usan:

http://internal-api:8000/api/v1/

Autenticación

La API usa JSON Web Tokens (JWT) emitidos al iniciar sesion. Incluye el token en el header Authorization:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Campo del JWT	Descripción
`sub`	ID del usuario
`tenant_id`	ID del tenant
`role`	Rol del usuario
`permissions`	Lista de permisos
`exp`	Expiracion (15 minutos por defecto)

Los tokens se refrescan via POST /api/v1/auth/refresh con el refresh token.

Rate Limits por Plan

Plan	Requests/min	Burst máximo
Free	30	10
Starter	120	30
Professional	600	100
Enterprise	3,000	500

Headers de respuesta incluidos en cada solicitud:

X-RateLimit-Limit — Limite total de la ventana
X-RateLimit-Remaining — Solicitudes restantes
X-RateLimit-Reset — Timestamp de reset (Unix epoch)

Formato de Errores

Todos los errores siguen un formato consistente:

{
  "detail": "Resource not found",
  "error_code": "NOT_FOUND",
  "request_id": "req_abc123"
}

Codigos de Estado

Codigo	Significado
`200`	Operación exitosa
`201`	Recurso creado
`204`	Eliminado sin contenido
`400`	Solicitud invalida
`401`	No autenticado
`403`	Sin permisos o limite de plan
`404`	Recurso no encontrado
`409`	Conflicto (duplicado)
`422`	Error de validación
`429`	Rate limit excedido
`500`	Error interno del servidor

Paginacion

Los endpoints de listado soportan paginacion con skip y limit:

GET /api/v1/agents?skip=0&limit=20

La respuesta incluye metadatos de paginacion en el cuerpo.

Mapa de routers disponibles

La API real expone ~20 routers en /api/v1/. Las páginas de esta sección cubren los grupos más usados (agents, assets, maintenance, data, admin). Esta tabla es la fuente única de verdad del total:

Prefijo	Propósito	Doc
`/api/v1/whatsapp/agents`	Agentes WhatsApp	whatsapp-agents/create
`/api/v1/whatsapp/numbers`	Números WhatsApp Evolution	whatsapp-agents/numbers
`/api/v1/email`	Agentes email	email-agents/create
`/api/v1/email/accounts`	Cuentas email (Postmark)	email-agents/accounts
`/api/v1/tools`	Tools de agentes	tools/overview
`/api/v1/prompts`	Prompt optimizer (Gemini)	features/prompt-optimizer
`/api/v1/collections`	Colecciones de datos	data/collections
`/api/v1/extraction-templates`	Plantillas de extracción	data/extractions
`/api/v1/extractions`	Extracción IA + CRUD registros	data/extractions
`/api/v1/files`	Upload multipart a GCS	features/file-uploads
`/api/v1/machine`	Gateway de eventos industriales	machine-agents/create
`/api/v1/dashboard`	KPIs del dashboard operacional	features/operational-dashboard
`/api/v1/assets`	Activos industriales	assets-api
`/api/v1/predictive-config`	Config del motor predictivo	maintenance/predictive-config
`/api/v1/reports`	Reportes PDF/Excel on-demand	data/reports
`/api/v1/scheduled-reports`	Reportes programados	data/scheduled-reports
`/api/v1/brandings`	Presets de branding	admin/brandings
`/api/v1/audit`	Audit trail inmutable	admin/audit
`/api/v1/csat`	Encuestas CSAT	features/csat

Todos los endpoints son REST JSON, autenticados con JWT y rate-limited según el plan del tenant. La arquitectura del pipeline está en architecture.

Versionado

La version actual es v1. Cuándo una nueva version este disponible, los headers de deprecacion indicaran la ruta de migracion:

Deprecation: true
Sunset: Sat, 01 Jan 2027 00:00:00 GMT
Link: </api/v2/resource>; rel="successor-version"

Endpoints Internos

Algunos endpoints estan reservados para comunicación entre servicios:

Endpoint	Uso
`POST /internal/events`	Ingesta interna de eventos
`POST /internal/notifications`	Cola de notificaciones
`GET /internal/health`	Health check del servicio

Estos endpoints requieren un token de servicio interno y no estan expuestos en la API publica.

Referencia de API — Vista General

En esta página