Descripcion General de la API

La API REST de VOCALS te permite gestionar agentes, iniciar llamadas, configurar proveedores y consultar analiticas de forma programatica. Todos los endpoints se sirven bajo una unica URL base y requieren autenticacion.

URL Base

https://api.usevocals.com/api/v1

Todas las rutas en esta documentacion son relativas a la URL base. Por ejemplo, GET /agents significa GET https://api.usevocals.com/api/v1/agents.

Autenticacion

VOCALS soporta dos metodos de autenticacion. Cada solicitud debe incluir uno de ellos.

Bearer JWT (Supabase Auth)

Autenticate con un JWT de Supabase obtenido a traves del flujo estandar de Supabase Auth (email/contrasena, OAuth, etc.). Pasalo en el header Authorization:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

El JWT contiene la identidad del usuario y se resuelve automaticamente a un tenant. Este metodo es utilizado por el frontend del dashboard y es adecuado para integraciones orientadas al usuario.

API Key (X-API-Key)

Para casos de uso servidor-a-servidor y automatizacion (n8n, Make, scripts personalizados), genera una API key desde el dashboard o a traves del endpoint /api-keys, y pasala en el header X-API-Key:

X-API-Key: voc_a1b2c3d4e5f6...

Las API keys estan vinculadas a un tenant y tienen sus propios limites de tasa. La clave completa solo se muestra una vez en el momento de la creacion.

Cuando ambos headers estan presentes, la API key tiene prioridad.

Limites de Tasa

Los limites de tasa se aplican por API key usando contadores de Redis. Cada clave tiene dos umbrales:

Limite	Por defecto	Descripcion
rate_limit_rpm	300	Solicitudes maximas por minuto
rate_limit_rpd	50,000	Solicitudes maximas por dia

Cuando se excede un limite, la API devuelve 429 Too Many Requests con un cuerpo de error en JSON. Puedes ver y ajustar los limites de tasa a traves del endpoint /rate-limits.

Las solicitudes autenticadas mediante Bearer JWT no estan sujetas a los limites de tasa de API key.

Headers Comunes

Header	Requerido	Descripcion
Authorization	Condicional	Bearer <jwt> para Supabase Auth
X-API-Key	Condicional	Cadena de API key (alternativa a Bearer)
Content-Type	Si (para POST/PUT)	Siempre application/json

Formato de Respuesta de Error

Todos los errores siguen una estructura JSON consistente:

{
  "detail": "Human-readable error message"
}

Para errores de validacion (422), FastAPI devuelve el formato estandar:

{
  "detail": [
    {
      "loc": ["body", "name"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}

Codigos de Estado HTTP

Codigo	Significado
200	Exito
201	Recurso creado
202	Aceptado (operaciones asincronas como llamadas salientes)
204	Eliminado exitosamente (sin cuerpo)
400	Solicitud incorrecta (entrada invalida, configuracion faltante)
401	No autorizado (autenticacion faltante o invalida)
404	Recurso no encontrado
422	Error de validacion (cuerpo de solicitud malformado)
429	Limite de tasa excedido
500	Error interno del servidor

Paginacion

Los endpoints que devuelven listas soportan paginacion con estos parametros de consulta:

Parametro	Tipo	Por defecto	Descripcion
page	integer	1	Numero de pagina (indexado desde 1)
page_size	integer	20	Elementos por pagina (maximo 100)

Las respuestas paginadas incluyen metadatos:

{
  "items": [...],
  "total": 142,
  "page": 1,
  "page_size": 20
}

Multi-Tenancy

VOCALS es multi-tenant. Todos los datos estan limitados al tenant asociado con tus credenciales de autenticacion. No puedes acceder a recursos pertenecientes a otros tenants. El tenant se resuelve automaticamente desde tu JWT o API key -- no hay un header de tenant ID que configurar.

Ejemplo Rapido

# Listar todos los agentes
curl -H "X-API-Key: voc_your_key_here" \
  https://api.usevocals.com/api/v1/agents

# Iniciar una llamada saliente
curl -X POST \
  -H "X-API-Key: voc_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"to_number": "+15551234567", "agent_id": "uuid-here"}' \
  https://api.usevocals.com/api/v1/calls