Flow definition schema

The complete shape of a flow: how routing works, every node type, every condition and every operator. Enough to author a valid flow without reading source.

The document

{
  "trigger": { "event": "signed_up", "match": null, "label": "optional card title" },
  "node_counter": 4,
  "nodes": [ ... ]
}

Over the API this is the definition field; in a manager repo it's the definition key of flows/<key>.json, alongside the flow's key, name, labels and run_policy. The same shape in all three places.

Order is the routing

Steps run in the order they appear. The first node in nodes is where a person starts. There is no entry, no next, and no pointers of any kind — a step knows what it does, not what follows it.

Branches are exactly two arms, each a plain array on the step

Nothing else nests. A gate that never expires carries no arms because nobody can ever reach a "gave up" path on it — it behaves exactly like a delay that happens to be watching for something. Spell that choice as an expires_after of "never": it means the same as omitting the field, but says the waiting is deliberate, so the validator doesn't flag it as a possible omission.

Arms fall through

When an arm runs out, the person carries on to the step after the branch — and that rule applies again to the branch itself, however deep it sits. So:

• An empty arm means "this side does nothing extra".
• Both sides meet again below the branch, unless one of them ends in an exit_flow.
• An exit_flow inside an arm is how you stop the run on that side for good.
• Running off the end of the top level completes the run.

This one rule replaces every merge pointer. There is no way to write "these two paths rejoin here" because fall-through already is that, and no way to write a loop at all.

Identity: the one thing you must not get wrong

{ "id": 7, "slug": "send-pitch", "name": "Send the pitch", "type": "send_email", "email_id": 42 }

The handle is {id}-{slug} — 7-send-pitch. The step ID, used in logs, traces and reports, is {flow_key}.{id}-{slug}. Renaming a step never moves anybody, which is what makes renaming safe to offer; changing or reusing an id does, silently.

node_counter records the last id ever handed out. It only ratchets up, and it is round-tripped rather than recomputed from the ids present — which is how a deleted step's id stays retired. On save Mimeo takes the highest of the counter you sent, the counter it has, and the highest id actually present, so a stale counter in a merged file can't drag it backwards.

Node types

Durations

{ "amount": 3, "unit": "days" }        // literal — minutes | hours | days | weeks
{ "setting": "quiet_buffer_days" }    // a named tunable, so the knob moves without a definition edit

Gates

{ "id": 7, "slug": "wait-for-pricing", "name": "Wait for a pricing visit", "type": "gate",
  "wait_for": { "event": { "name": "visited_pricing", "match": null, "occurrence": "next_occurrence" } },
  "expires_after": { "amount": 14, "unit": "days" },
  "met": [],
  "expired": [ { "id": 8, "slug": "quiet-exit", "name": "Done — went quiet", "type": "exit_flow" } ] }

wait_for takes exactly one of event or condition. An event's occurrence is next_occurrence (from now on) or any_past (it may already have happened).

expires_after is a duration, or the string "never" for a gate that should wait forever — the person then stays at the step until the wait is met, and the gate carries no arms. Omitting the field means the same thing, but draws a validator warning, since an omission can't be told from a forgotten field.

Where someone goes when a gate releases is read from the live definition, not from a snapshot taken when they parked — so editing the arms moves the people already waiting.

The trigger

"trigger": {
  "event": "signed_up",
  "match": { "all": [ { "detail": "plan", "op": "equals", "value": "trial" } ] }
}

Flows trigger on events only — there are no time-based triggers. match is optional and nests with all, any and not; leaves are { detail, op, value } against the event's own details.

Match operators: equals · contains · starts_with · ends_with · greater · less · blank · present — the same eight every field condition uses, so there is one operator vocabulary to learn. (Definitions written before the names were unified may carry exact, has_value or is_empty; they still read as equals, present and blank.)

Conditions

The same vocabulary powers if_else steps, gate conditions, guards and segments — learn it once.

Groups: all, any, not.

suppressed takes no fields. It is a question, not a setting: on its own it matches people who are suppressed — meaning Mimeo will never email them, because they unsubscribed, hard-bounced, or complained. To match everyone who is not, wrap it in not — { "type": "not", "condition": { "type": "suppressed" } }. Writing { "type": "suppressed", "value": false } does not do that; it means the opposite of what it looks like.

The trigger takes event, an optional match, an optional label, and ignore_historical. Any other key is refused on save, for the same reason a condition's unknown keys are: a setting nobody reads is a flow that behaves unlike the thing you wrote.

ignore_historical defaults to true when absent, so every flow written before historical events existed is protected without being touched. Set it to false only when a flow genuinely should react to backfilled history — it will then start on historical events and open its gates on them. See backfilling without sending mail.

subscribed_on uses the same three operators as everything else — less is before the date, greater is after it, and equals is on it. Both comparisons are strict, so someone whose date is exactly the value matches only equals. There is no before or after operator: they would be second names for operators that already have one, and a rule using them is refused on save. The interface shows them as "is before", "is after" and "is on" — that's a label, not a different vocabulary.

More generally, a condition only reads the fields listed above. A field that isn't in its row is rejected when you save — a rule that quietly ignored half of what you wrote would be worse than one that refuses to save. If a save fails with condition_keys_unknown, the error names the field and the ones that type does accept.

Field operators: equals · contains · starts_with · ends_with · greater · less · blank · present
Email address operators: equals · starts_with · ends_with · contains — the text operators only; ordering an address makes no sense, and every person has one, so the empty checks would be dead weight. The interface shows equals as "is exactly" — a label, not a different vocabulary.
Amount operators: greater · less · equals

Note which references are keys and which are numeric ids: flows, products and segments are referenced by key; emails and sequences by numeric id. GET /api/v1/emails and /sequences resolve those, and MCP's describe_schema returns all of it in one call — along with the custom fields, tags, event names and named durations this particular install actually has.

Validation

POST /api/v1/flows/:id/validate checks a definition without saving it. Errors block activation; warnings never do. Every issue carries a code, a path into the document (nodes[0].then[1].tag), the step's handle, and a message that says what the shape is rather than only that something is wrong.

Warnings worth knowing:

Errors cover the rest: unknown types, missing required fields, fields a condition doesn't read (condition_keys_unknown), duplicate ids, arms on a type that doesn't have them, references to emails, sequences, fields, tunables, flows, products or segments that don't exist, nesting deeper than ten, and steps that nothing can reach.

See also: Flows API · Event contract · Flows, for humans