# Flows

How the Product API models a flow: a branching automation made of a trigger event, steps and exits. This page covers the drafts-only contract, the endpoints and scopes, and how a flow moves from an API draft to something a person publishes in the dashboard.

**Language:** en
**Audience:** developer
**TLDR:** A flow is a branching automation: one trigger event enrols a contact, who then follows their own path through sends, waits and branches until an exit event or the end. The Product API creates and edits flow DRAFTS only: POST /flow, GET and PUT /flow/{id}/draft, POST /flow/{id}/draft/validate, plus GET /flow/templates to start from a ready-made graph. Publishing, enabling, disabling and archiving stay in the dashboard. Reads need PROJECT_AUTOMATION_READ, writes PROJECT_AUTOMATION_WRITE.
**Search keywords:** flow, flows, flow api, journey, customer journey, branching automation, workflow, automation builder, flow draft, draft, publish flow, activate flow, enable flow, trigger, exit, exit event, steps, nodes, graph, lifecycle, PROJECT_AUTOMATION_WRITE, PROJECT_AUTOMATION_READ, what can I do to a flow
**Related pages:** /developers/product-api/flows/templates, /developers/product-api/flows/drafts, /developers/product-api/analytics/flows, /platform/en/automations/flows
**Docs index (every page):** https://staging-instasent-docs-nextjs.oscar-284.workers.dev/llms.txt
**This zone's index:** https://staging-instasent-docs-nextjs.oscar-284.workers.dev/developers/product-api/llms-full.txt
**This page:** https://staging-instasent-docs-nextjs.oscar-284.workers.dev/developers/product-api/flows/overview/ (HTML) · https://staging-instasent-docs-nextjs.oscar-284.workers.dev/developers/product-api/flows/overview.md (Markdown)

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.

> **Note**: **Flows is in beta**, in the dashboard and in this API. The endpoints and fields on these pages are the ones to build on, but the section may still grow and change while the feature evolves. For how customers build and publish flows in the dashboard, see [Flows](/platform/en/automations/flows) in the Platform guides.

## Drafts only

> **Warning**: **The API writes drafts, a person publishes.** Nothing in this section publishes, enables, disables or archives a flow, runs a test, or makes a contact enter one. A flow created through the API sends nothing until someone publishes it in the dashboard.

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](/developers/product-api/flows/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](/developers/product-api/flows/drafts).
- **Write the graph.** The trigger and exits, the nodes you may place, and the delays. See [Triggers and exits](/developers/product-api/flows/triggers-and-exits), [Nodes](/developers/product-api/flows/nodes) and [Delays and waits](/developers/product-api/flows/delays).

## 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](/developers/product-api/analytics/flows#versions). | `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](/developers/product-api/authentication) and [Rate limits](/developers/product-api/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.

```mermaid
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](/developers/product-api/analytics/flows#versions). The customer-facing description of the builder is [Flows](/platform/en/automations/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:

- `template` — `string`
  The key of the template the flow was created from, or `null`. A template stays marked `used` in [the template list](/developers/product-api/flows/templates) while a flow created from it is not archived.
- `trigger` — `object`
  What the flow reacts to, taken from the live version or, when nothing is published, from the draft.
  
  - `triggerEvent` — `string`
    The event type that enrols a contact.
  - `triggerDatasource` — `string`
    The data source the trigger listens to. `null` means any source.
  - `exitEvents` — `string[]`
    The event types that take a contact out.
  - `exitDatasources` — `string[]`
    The data sources the exits listen to.
  - `from` — `string`
    `live` or `draft`: which version the trigger was read from.

> **Tip**: **List the flows before you create one.** Two flows on the same trigger event both enrol the same contact and message them twice. Checking `trigger.triggerEvent` across the existing flows is the cheapest way to avoid it. A disabled flow with a trigger may never have run: `from: "draft"` says nothing has been published.

## What's next

- [Templates](/developers/product-api/flows/templates) - Ready-made flows scored against the project's real events, in SMS or RCS, in the project's language.
- [Creating and editing drafts](/developers/product-api/flows/drafts) - Create, read, replace and validate a draft, and the errors each call returns.
- [Triggers and exits](/developers/product-api/flows/triggers-and-exits) - The trigger event and its source, who may enter, re-entry, exits and goals.
- [Nodes](/developers/product-api/flows/nodes) - How the graph chains, the nodes the API accepts, and how a send is written.
- [Delays and waits](/developers/product-api/flows/delays) - Fixed delays, window and smart delays configured by name, and waits for an event or a delivery.
- [Flow reports](/developers/product-api/analytics/flows) - Versions, and the time series that measures a published flow.

---

This is one page of the Instasent documentation. For the complete machine-readable index of every guide and API reference, fetch https://staging-instasent-docs-nextjs.oscar-284.workers.dev/llms.txt — start there for full context.