API de Workflows

Ruta base: /builder/v1/workflows. Misma autenticación y convenciones que la API de Agentes: Authorization: Bearer <token>, atributos en camelCase, fechas ISO 8601 en UTC, envoltura {"data": ..., "meta": ...}.

Modelo de recursos

Recurso	Descripción
Workflow	Definición (nombre, descripción) y estado: draft, published, paused, needs_attention, archived.
Grafo	Nodos y conexiones del borrador. El catálogo de tipos de nodo se obtiene de GET /workflows/node-types (Nodos y componentes).
Release	Cada publicación crea una versión numerada con su manifiesto; deployment indica cuál está activa.
Connection	Canal de entrada o salida: webhook, WhatsApp, entrada o salida interna. Un webhook tiene URL, token y eventos.
Run	Ejecución con estado (queued, running, paused, completed, failed, cancelled), origen (manual, webhook, scheduled, channel), trace, events, activity y analytics.
Thread / record	Conversación con sus mensajes (thread) y registro de ejecución con sus intercambios (record).
Template	Workflow prearmado que se instancia como uno propio.

Operaciones

Definición y ciclo de vida

Método y ruta	Qué hace
GET /workflows, POST /workflows	Listar y crear.
GET, PATCH, DELETE /workflows/{id}	Leer, editar el borrador, eliminar. GET /workflows/{id}/delete-impact indica qué se afecta antes de borrar (agentes que lo usan como herramienta).
POST /workflows/{id}/validate	Valida el grafo sin publicar: nodos sin conexión, canales incompletos.
POST /workflows/{id}/publish	Publica: crea una release y la activa.
POST /workflows/{id}/pause, /resume	Pausar y reanudar la versión publicada.
POST /workflows/{id}/archive, /restore	Archivar y restaurar. POST /workflows/batch/archive archiva varios.
POST /workflows/{id}/clone	Copia el borrador como un flujo nuevo.
GET /workflows/{id}/export, POST /workflows/import	Exportar e importar la definición (para mover flujos entre Clientes o versionarlos).
POST /workflows/{id}/preview	Ejecuta el borrador con una entrada de prueba sin registrarlo como ejecución.

Versiones

Método y ruta	Qué hace
GET /workflows/{id}/releases	Versiones publicadas.
GET /workflows/{id}/releases/{releaseId}, /manifest, /runtime-status	Detalle de una versión, su manifiesto y si está cargada en el runtime.
GET /workflows/{id}/deployments, POST .../{deploymentId}/activate	Ver qué versión está activa y volver a una anterior.

Canales y webhooks

Método y ruta	Qué hace
GET, PUT /workflows/{id}/connections	Leer y configurar los canales (webhook, WhatsApp, internos).
GET, POST /workflows/{id}/webhooks, GET /.../{webhookId}	Webhooks de entrada del flujo.
POST /workflows/{id}/webhooks/{webhookId}/regenerate-token	Nuevo token; el anterior deja de valer.
GET /workflows/{id}/webhooks/{webhookId}/events, /events/{eventId}	Llamadas recibidas por el webhook y su resultado.
GET /workflows/{id}/webhook-credentials, POST .../inbound/regenerate	Credenciales del webhook de entrada.
GET, POST, DELETE /workflows/{id}/webhook-credentials/outbound[/{id}]	Credenciales que el flujo usa al llamar a sistemas externos (nodo Solicitud HTTP).

Ejecuciones

Método y ruta	Qué hace
GET /workflows/{id}/runs, GET /workflows/runs/summaries	Listar ejecuciones (filtros por origen, periodo y resultado) y resúmenes por flujo.
GET /workflows/{id}/runs/{runId}	Detalle: estado, origen, payload de entrada y salida.
GET .../runs/{runId}/trace, /events, /activity, /analytics	Traza (nodos, herramientas, modelos, errores), eventos, línea de tiempo y métricas de esa ejecución.
POST .../runs/{runId}/cancel, /stop	Cancelar en cola o detener en curso.
POST .../runs/{runId}/resolve-wait	Resolver una Revisión humana: aprobar o rechazar los campos y continuar.

Conversaciones y registros

Método y ruta	Qué hace
GET /workflows/{id}/threads, GET .../threads/{threadId}, GET .../messages	Conversaciones del flujo y sus mensajes. POST /workflows/threads/batch lee varias.
GET, POST, DELETE .../threads/{threadId}/operator-state[/release]	Tomar y soltar el control de una conversación (operador humano), donde la instalación lo permite.
GET /workflows/{id}/records, /records/{recordId}, /records/{recordId}/exchanges	Registros de ejecución (lo que ves en la pestaña Registros) y sus intercambios.
GET .../records/filters, /records/participants	Valores disponibles para filtrar y lista de participantes.
POST .../records/threads/{threadId}/nudge	Reenviar un recordatorio al participante de una conversación.

Métricas, prueba y plantillas

Método y ruta	Qué hace
GET /workflows/{id}/analytics, /analytics/summary, /analytics/runs	Lo que muestra la pestaña Resumen: ejecuciones, duración mediana y p95, tokens, costo del mes, ejecuciones por día.
GET /workflows/{id}/activity	Actividad reciente del flujo.
GET, POST /workflows/{id}/test-agent	El agente de prueba interno de Probar flujo.
GET, POST /workflows/{id}/teams, /teams/{teamId}	Equipos privados del flujo.
GET /workflows/templates, /templates/{templateId}, POST .../instantiate	Plantillas y crear un flujo a partir de una.
POST /workflows/expression/preview	Evaluar una expresión de Condición contra un JSON de ejemplo antes de guardarla.

Disparar un workflow publicado por webhook

curl -X POST "<URL del webhook>" \
  -H "Authorization: Bearer <token del canal>" \
  -H "Content-Type: application/json" \
  -d '{"text": "..."}'

La respuesta trae la salida del nodo Enviar resultado y el identificador de la ejecución. Con Modo asíncrono en el canal, la respuesta es 202 con el identificador y el resultado se consulta en GET /workflows/{id}/runs/{runId}.

Errores

HTTP	code	Cuándo
400	invalid_body	Grafo o configuración inválidos; el mensaje nombra el nodo.
404	workflow_not_found	No existe, no es tuyo o fue eliminado.
409	unpublished_changes	La operación requiere publicar primero.
422	channel_incomplete	Un canal no está configurado; revisa la pestaña Canales.

Rutas y esquemas exactos en el OpenAPI de tu instalación: /builder/v1/openapi.json.