Creating and editing drafts

A flow's draft is the one version the API can write. You create it together with the flow, read it back to change it, replace it whole, and validate graphs against the same checks the dashboard applies when it saves. Publishing it stays with a person in the dashboard — see Flows.

Four endpoints, one shape: every draft travels as { "trigger": { ... } }, the graph nested inside the trigger. That shape is described node by node in Nodes, and the fastest way to get a correct one is a template payload.

Before you start

1. 1

   Get a Product API token with automation write access

   Creating, replacing and validating need PROJECT_AUTOMATION_WRITE; reading the draft needs PROJECT_AUTOMATION_READ. Scopes are chosen when the token is minted, under Project settings → API tokens — see Authentication.

2. 2

   Know your project UID

   Every call is scoped to one project, which owns the data sources, senders and segments the draft may reference.

3. 3

   Export credentials

   export INSTASENT_PROJECT="proj_xxx"
   export INSTASENT_TOKEN="eyJhbGciOi..."
   export BASE="https://api.instasent.com/v1/project/$INSTASENT_PROJECT"

Creating a flow

curl -X POST "$BASE/flow" \
  -H "Authorization: Bearer $INSTASENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d @flow.json

A successful call returns 201 Created:

{
  "entity": {
    "flowId": "66b1f2a4e5a6b7c8d9e0f1a2",
    "draftId": "66b1f2a4e5a6b7c8d9e0f1b7",
    "valid": false,
    "errors": [
      {
        "path": "graph",
        "message": "...",
        "parameters": { "errorsCount": 1, "uids": ["6f1c0a9e-..."] }
      }
    ],
    "warnings": [
      { "rule": "no-purchase-exit", "message": "..." }
    ]
  }
}

Reading the draft

The response is the same flowId, draftId, valid and errors, plus draft: the graph, with every node's uid kept so it can be edited and sent back whole. A flow with no draft answers 404.

A draft can change without you: a person may open the flow in the dashboard and save it, and every save produces a new draftId. Read before you replace.

Replacing the draft

There is no partial edit. Every save — yours or a person's in the dashboard — replaces the whole draft and creates a new draft version with its own id. The request carries the graph and the id of the draft you started from:

If the flow's current draft is not the one you name, nothing is saved and the call answers 409 Conflict: someone saved in between, and overwriting their change silently would lose it. Read the draft again, reapply your change on top of it, and send it with the new draftId.

flowchart TD
    A[GET /flow/id/draft] --> B[Edit the graph, keep the uids]
    B --> C[PUT /flow/id/draft with expectedDraftId]
    C -->|200| D[Saved: keep the new draftId]
    C -->|409| A
    class D success

Keep the uid of every node you read. A node that keeps its uid keeps its identity across saves; omit it only on nodes you add.

A successful replace returns 200 OK with flowId, the new draftId, valid and errors. Like creation, an invalid draft is saved. Editing the draft never changes what is live: the published version keeps running until a person publishes again.

Two things refuse a replace besides a stale draft: an archived flow, whose draft can no longer change (400), and a second save of the same flow within a couple of seconds of the previous one (429, retry after a moment).

Validating without saving

Send { "draft": { ... } } and get back valid, errors and warnings, from the same checks a save runs. Nothing is stored, so it is the way to iterate on a graph before replacing a draft with it. The flow in the path must exist: create the flow first, then validate the changes you plan to make to it.

{
  "entity": {
    "valid": true,
    "errors": [],
    "warnings": [
      { "rule": "send-right-after-trigger", "message": "..." }
    ]
  }
}

Validation errors

Validation covers the graph's structure, each node's required settings, and limits on the flow as a whole. Each entry carries path, message and parameters. Base your handling on path and parameters: message is written for the dashboard and can still contain {{placeholders}} that parameters fills in.

• Problems with the graph as a whole come as entries with path: "graph": a node reachable from more than one place, more than 50 nodes, waits on the longest path adding up to more than 180 days, or nodes that reference a sender or data source from outside this project (their uids are in parameters).
• Problems inside nodes come as a single path: "graph" entry whose parameters carry errorsCount and the uids of the nodes in error. The API does not return the reason per node; the dashboard editor shows it on each node. Keeping the uid of the nodes you read is what lets you tell which ones failed; a node you add gets its uid when the draft is saved, so read the draft back to map it.

The node problems you will meet most:

• A send with no sender, or no text. The most common, and the one every template payload has until you set its senders.
• A branch with the wrong paths: a missing path, a default path with a condition, the wrong number of fixed outcomes. See Nodes.
• A value out of range: a delay shorter or longer than its node allows. See Delays and waits.

Advice

warnings flags a graph that validates but probably does not do what its author wants. It never blocks a save and is never stored; it rides the creation response and the validate response, not a replace.

Read every entry: each one describes a journey that will misbehave in front of contacts once it is published.

Limits

The first limit exists so an automated caller cannot fill a project with drafts in a loop; it is checked before any other work, and only on creation. A flow counts towards it until it is published, and stops counting once a person publishes or deletes it.

Errors

The two 409s are told apart by their body. The draft limit is the only one with a machine-readable code at the top level:

{
  "code": "flow-draft-limit-reached",
  "message": "This project already has 50 flows that were never published, the most allowed. Publish or delete one before creating another; retrying will fail the same way.",
  "limit": 50,
  "count": 50
}

Retrying it changes nothing until a flow is published or deleted in the dashboard, so report it rather than looping. The stale-draft 409 carries only a message; its remedy is always to read the draft again.

A 422 looks like the other field errors of the Product API:

{
  "errors": {
    "fields": {
      "draft": ["A value in the draft has the wrong shape: ..."]
    }
  }
}

The most common cause is an RCS message written as a bare string: an RCS text is { "text": { "text": "..." } }. Everything else — 401, 5xx — behaves as described in Errors.

What's next