Flows

A flow Beta is an automation that branches. One trigger event enrols a contact — a checkout started, an order placed, a contact created — and from there each contact follows their own path through the steps you place: messages, waits, and branches that route them depending on who they are or what they do. Exit events take a contact out early, typically when the goal of the journey happens: a reminder about an abandoned checkout stops the moment the order arrives.

The Product API lets an integration or an AI assistant turn "remind people who abandon their checkout" into a complete, validated flow that a person can open in the dashboard, review and publish. It does not let you switch one on.

Drafts only

That split is deliberate. A live flow is what reaches contacts and spends balance, so the last step stays with a person who has seen the graph. What the API gives you is everything up to that point:

• Start from a template. GET /flow/templates returns ready-made flows scored against the events the project really receives, each with a graph that already validates. See Templates.
• Create, read, replace and validate the draft. A flow is created together with its first draft, and the draft is always replaced whole. See Creating and editing drafts.
• Write the graph. The trigger and exits, the nodes you may place, and the delays. See Triggers and exits, Nodes and Delays and waits.

The endpoints

Endpoint	What it does	Scope	Rate limit
GET /flow/templates	Lists the templates worth offering this project, with a graph ready to create.	PROJECT_AUTOMATION_READ	medium
POST /flow	Creates a flow with its first draft.	PROJECT_AUTOMATION_WRITE	restrictive
GET /flow/{id}/draft	Reads the draft, with the draftId a replace expects.	PROJECT_AUTOMATION_READ	large
PUT /flow/{id}/draft	Replaces the whole draft.	PROJECT_AUTOMATION_WRITE	restrictive
POST /flow/{id}/draft/validate	Validates a graph without saving anything.	PROJECT_AUTOMATION_WRITE	large
GET /flow	Lists the project's flows, with each one's trigger and exits.	PROJECT_AUTOMATION_READ	large
GET /flow/{id}	Reads one flow.	PROJECT_AUTOMATION_READ	large
GET /flow/{id}/versions	Lists a flow's versions. See Flow reports.	PROJECT_AUTOMATION_READ	large

Every path is relative to /v1/project/{project}. Scopes are chosen when the token is minted, under Project settings → API tokens; PROJECT_AUTOMATION_WRITE only ever produces drafts. See Authentication and Rate limits, where each class ceiling follows the organization's subscription plan.

The two write endpoints that save a draft also require the organization owner to be verified, like creating a campaign: an unverified organization gets a 403 with code: "organization.verification_required".

The life of a flow

A flow is a container with a status — enabled, disabled or archived — that points at versions. The API only ever writes one of them: the draft, the single editable version, which never runs on live traffic.

stateDiagram-v2
    state "Draft only" as DraftOnly
    [*] --> DraftOnly: created through the API (disabled, nothing published)
    DraftOnly --> DraftOnly: draft replaced through the API or the dashboard
    DraftOnly --> Enabled: a person publishes the draft in the dashboard
    Enabled --> Disabled: a person disables it
    Disabled --> Enabled: a person enables it
    Enabled --> Archived: a person archives it
    Disabled --> Archived: a person archives it
    Archived --> [*]
    class Enabled success
    class Archived destructive

• Creating makes a flow that is disabled, with its draft and nothing published.
• Publishing copies the draft into a new, numbered version that new entrants follow. The draft stays as the base for the next change, so editing it later never changes what is live. The first publish switches the flow on by itself, unless the project is already at its plan's limit of enabled flows. A person can also publish a version as a live test that takes a small share of new entrants beside the live one.
• Disabling stops new entries and also halts the contacts already inside: they do not advance while it is off, and those kept waiting too long are cancelled. It is a stop, not a harmless pause.
• Archiving is final: the flow stops and its draft can no longer be replaced.

Versions, their roles and how to report on each one are covered in Flow reports. The customer-facing description of the builder is Flows in the Platform guides.

Reading flows

GET /flow and GET /flow/{id} return each flow's id, name and status, and two fields that help an integration before it creates anything:

What's next