Workflows API

In the paths, the resource is named workflows, in English. The interface calls them flujos (workflows); the API says workflows.

Base path: /builder/v1/workflows. Same authentication and conventions as the Agents API: Authorization: Bearer <token>, attributes in camelCase, dates in ISO 8601 UTC, {"data": ..., "meta": ...} envelope.

Resource model

Resource	Description
Workflow	Definition (name, description) and status: draft, published, paused, needs_attention, archived.
Graph	Nodes and connections of the draft. The catalog of node types is obtained from GET /workflows/node-types (Nodes and components).
Release	Each publication creates a numbered version with its manifest; deployment indicates which one is active.
Connection	Input or output channel: webhook, WhatsApp, internal input or output. A webhook has a URL, a token and events.
Run	Run with status (queued, running, paused, completed, failed, cancelled), origin (manual, webhook, scheduled, channel), trace, events, activity and analytics.
Thread / record	Conversation with its messages (thread) and run record with its exchanges (record).
Template	Prebuilt workflow that you instantiate as your own.

Operations

Definition and lifecycle

Method and path	What it does
GET /workflows, POST /workflows	List and create.
GET, PATCH, DELETE /workflows/{id}	Read, edit the draft, delete. GET /workflows/{id}/delete-impact indicates what is affected before deleting (agents that use it as a tool).
POST /workflows/{id}/validate	Validates the graph without publishing: unconnected nodes, incomplete channels.
POST /workflows/{id}/publish	Publishes: creates a release and activates it.
POST /workflows/{id}/pause, /resume	Pause and resume the published version.
POST /workflows/{id}/archive, /restore	Archive and restore. POST /workflows/batch/archive archives several.
POST /workflows/{id}/clone	Copies the draft as a new workflow.
GET /workflows/{id}/export, POST /workflows/import	Export and import the definition (to move workflows between Clients or to version them).
POST /workflows/{id}/preview	Runs the draft with a test input without recording it as a run.

Versions

Method and path	What it does
GET /workflows/{id}/releases	Published versions.
GET /workflows/{id}/releases/{releaseId}, /manifest, /runtime-status	Detail of a version, its manifest and whether it is loaded in the runtime.
GET /workflows/{id}/deployments, POST .../{deploymentId}/activate	See which version is active and go back to an earlier one.

Channels and webhooks

Method and path	What it does
GET, PUT /workflows/{id}/connections	Read and configure the channels (webhook, WhatsApp, internal).
GET, POST /workflows/{id}/webhooks, GET /.../{webhookId}	Inbound webhooks of the workflow.
POST /workflows/{id}/webhooks/{webhookId}/regenerate-token	New token; the previous one stops working.
GET /workflows/{id}/webhooks/{webhookId}/events, /events/{eventId}	Calls received by the webhook and their result.
GET /workflows/{id}/webhook-credentials, POST .../inbound/regenerate	Credentials of the inbound webhook.
GET, POST, DELETE /workflows/{id}/webhook-credentials/outbound[/{id}]	Credentials that the workflow uses when it calls external systems (the Solicitud HTTP, or HTTP request, node).

Runs

Method and path	What it does
GET /workflows/{id}/runs, GET /workflows/runs/summaries	List runs (filters by origin, period and result) and summaries per workflow.
GET /workflows/{id}/runs/{runId}	Detail: status, origin, input and output payload.
GET .../runs/{runId}/trace, /events, /activity, /analytics	Trace (nodes, tools, models, errors), events, timeline and metrics of that run.
POST .../runs/{runId}/cancel, /stop	Cancel while queued or stop while in progress.
POST .../runs/{runId}/resolve-wait	Resolve a Revisión humana (Human review): approve or reject the fields and continue.

Conversations and records

Method and path	What it does
GET /workflows/{id}/threads, GET .../threads/{threadId}, GET .../messages	Conversations of the workflow and their messages. POST /workflows/threads/batch reads several.
GET, POST, DELETE .../threads/{threadId}/operator-state[/release]	Take and release control of a conversation (human operator), where the installation allows it.
GET /workflows/{id}/records, /records/{recordId}, /records/{recordId}/exchanges	Run records (what you see in the Registros, or Logs, tab) and their exchanges.
GET .../records/filters, /records/participants	Values available for filtering and list of participants.
POST .../records/threads/{threadId}/nudge	Resend a reminder to the participant of a conversation.

Metrics, testing and templates

Method and path	What it does
GET /workflows/{id}/analytics, /analytics/summary, /analytics/runs	What the Resumen (Summary) tab shows: runs, median and p95 duration, tokens, cost for the month, runs per day.
GET /workflows/{id}/activity	Recent activity of the workflow.
GET, POST /workflows/{id}/test-agent	The internal test agent of Probar flujo (Test workflow).
GET, POST /workflows/{id}/teams, /teams/{teamId}	Private teams of the workflow.
GET /workflows/templates, /templates/{templateId}, POST .../instantiate	Templates, and creating a workflow from one.
POST /workflows/expression/preview	Evaluate a Condición (Condition) expression against a sample JSON before saving it.

Trigger a published workflow by webhook

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

The response includes the output of the Enviar resultado (Send result) node and the identifier of the run. With Modo asíncrono (Async mode) on the channel, the response is 202 with the identifier, and you query the result at GET /workflows/{id}/runs/{runId}.

Errors

HTTP	code	When
400	invalid_body	Invalid graph or configuration; the message names the node.
404	workflow_not_found	It does not exist, is not yours, or was deleted.
409	unpublished_changes	The operation requires publishing first.
422	channel_incomplete	A channel is not configured; check the Canales (Channels) tab.

Exact paths and schemas in your installation's OpenAPI: /builder/v1/openapi.json.