Create an automation flow
Authorizations
A secret API key. Publishable keys cannot reach this API. A key may carry an expiry, and an expired key is refused exactly like an unknown one, with a 401 that names no reason; check the key's expires_at in the dashboard rather than inferring it from a response. When a merchant rolls a key's secret they choose a grace window of up to 3 days, and for its duration BOTH the new secret and the one it replaced authenticate, so an integration moves over on its own deploy schedule instead of at the instant the button is pressed. Move before the window closes: after it, the old secret is refused. Nothing else about this contract moves with a roll. The key keeps its id and its scopes, so the only thing an integration updates is the credential itself.
Headers
A unique key per logical write. Replaying a request with the same key returns the first response byte for byte instead of applying the write twice.
Body
A flow ALWAYS lands as a draft with no published graph, so this route can never mail anybody: publishing a version and taking it live are two further explicitly named calls. status and live_version_id are refused by name for that reason. THE STEP GRAPH IS NOT ON THIS BODY. It lives in an immutable version, so changing the program means POSTing to .../versions; this body carries only who enters the flow and under what policy.
What the merchant sees in their own dashboard. Unique per store, so a repeat is 409 name_taken rather than a second program nobody can tell apart from the first. At most 200 bytes.
What admits a contact. event enrolls whoever performs a named behaviour, segment_entry enrolls whoever joins a segment, and manual enrolls only who is explicitly pushed through .../enroll. It has no default and cannot be inferred.
event, segment_entry, manual REQUIRED when trigger_type is event. A trigger that does not carry the thing it triggers on could never fire, so it is 400 invalid_flow rather than a flow that silently enrolls nobody.
REQUIRED when trigger_type is segment_entry, for the same reason.
Whether someone who has been through this program may enter it again. An omitted key stores never, which is the conservative one: it is the difference between a welcome series and a loop that mails the same person every week.
never, after_exit, after_cooldown How long after_cooldown waits before a contact is eligible again. REQUIRED and non-zero when reenrollment is after_cooldown; meaningless on the other two.
Behavioural events that end a run early, so a contact who converts stops receiving the rest of the sequence. Empty means a run only ends by reaching an exit step.
Response
Created
