Referencia de la API

2 min de lectura

Aquí está cada endpoint: qué recibe, qué devuelve y qué permiso exige. Lo que significa cada cosa —qué es un agente, un canal o una skill— está en el manual; esto es la ficha técnica.

API del plano de control: organizaciones, agentes, recursos (skills, memorias, servidores MCP, credenciales), comunicación (canales, inbox, aprobaciones), tareas programadas, auditoría y facturación.

Autenticación

Las integraciones se autentican con un token de servicio en cada petición:

Authorization: Bearer kjtk_live_…

El token se crea desde el panel (Ajustes → Tokens de servicio), pertenece a una organización y lleva sus propios permisos (scopes). El secreto completo solo se muestra una vez, al crearlo — guárdalo en un gestor de secretos. Se puede revocar en cualquier momento desde el mismo panel.

Rutas y organizaciones

Todas las rutas van bajo el prefijo /v1. Los recursos de una organización viven bajo /v1/org/{org_id}/…: el token solo ve su organización — pedir la de otro responde 404, sin revelar si existe.

Cada endpoint indica el permiso que exige (recurso.accion, p. ej. agent.view). Un token sin ese scope recibe 403.

Errores

Las respuestas de error comparten una misma forma:

{ "status": 403, "code": "PERMISSION_DENIED", "message": "…" }

code es estable y es sobre lo que conviene ramificar en código; message es un texto de apoyo. Los errores de validación añaden una lista errors con el detalle por campo.

Límites de peticiones

Ventanas de 60 segundos por IP: 600 peticiones sobre cualquier ruta como techo general, con cupos estrictos en superficies sensibles (autenticación 10/min, webhooks públicos 120/min, soporte 20/min). Superado un límite, la API responde 429 con el header Retry-After.

Más ayuda

Guías y conceptos de la plataforma: docs.kujira.so.

Contrato OpenAPI

La referencia de esta web se genera desde una copia sincronizada del contrato. Para importar el contrato que publica la plataforma en este momento, usa

OpenAPI JSON actual.

También está disponible la copia de esta documentación, útil para generar un cliente contra la versión que estás leyendo o comparar revisiones.

Antes de la primera llamada

Necesitas un token de servicio: se crea desde el panel y es lo que va en la cabecera Authorization. Cómo se crea y qué permisos darle está en Tokens de servicio.