Referencia de API — Vista General

URL base, autenticacion 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/

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

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Campo del JWT	Descripcion
`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.

Headers de respuesta incluidos en cada solicitud:

Todos los errores siguen un formato consistente:

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

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.

La version actual es v1. Cuando 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"

Algunos endpoints estan reservados para comunicacion 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.