Skip to main content

Flows API

Build visual automation workflows that trigger on events (incoming message, webhook, schedule) and execute multi-step logic — send messages, call APIs, branch on conditions, invoke AI agents, and more. Base path: /api/v1/flows

Create Flow

POST /api/v1/flows Create a new automation flow.
string
required
Flow name
string
required
What starts this flow: manual, webhook, schedule, event, workflow
string
Cron schedule that fires the flow. Required when trigger_type is schedule — a schedule flow submitted without it returns 422 VALIDATION_ERROR. Accepts a standard 5-field cron expression (0 9 * * 1 runs every Monday at 09:00) or a predefined alias such as @hourly, @daily, or @weekly. Ignored for every other trigger type.
string
default:"UTC"
IANA timezone the cron_expr is evaluated in, for example America/New_York. Defaults to UTC. An unrecognized timezone returns 422 VALIDATION_ERROR.
object
required
Flow definition — a JSON object representing the node graph from the visual builder. Contains nodes, edges, and configuration for each step.

Scheduled flows

For a schedule trigger, include cron_expr (and optionally cron_tz) alongside the definition:
cURL

List Flows

GET /api/v1/flows Retrieve all flows with cursor-based pagination.
string
Cursor for pagination
integer
default:"25"
Number of results per page (max 200)

Get Flow

GET /api/v1/flows/{id} Retrieve a flow by ID, including its full definition.
string
required
Flow ID (e.g., flw_abc123)

Validate Flow

GET /api/v1/flows/{id}/validate Check a flow’s definition for structural problems before publishing: a missing trigger node, disconnected nodes, nodes without an id or type, misweighted A/B split variants, and infinite loops (a cycle with no delay or wait node). Returns a list of problems — an empty errors list means the flow is publishable. Read-only.
string
required
Flow ID

Update Flow

PUT /api/v1/flows/{id} Update a flow’s name, trigger, or definition. Each update increments the version number.
string
required
Flow ID
string
Updated flow name
string
Updated trigger type
string
Cron schedule for a schedule trigger. Required whenever the flow’s effective trigger_type is schedule — you can update the schedule on an existing schedule flow by sending cron_expr alone. An empty or unparseable expression returns 422 VALIDATION_ERROR.
string
default:"UTC"
IANA timezone the cron_expr is evaluated in. Defaults to UTC.
object
Updated flow definition (node graph)
integer
Expected current version (for optimistic concurrency control). The update is rejected if the stored version does not match.

Delete Flow

DELETE /api/v1/flows/{id} Delete a flow. Running executions are allowed to complete but no new executions will start.
string
required
Flow ID
Response: 204 No Content

Publish Flow

POST /api/v1/flows/{id}/publish Validate and publish a flow. The current definition is validated (the same checks as Validate Flow), frozen as an immutable version snapshot, and the flow’s status is set to published. Publishing a flow that fails validation returns 422 VALIDATION_ERROR with the list of problems.
string
required
Flow ID

Unpublish Flow

POST /api/v1/flows/{id}/unpublish Take a published flow out of live execution and return it to draft. Only a published flow can be unpublished — calling this on a draft or archived flow returns 422 VALIDATION_ERROR.
string
required
Flow ID

Execute Flow

POST /api/v1/flows/{id}/execute Run a flow immediately with an explicit trigger payload. The payload is available to every node as trigger_data. Returns 202 Accepted with the execution record. Concurrent executions are capped per workspace; exceeding the cap returns 429. Rate limited to 10 requests per minute.
string
required
Flow ID
object
default:"{}"
Arbitrary key/value payload passed to the flow’s nodes as trigger_data.

Enroll Contacts in a Flow

POST /api/v1/flows/{id}/start Enroll a single contact or an entire list into a flow — the high-level enrollment entry point for programmatic and agent-driven use. Pass exactly one of contact_id or list_id, plus an optional context object that is merged into each enrollment’s trigger_data. Returns 202 Accepted. Rate limited to 10 requests per minute.
string
required
Flow ID
string
Enroll a single contact. Returns { "mode": "single", "execution": { ... } }.
string
Enroll every member of a contact list (up to 500 members). Returns { "mode": "list", "attempted": N, "enrolled": M }. Lists larger than 500 members return 413 — use bulk enrollment for large audiences instead.
object
Optional key/value data merged into each enrollment’s trigger_data.

List Flow Versions

GET /api/v1/flows/{id}/versions List the saved version snapshots for a flow, newest first. Each publish writes a snapshot, and operators can also save manual snapshots from the builder.
string
required
Flow ID

Create Flow Version

POST /api/v1/flows/{id}/versions Save a manual snapshot of the flow’s current definition. With an empty body the server snapshots the flow’s current definition. Returns 201 Created with the new version.
string
required
Flow ID
object
Definition to snapshot. Defaults to the flow’s current stored definition.
string
Optional short description of what changed in this version.

Restore Flow Version

POST /api/v1/flows/{id}/versions/{versionId}/restore Restore an earlier snapshot onto the flow’s draft definition. The flow’s status is unchanged — a published flow keeps serving its published version until you publish the restored draft.
string
required
Flow ID
string
required
Version snapshot ID to restore.

Export Flow

GET /api/v1/flows/{id}/export Export a flow as portable, vendor-neutral JSON. The document captures the flow definition, its trigger and schedule, and — unless include_agents=false — the full configuration of every AI agent the flow references, so you can move your work to another platform or keep an offline backup. The response body is the export document itself, with no envelope.
string
required
Flow ID
boolean
default:"true"
Inline the configuration of every agent the flow references. Set to false to export only the flow definition.
boolean
default:"false"
When true, sets a Content-Disposition header so a browser downloads the export as a file.

List Flow Templates

GET /api/v1/flows/templates Return the built-in starter templates shown in the flow builder’s “New Flow” dialog — welcome messages, OTP verification, abandoned-cart reminders, lead nurture, support escalation, and more. Each template includes its trigger type, channels, and a ready-to-use definition you can pass straight to Create Flow.

List Executions

GET /api/v1/flows/executions Retrieve flow execution logs across all flows, ordered by most recent.
string
Cursor for pagination
integer
default:"25"
Number of results per page (max 200)

Get Execution

GET /api/v1/flows/executions/{id} Retrieve a single flow execution by ID, including its full trigger payload and step-by-step trace — each node’s name, status, duration, and any error. Returns 404 if the execution does not exist.
string
required
Execution ID (e.g., exec_001)

Get Executions Summary

GET /api/v1/flows/executions/summary Aggregate execution statistics over a rolling started_at window — total count, a completed/failed/running breakdown, and average duration. Powers the flow-executions dashboard stat cards so totals stay accurate across every execution, not just the currently loaded page. Read-only.
string
Restrict the aggregate to a single flow.
string
Restrict the aggregate to executions in this status: running, waiting, completed, completed_with_errors, failed, timeout.
integer
default:"30"
Rolling started_at window in days, clamped to [1, 365]. Pass 1 for a last-24h (“today”) count.

Flow Analytics

GET /api/v1/flows/{id}/analytics Per-flow conversion funnel: how many contacts entered and completed the flow, a per-node drop-off funnel in flow-graph traversal order, and goal attribution (event or trait) within the configured window after a contact exits the flow. The conversion goal defaults to the flow’s stored definition.conversionGoal and can be overridden per request. Read-only aggregation over the executions log.
string
required
Flow ID (e.g., flw_abc123)
string
Lower bound (inclusive) of the entry window — executions started at or after this ISO-8601 timestamp.
string
Upper bound of the entry window — executions started before this ISO-8601 timestamp.
integer
Goal attribution window in days after a contact exits the flow, clamped to [1, 365].
string
Override the flow’s stored goal — count this event as the conversion.
string
Override the flow’s stored goal — count an identify call setting this trait as the conversion.
string
When goal_trait is set, only count the conversion when the trait is set to this value.

A/B Test Results

GET /api/v1/flows/{id}/ab-results Per-variant results for every in-flow A/B test (abTest) node: how many contacts were assigned to each variant, how many completed and converted, the conversion (or completion) rate per variant, and the leading variant. Accepts the same goal and window overrides as Flow Analytics. Read-only.
string
required
Flow ID (e.g., flw_abc123)
string
Lower bound (inclusive) of the entry window — executions started at or after this ISO-8601 timestamp.
string
Upper bound of the entry window — executions started before this ISO-8601 timestamp.
integer
Goal attribution window in days after a contact exits the flow, clamped to [1, 365].
string
Override the flow’s stored goal — count this event as the conversion.
string
Override the flow’s stored goal — count an identify call setting this trait as the conversion.
string
When goal_trait is set, only count the conversion when the trait is set to this value.