API REST
La API vive en http://localhost:13333/api. El listado completo de rutas y métodos está en el índice de rutas, generado desde el código.
Convenciones
Sección titulada «Convenciones»- Todo es JSON. Muchas rutas responden
{ ok: true, ... }, pero no todas: algunas devuelven el objeto directo (por ejemplo,POST /api/tasksdevuelve{ task }). Los errores vienen como{ error, code? }con un status 4xx o 5xx. - El workspace va en
?workspace_id=o en el headerx-workspace-id. Lo que se crea sin workspace va aws-default; los listados sin filtro devuelven todos los workspaces. - Los cambios se registran con un actor:
created_byoagentIden el body, ox-taia-actoren settings.
| Endpoint | Método | Para qué |
|---|---|---|
/api/tasks |
GET |
Listar. Filtros: status, project, project_id, assigned_to, priority, q, workspace_id, done_since_days |
/api/tasks |
POST |
Acciones: { "action": "create", "task": {…} }, { "action": "move", "taskId", "status" }, { "action": "update", "taskId", "updates": {…} } |
/api/tasks/[id] |
GET, PUT (o PATCH), DELETE |
Leer, actualizar y borrar |
/api/tasks/assign |
POST |
Asignar a un agente |
/api/tasks/[id]/subtasks |
GET, POST, PUT |
Subtareas (PUT reordena) |
/api/tasks/[id]/subtasks/[sid] |
PUT, DELETE |
Una subtarea |
/api/tasks/[id]/dependencies |
GET, POST, DELETE |
Dependencias (con detección de ciclos) |
/api/tasks/[id]/messages |
GET, POST |
Hilo de la tarea |
/api/tasks/[id]/tags |
POST, DELETE |
Tags |
/api/tasks/[id]/trajectories |
GET, POST |
Historial de cambios |
/api/tasks/[id]/cost |
GET |
Costo de la tarea |
El status tiene que ser una columna del workspace de la tarea; si no, la API responde 400 INVALID_STATUS (Workspaces y columnas).
Workspaces y columnas
Sección titulada «Workspaces y columnas»/api/workspaces (GET, POST), /api/workspaces/[id] (GET, PUT, DELETE), /api/workspaces/[id]/columns (GET, POST), /api/workspaces/[id]/columns/[columnId] (PUT, DELETE), /api/workspaces/[id]/columns/reorder (POST) y /api/workspaces/presets (GET).
Agentes
Sección titulada «Agentes»| Endpoint | Método | Para qué |
|---|---|---|
/api/agents |
GET, POST |
Listar (con datos del runtime de cada uno) y crear |
/api/agents/[id] |
GET, PUT, DELETE |
Un agente |
/api/agents/[id]/context |
GET, PATCH |
Identidad y contexto (con versiones en /versions) |
/api/agents/[id]/runtime-settings |
GET, PATCH |
Modelo y tools del agente en su runtime |
/api/agents/[id]/transcript, /live, /stream |
GET |
Transcripción y eventos en vivo |
/api/agents/[id]/trigger |
POST |
Despertar al agente ahora |
/api/agents/[id]/cron |
GET, POST, PATCH, DELETE |
Heartbeat (Cron) |
/api/agents/[id]/memory, /working-state |
GET, PUT |
Memoria y estado de trabajo |
/api/agents/[id]/cost |
GET |
Costo del agente |
Runtime y sesiones
Sección titulada «Runtime y sesiones»/api/runtime/health (estado de cada instancia y un agregado), /api/sessions, /api/sessions/active, /api/sessions/[key]/history (?instance=), /api/models, /api/gateway/config (config cruda, ?instance=) y /api/settings/test-connection (POST).
- Proyectos:
/api/projectsy/api/projects/[id], con/contexty/repositories. - Filtros, templates y tags:
/api/filters,/api/templates,/api/tag-colors. - Planificación, QA, webhooks e importación: ver las guías.
- Aprobaciones y costos:
/api/approvals,/api/cost/dashboardy/api/cost/sync. - Actividad y métricas:
/api/activities,/api/stats,/api/usage-analyticsy/api/standup(GET, texto o?format=json). - Settings:
/api/settings(GET,PUT,DELETE; las claves sensibles vuelven enmascaradas) y/api/settings/audit. - Salud:
/api/health,/api/health/migrations,/api/health/event-busy/api/runtime-target.
WebSocket
Sección titulada «WebSocket»El navegador se conecta a ws://localhost:13334 (en producción, wss://<dominio>/ws vía Caddy) y recibe mensajes { type, payload, timestamp }:
| Evento | Cuándo |
|---|---|
connected |
Al conectarse |
task:created, task:updated, task:moved, task:deleted |
Cambios en tareas |
agent:status |
Cambio de estado de un agente |
activity:new |
Nueva entrada de actividad |
worktree:created, worktree:updated, worktree:merged |
Worktrees |
dependency:added, dependency:removed |
Dependencias |
Es solo de lectura: el servidor no reenvía mensajes que mandan los clientes.