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, workflowstring
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 aschedule 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
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.