Introducción
La API v1 de Kadu le da a otro sistema todo lo que hace el Agent Console: listar y lanzar tareas, seguir ejecuciones (logs, eventos, pendientes, archivos), configurar entornos, secrets, programaciones y webhooks, sincronizar el Playbook y consultar uso y costo.
Direcciones
| Entorno | URL base |
|---|---|
| Producción | https://api.kadu.ia.br/v1 |
| Staging | https://api.staging.kadu.ia.br/v1 |
curl -H "Authorization: Bearer $KOBANA_TOKEN" \
https://api.kadu.ia.br/v1/me
Toda ruta exige un access token de la Cuenta Kobana en el header
Authorization: Bearer. Ver Autenticación.
Qué se puede hacer
| Recurso | Endpoints | Para qué |
|---|---|---|
| Identidad | /v1/me | verificar de quién es el token |
| Organización | /v1/organizations | leer y modificar la organización del token |
| Estructura | /v1/workspaces, /v1/activities, /v1/tasks | el árbol de tareas |
| Lanzamiento | POST /v1/tasks/{id}/run, GET /v1/tasks/{id}/readiness | ejecutar una tarea y verificar antes si el entorno está listo |
| Ejecuciones | /v1/executions, /logs, /events, /todos, /cancel, /continue, /v1/executions/search | seguir, cancelar, continuar una tarea conversacional y buscar |
| Pendientes | PATCH /v1/todos/{id} | resolver un pendiente |
| Archivos | /v1/files | enviar archivos de entrada y descargar los de salida |
| Configuración | /v1/environments, /v1/secrets, /v1/schedules, /v1/tasks/{id}/endpoint | entornos, credenciales, programaciones y el endpoint de lanzamiento |
| Integraciones | /v1/webhooks, /v1/webhook_deliveries | webhooks, entregas y reenvío |
| Repositorio | /v1/repository, POST /v1/repository/sync | estado y sincronización del Playbook |
| Uso | /v1/usage | tokens, costo y precio por período |
| Personas | /v1/users, /v1/memberships, /v1/roles | miembros, vínculos y roles |
| Memoria | /v1/memories | registros que la organización guarda por entidad |
| Eventos | /v1/system_events | eventos de la organización |
La referencia completa de cada endpoint está en Recursos, generada a partir de la especificación OpenAPI (Especificación).
El contrato en una pantalla
- JSON en
snake_caseen ambos sentidos. - Éxito:
{ "data": … }o{ "data": […], "meta": { "next_cursor", "limit" } }. - Error:
{ "error": { "code", "message", "details" } }, concodeenUPPER_SNAKE_CASE. - Listados por cursor (Paginación).
X-Idempotency-Keyen todoPOST,PUTyPATCH(Idempotencia).- 600 solicitudes por minuto por token (Límites).
Detalles en Convenciones.
Desde la terminal
La CLI kobana llama a todos estos endpoints desde la
línea de comandos (kobana kadu tasks run, kobana kadu executions logs), con
el mismo token.
Lanzamiento sin la API
Para que un sistema lance una tarea específica sin token de la Cuenta Kobana, usa el endpoint de lanzamiento: una URL por tarea, con credencial propia.