> For the complete documentation index, see [llms.txt](https://developers.gleantap.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.gleantap.com/api-reference-v3/flows.md).

# Flows

Multi-step automations. Contacts are enrolled based on segment membership (or manually via `POST /flows/{id}/enroll`) and move through the flow's steps. Use `GET /flows/schema` to see the supported node types and their settings.

## List flows.

> Paginated list. Common filters: \`?filter\[status]=active\`, \`?filter\[name]=welcome\` (case-insensitive prefix). \`?fields=name,status\` keeps only those top-level fields (plus \`id\`, \`object\`). Flows in a list never include \`nodes\`. Rate limit bucket: \`read\`.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Flows","description":"Multi-step automations. Enrollment is driven by segment membership. 7 node types are supported by the engine — see the Flow Engine companion doc for the full model, including the versioning and in-flight-edit caveats."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["flows:read"]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"},"OAuth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE. Use for third-party apps acting on behalf of a Gleantap user.\nAuthorization Code + PKCE is the only supported grant for interactive flows; refresh_token grant is supported and rotates on every use.\n","flows":{"authorizationCode":{"authorizationUrl":"https://api.gleantap.com/v3/oauth/authorize","tokenUrl":"https://api.gleantap.com/v3/oauth/token","refreshUrl":"https://api.gleantap.com/v3/oauth/token","scopes":{"contacts:read":"Read contact records.","contacts:write":"Create, update, delete contacts (soft delete).","contacts:delete_hard":"Hard-delete contacts (irreversible).","events:read":"Read event records.","events:write":"Record events.","segments:read":"Read segments and preview membership.","segments:write":"Create, update, delete segments.","templates:read":"Read message templates.","templates:write":"Create, update, delete templates.","campaigns:read":"Read campaigns and analytics.","campaigns:write":"Create, schedule, cancel campaigns.","flows:read":"Read flow definitions and analytics.","flows:write":"Create, edit, publish flows.","flows:publish":"Publish/unpublish flows (separately scoped for governance).","messaging:send":"Send transactional messages (SMS, email, voice).","conversations:read":"Read conversations and messages.","conversations:write":"Send messages, close/reopen conversations.","webhooks:manage":"Create, update, delete webhook endpoints.","forms:manage":"Create, update, delete, publish, duplicate forms; list submissions and rotate the submission_token.","campaigns:manage":"Create, schedule, cancel, duplicate campaigns; read recipients and analytics. (Supersedes the earlier `campaigns:read` + `campaigns:write` split; the split scopes still work.)","admin:impersonate:read":"Gleantap staff only — read any customer account named via `Gleantap-Account`. Not available through dynamic client registration.","admin:impersonate:write":"Gleantap staff only — required for any state-changing method while impersonating. Not available through dynamic client registration."}}}}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"WorkroomQuery":{"name":"workroom","in":"query","required":false,"description":"Same semantics as the `Gleantap-Workroom` header, including that a write should never be sent without a workroom the user actually chose, and that an omitted workroom scopes a read to the account default rather than spanning the account. Prefer this on GETs so proxies and caches can key on it. Accepts name, prefixed ID, raw hex, or `all`.\n","schema":{"type":"string"}},"LimitParam":{"name":"limit","in":"query","required":false,"description":"Page size. Default 25, max 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},"CursorParam":{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from a prior response's `next_cursor`, to fetch the NEXT page (alias - `after`). On listContacts and listSegmentContacts, use `before` with a `prev_cursor` to page backward; other list endpoints are forward-only.","schema":{"type":"string"}},"SortParam":{"name":"sort","in":"query","required":false,"description":"Comma-separated list of fields to sort by. Leading `-` reverses. Default `-created_at`. Sortable fields vary per resource; unsortable fields return 400 `invalid_sort_field`.\n","schema":{"type":"string"}},"FieldsParam":{"name":"fields","in":"query","required":false,"description":"Sparse fieldset — comma-separated list of fields to include in the response. Reduces payload size on high-volume reads. Nested field access is not supported; request the parent object.\n","schema":{"type":"string"}}},"schemas":{"ListEnvelope":{"type":"object","required":["object","data","has_more","next_cursor","prev_cursor"],"properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"type":"object"},"description":"The page of results. Item type varies per endpoint — see the specific response schema."},"has_more":{"type":"boolean","description":"True if additional records exist beyond this page."},"next_cursor":{"type":"string","nullable":true,"description":"Opaque cursor for the next page. Null on the last page."},"prev_cursor":{"type":"string","nullable":true,"description":"Cursor for the previous page. Supported on `listContacts` and `listSegmentContacts`: pass it back as `?before=...` to page backward; `null` on the first page. On every other list endpoint paging is forward-only and this is always `null`."}}},"Flow":{"type":"object","required":["id","object","name","status","entry","nodes","created_at","updated_at"],"properties":{"id":{"$ref":"#/components/schemas/FlowId"},"object":{"type":"string","const":"flow"},"name":{"type":"string","maxLength":200},"description":{"type":"string","nullable":true,"maxLength":2000},"status":{"$ref":"#/components/schemas/FlowStatus"},"workroom_id":{"$ref":"#/components/schemas/WorkroomId","nullable":true,"description":"The workroom this flow lives in. Its `entry.segment_ids` must all belong to the same workroom."},"entry":{"$ref":"#/components/schemas/FlowEntry"},"nodes":{"type":"array","items":{"$ref":"#/components/schemas/FlowNode"}},"stats":{"$ref":"#/components/schemas/FlowStats"},"conversion_config":{"type":"object","nullable":true,"description":"Optional conversion goal(s) tracked per contact per run.","properties":{"conversion_ids":{"type":"array","items":{"type":"string"}},"attribution_window_days":{"type":"integer","minimum":1,"nullable":true}}},"timezone":{"$ref":"#/components/schemas/Timezone","nullable":true,"description":"Timezone used to interpret `delay` node \"Specific Date & Time\" values. Defaults to the account timezone."},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"published_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"archived_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"created_by_user_id":{"$ref":"#/components/schemas/UserId","nullable":true},"metadata":{"$ref":"#/components/schemas/Metadata"}}},"FlowId":{"type":"string","pattern":"^flw_[0-9A-HJKMNP-TV-Z]{26}$"},"FlowStatus":{"type":"string","enum":["draft","active","inactive","paused","completed","archived"],"description":"`draft` — never published. `active` — published and enrolling. `inactive` — unpublished; in-flight runs continue but no new entries. `paused` — enrollment and step execution both halted; can be resumed. `completed` — `end_date_time` passed. `archived` — soft-deleted.\n"},"WorkroomId":{"type":"string","pattern":"^wrm_[0-9a-f]{24}$"},"FlowEntry":{"type":"object","description":"Flow enrollment configuration. Enrollment is driven by segment membership — contacts entering `segment_ids` are enrolled on the next cron pass. Rich trigger vocab (`event`, `form_submission`, `appointment_booked`, etc.) is not first-class in the engine; model those via a segment that captures the trigger criteria.\n\n**Set a trigger.** Publishing requires `segment_ids`. A flow without them is created with a `no_entry_trigger` warning and publishing is refused with `no_entry_segment`: the send worker enrolls every contact in the entry segment, so a flow with none would enroll the whole workroom. `segment_criteria` and `manual_only` are not read by the worker; save criteria as a segment and use its id.\n\n**Workroom matching.** A flow lives in exactly one workroom and can only be triggered by segments from that same workroom. Compare `Segment.workroom_id` with `Flow.workroom_id`. On create you don't need to pass `workroom`: the flow is placed in the workroom that owns `segment_ids`. Segments spanning two workrooms are rejected — build one flow per workroom. On PATCH the workroom is already fixed, so a sibling-workroom segment is rejected with `422 invalid_segment_ids`.\n","properties":{"segment_ids":{"type":"array","items":{"$ref":"#/components/schemas/SegmentId"},"description":"Contacts entering ANY of these segments enter the flow. Must all belong to one workroom."},"segments":{"type":"array","items":{"$ref":"#/components/schemas/Segment"},"description":"Inlined Segment objects when `?expand=entry.segments` is requested."},"unenroll_segment_ids":{"type":"array","items":{"$ref":"#/components/schemas/SegmentId"},"description":"Contacts entering ANY of these segments are unenrolled from in-flight runs. Must belong to the flow's workroom."},"unenroll_segments":{"type":"array","items":{"$ref":"#/components/schemas/Segment"},"description":"Inlined unenroll Segment objects when `?expand=entry.segments` is requested."},"manual_only":{"type":"boolean","default":false,"description":"Marks a flow meant for `POST /v3/flows/{id}/enroll`. It does not remove the need for `segment_ids` to publish: the send worker enrolls the entry segment regardless, so use a segment that matches nobody until you enroll contacts."},"reenroll":{"type":"boolean","default":false,"description":"Allow contacts who completed the flow to enter again. Stored as the dashboard's `reenroll_status`, which is the only field the flow worker reads. The worker re-enrolls a contact who still matches the entry segment once their finished run started before today (account timezone); the old run moves to history and the new run has `reenroll: true`. Manual enroll (`POST /enroll`) follows the same rule.\n\nReads report what the worker will do: flows saved by older API versions with only `reenroll` set read `false` until re-saved.\n"},"reentry_cooldown_days":{"type":"integer","nullable":true,"deprecated":true,"description":"Not supported, and ignored. The flow worker has no re-entry cooldown. Sending a value returns a `reentry_cooldown_days_unsupported` warning and nothing is stored. To space re-entries, build the gap into the entry segment."},"end_date_time":{"$ref":"#/components/schemas/Timestamp","nullable":true,"description":"Flow auto-completes past this time. New enrollments halted; in-flight runs continue."},"segment_criteria":{"$ref":"#/components/schemas/SegmentQuery","nullable":true,"description":"Stored and echoed back only. The enrollment worker never reads it: who enters is decided by `segment_ids` alone, and it does not narrow them. To enroll on criteria, save them as a segment (`POST /v3/segments`) and put its id in `segment_ids`."}}},"SegmentId":{"type":"string","pattern":"^seg_[0-9A-HJKMNP-TV-Z]{26}$"},"Segment":{"type":"object","description":"A named collection of contacts. Either static (hand-managed list) or dynamic (query-defined). Discriminated by the `type` field, which is immutable after creation.\n","required":["id","object","type","name","size","created_at","updated_at"],"properties":{"id":{"$ref":"#/components/schemas/SegmentId"},"object":{"type":"string","const":"segment"},"workroom_id":{"$ref":"#/components/schemas/WorkroomId","nullable":true,"description":"The workroom that owns this segment. A flow can only be triggered by segments in its own workroom — compare against `Flow.workroom_id`."},"type":{"$ref":"#/components/schemas/SegmentType"},"name":{"type":"string","maxLength":200},"description":{"type":"string","nullable":true,"maxLength":2000},"query":{"$ref":"#/components/schemas/SegmentQuery","nullable":true,"description":"The segment's criteria. **Present on BOTH static and dynamic segments** — a \"static\" segment only means the engine doesn't auto-refresh membership; the criteria that defined the initial membership list is still stored and returned. When diagnosing \"why did this contact match this segment?\", read `query.segment_users` (+ `with_or_segment_users` and `exclude_segment_users`). May be `null` only on segments imported without criteria or created empty.\n"},"size":{"type":"integer","minimum":0,"description":"Current member count. Eventually consistent — up to minutes of lag on dynamic segments."},"email_count":{"type":"integer","minimum":0,"description":"Members with a non-empty, non-invalid email."},"phone_count":{"type":"integer","minimum":0,"description":"Members with a non-empty, non-invalid phone."},"last_evaluated_at":{"$ref":"#/components/schemas/Timestamp","nullable":true,"description":"When this dynamic segment was last recomputed. Null on static."},"folder_id":{"$ref":"#/components/schemas/SegmentFolderId","nullable":true,"description":"The segment folder this segment currently belongs to, or `null` if unfoldered."},"segment_summary":{"type":"string","nullable":true,"description":"AI-generated narrative summary of the segment's criteria. Populated on demand via `POST /v3/segments/{id}/summary`."},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"metadata":{"$ref":"#/components/schemas/Metadata"}}},"SegmentType":{"type":"string","enum":["static","dynamic"],"description":"`static` — hand-managed member list. Contacts are added/removed explicitly.\n`dynamic` — query-defined membership. Auto-evaluated; membership changes as contact data changes.\nImmutable after creation.\n"},"SegmentQuery":{"type":"object","description":"The segment criteria. **Present on BOTH `static` and `dynamic` segments** — \"static\" only means the engine doesn't auto-refresh membership; the criteria that defined the segment is still on the doc, and diagnostic tools (like \"why did this contact match this segment?\") MUST read it here.\n\nFull match logic:\n\n  (all `segment_users` ANDed together)\n  OR (all conditions in `with_or_segment_users[0]` ANDed)\n  OR (all conditions in `with_or_segment_users[1]` ANDed)\n  OR ...\n  MINUS contacts removed by `exclude_segment_users` (all ANDed) — self-match or shared-copy match per the account setting below\n\nHow `exclude_segment_users` matches depends on the account's `shared_contact_status` (surfaced as `shared_contacts_enabled` on `GET /segments/schema`). When shared contacts are ENABLED it is the dashboard's \"exclude shared contacts\" rule: a contact is removed when one of its linked copies in another workroom (`shared_contacts[]`) matches these conditions, NOT when the contact itself matches. When shared contacts are OFF it is a plain self-subtraction: the contact is removed when its OWN fields match. The exclusion can be any condition (attribute match, event done, tag, form filled — just the positive form of what to exclude). Either way the segment must keep at least one primary condition in `segment_users`; an exclude-only (or `with_or`-only) query is rejected. To exclude by a contact's own attributes regardless of the account setting, you can also use a negative condition in `segment_users` (e.g. `Is Not One Of`, `Has not Filled a Form`, `Does Not Contain`).\n\nConditions are stored in the exact tokens the dashboard's segment engine evaluates: friendly category names are rewritten on write (`Custom`/`attributes` → `Attributes`, `email_engagement` → `EmailCampaigns`, `salesattributes` → `sales`, …), and an absolute-date `<`/`>` on a Date field is stored as `Before`/`After` with an `MM-DD-YYYY` value. A retrieved segment therefore shows the stored (engine) form.\n\nThere is no additional `all/any/none` grouping. Express further OR via multi-value operators (`Is One Of`, `Segments` with an array).\n","properties":{"segment_users":{"type":"array","items":{"$ref":"#/components/schemas/SegmentCondition"},"description":"Base inclusion conditions. All ANDed. A contact must satisfy every one to be included via this group."},"with_or_segment_users":{"type":"array","description":"Alternate inclusion groups. Each inner array is a set of conditions that are ANDed together; the outer array is OR-joined with `segment_users` and each other inner array. Use this to build \"criteria A OR criteria B\" queries without touching the top-level `segment_users`.\n","items":{"type":"array","items":{"$ref":"#/components/schemas/SegmentCondition"}}},"exclude_segment_users":{"type":"array","items":{"$ref":"#/components/schemas/SegmentCondition"},"description":"Exclusion conditions, ANDed. How they match depends on the account's `shared_contact_status` — shared-copy match when shared contacts are ON (a contact is removed when a linked copy in another workroom, `shared_contacts[]`, matches all of them), self-match when OFF (removed when the contact's own fields match all of them). Same condition shape as `segment_users`. Cannot stand alone — `segment_users` must be non-empty. See the match logic above."}}},"SegmentCondition":{"type":"object","description":"A single condition in a dynamic segment query. Shape and operator vocabulary are documented in the Segment Query DSL companion doc — the query language supports 28 segment types (Attributes, Tags, Event Trigger, External Events, Segments, SalesAttributes, Forms, Flows, Optin, and more) and 60+ operators. This schema is intentionally loose to accommodate that surface; the server validates the concrete shape.\n","required":["segment","operator"],"additionalProperties":true,"properties":{"segment":{"type":"string","description":"Segment-type discriminator. Full inventory in the DSL doc. Common values include `Attributes`, `Tags`, `Country`, `City`, `Event Trigger`, `External Events`, `Segments`, `SalesAttributes`, `Forms`, `Flows`, `SMS Optin`, `SMS Opted Out`, `Email Topics`, `Add Date`, `Last Access`.\n"},"data":{"type":"string","description":"Field or attribute within the segment type. E.g., `first_name`, `city`, `sales.pipeline.stage`.","nullable":true},"event":{"type":"string","description":"Event name — used only when `segment` is `Event Trigger`.","nullable":true},"operator":{"type":"string","description":"Operator vocabulary. Full list in the DSL doc. Common: `=`, `!=`, `<`, `>` (numeric — on a Date field they are stored as `Before`/`After`), `Contains`, `Does Not Contain`, `Is One Of`, `Is Not One Of`, `Is Empty`, `Is Not Empty`, `Exists`, `Does Not Exist`, `Is True`, `Is False`, `InLast`, `OverDays`, `InNext`, `Before`, `After`, `IsToday`, `DayInNext`, `DayInMonth`, `Is In Segment`, `Is Not In Segment`, `Has Filled a Form`. For recurring day-of-year fields (`data_type: Day`, e.g. Birthday) use the `DayInNext`/`DayInNextXY`/`DayInMonth` family — not the absolute-date `InNext`/`=` — so \"birthday in the next N days\" recurs every year (see `describeSegmentSchema`).\n\n`Exists`/`Does Not Exist` vs `Is Not Empty`/`Is Empty`: both check for a populated value and are usually close in practice, but `Exists` is what the dashboard UI itself uses when a user says a field \"exists\" - prefer `Exists`/`Does Not Exist` for that phrasing, especially inside `with_or_segment_users`, to match what the UI would produce for the same request.\n"},"value":{"type":["string","number","boolean","array","null"],"description":"The operand. Which type applies depends on the operator: a scalar for `=` and `Contains`, an array (or comma-separated string) for `Is One Of`, a number for count comparisons, and omitted entirely for `Exists` / `Is Empty`.\n"},"value2":{"type":["string","number","null"],"description":"Secondary operand for two-parameter conditions (currently `External Events` count comparison and `SalesAttributes` pipeline-stage filter)."},"operator2":{"type":"string","description":"Secondary operator for two-parameter conditions.","nullable":true},"value2_id":{"type":"array","items":{"type":"string"},"nullable":true,"description":"Object-ID list for stage-title disambiguation on `SalesAttributes`."},"data_type":{"type":"string","enum":["String","Numeric","Date","List"],"nullable":true,"description":"Optional hint for the engine's disambiguation logic."},"dataAlias":{"type":"string","nullable":true,"description":"Human-readable alias shown in the UI. Not evaluated."}}},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"SegmentFolderId":{"type":"string","pattern":"^sfd_[0-9a-fA-F]{24}$","description":"Segment folder ID."},"Metadata":{"type":"object","description":"Free-form key/value pairs the caller stores on the resource. Not evaluated by Gleantap.\nUse for opaque identifiers, integration state, or notes you need to survive round-trips.\n","additionalProperties":true},"FlowNode":{"type":"object","required":["id","type"],"description":"A node in a flow's DAG. Polymorphic on `type` — only the fields relevant to that type should be set (unused fields ignored). See per-type notes below.\n\n**Parent/child edges:** each node has `parent_id` pointing at another node's `id`. Root nodes have `parent_id: null` and `parent_branch: \"root\"`. For `condition` nodes with `action_type: \"yes_no\"`, children set `parent_branch: \"yes\"` or `\"no\"`. For `multi_choice` conditions, children set `parent_branch: \"<matched value>\"` (slugified — spaces → underscores, lowercased). For `wait_till_true` conditions, there is no branching at all — the node re-evaluates itself until its predicate matches (see `FlowConditionMode`), and its child (if any) hangs off the ordinary linear `parent_branch: \"next\"` edge, the same as a non-condition node.\n\n**Client-supplied `id`:** you supply a string identifier per node (unique within the flow). The server uses it to resolve `parent_id` references. IDs need not survive updates — the server maps them to internal IDs at save time.\n","properties":{"id":{"type":"string","maxLength":100,"pattern":"^[a-zA-Z0-9_-]+$","description":"Client-supplied identifier, unique within this flow."},"type":{"$ref":"#/components/schemas/FlowNodeType"},"parent_id":{"type":"string","nullable":true,"description":"The `id` of this node's parent. Null for root nodes."},"parent_branch":{"type":"string","default":"root","description":"Which branch of the parent this node hangs off. `root` for the flow's entry node, `next` for a linear step, `yes`/`no` for a yes_no condition child, the slugified condition `value` for a multi_choice child, or `converge` to rejoin branches after a condition node.\n"},"action_name":{"type":"string","maxLength":200,"description":"Label shown in the UI. Optional; defaults per node type."},"campaign_id":{"$ref":"#/components/schemas/CampaignId","nullable":true,"description":"Optional. If provided, the server upgrades that existing campaign into a \"shadow\" dedicated to this flow node (adds `isAutomationCampaign=true` + `automation_id` + `automation_details_id`). The campaign is no longer a standalone after this — do not share campaign_ids across flows or reuse for one-off sends.\n"},"template_id":{"$ref":"#/components/schemas/TemplateId","nullable":true,"description":"Optional. Seeds the shadow campaign's content from a library template. For `email_campaign` the template's rendered HTML, its editor design JSON and its thumbnail are all copied onto the node, which is what makes the dashboard open it as an **HTML email** (the \"HTML Email\" toggle) rather than a plain-text one — a node given only inline `message_body` is plain text by design. An explicit `message_body` on the same node overrides the template's HTML body; `subject` is never taken from the template. Render happens at send time — merge tags interpolate per-recipient using the flow's audience data.\n"},"subject":{"type":"string","nullable":true,"description":"For `email_campaign` nodes. Email subject line. Supports merge tags (`{first_name}`, `{data.company}`). REQUIRED unless `template_id` or `campaign_id` provided.\n"},"message_body":{"type":"string","nullable":true,"description":"For both `email_campaign` (HTML body) and `sms_campaign` (plain-text body). Supports merge tags. REQUIRED unless `template_id` or `campaign_id` provided.\n`sms_campaign`: At most 10 SMS segments: 1530 plain (GSM-7) characters, or 670 if the text contains emoji or any other non-GSM character (once split, each segment holds 153 GSM / 67 unicode characters; emoji count as 2). Merge tags count as written, not expanded. A longer body (inline or from `template_id`) is rejected with 422 `validation_failed`.\n"},"preheader_text":{"type":"string","nullable":true,"description":"For `email_campaign`. Preheader shown in inbox previews after subject."},"from_name":{"type":"string","nullable":true,"description":"For `email_campaign`. Sender display name. Inherits app default when omitted."},"from_email":{"type":"string","format":"email","nullable":true,"description":"For `email_campaign`. Sender address. Inherits app default when omitted."},"from_number":{"type":"string","nullable":true,"description":"For `sms_campaign`. E.164 sender phone. Inherits app default when omitted."},"schedule":{"type":"string","enum":["Relative","Specific Date & Time"],"nullable":true,"description":"For `delay` nodes."},"delayTimeHour":{"type":"integer","nullable":true,"description":"For `delay` with `schedule: \"Relative\"`. Amount of `delayTimetype`."},"delayTimetype":{"type":"string","enum":["minutes","hours","days","weeks","months"],"nullable":true,"description":"For `delay` with `schedule: \"Relative\"`."},"selected_date":{"type":"string","format":"date","nullable":true,"description":"For `delay` with `schedule: \"Specific Date & Time\"`."},"selected_time":{"type":"string","nullable":true,"description":"For `delay` with `schedule: \"Specific Date & Time\"`. `HH:mm:ss` in the flow's timezone."},"action_type":{"$ref":"#/components/schemas/FlowConditionMode","nullable":true,"description":"For `condition` nodes."},"segment_users":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/SegmentCondition"},"description":"For `condition` with `action_type: \"yes_no\"` or `\"wait_till_true\"`. Segment DSL predicates — materialized into a hidden shadow segment for either mode (see `FlowConditionMode`) so the live cron can evaluate it.\n\n**Before constructing this**: call `describeSegmentSchema` (or `GET /v3/segments/schema`) to see available categories and copy each attribute's `condition_template` (segment/data/dataAlias/data_type) verbatim, using an `operator` from that field's `operators[]` — the same rule `createSegment`'s conditions follow. Don't guess a field key or reach for a human phrase like \"Before\" from general knowledge; the schema call is what tells you the exact tokens the engine expects.\n"},"with_or_segment_users":{"type":"array","nullable":true,"description":"For `condition` with `action_type: \"yes_no\"` or `\"wait_till_true\"` only — same OR-logic semantics as Segments' `query.with_or_segment_users`: each inner array is ANDed, and the outer array is OR-joined with `segment_users` and every other group. Materialized into the same hidden shadow segment as `segment_users` (confirmed live: `attach_condition_segment()` writes both fields identically onto the shadow segment doc, and the engine reads it from there). For `multi_choice`, use `with_or_segment_users` on the individual `FlowMultiCondition` branch instead — this top-level field is ignored for that mode.\n\nEchoed back on create/retrieve just like `segment_users` (it is persisted on the condition node itself in addition to the shadow segment), so a round-trip reflects exactly what you sent.\n","items":{"type":"array","items":{"$ref":"#/components/schemas/SegmentCondition"}}},"multi_conditions":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/FlowMultiCondition"},"description":"For `condition` with `action_type: \"multi_choice\"`."},"salesautomation_id":{"type":"string","nullable":true,"pattern":"^saut_[0-9A-HJKMNP-TV-Z]{26}$","description":"For `sales_automation` nodes. References a CRM automation created via `POST /v3/pipelines/{pipeline_id}/automations`."},"sales_automation":{"type":"object","nullable":true,"description":"For `sales_automation` nodes, instead of `salesautomation_id`: an inline CRM rule. v3 creates the rule and binds it to this node. Send `action` for one action or `actions` for several (run in order). Do not send a `trigger`; the flow decides when it runs.","properties":{"action":{"$ref":"#/components/schemas/SalesAutomationAction"},"actions":{"type":"array","items":{"$ref":"#/components/schemas/SalesAutomationAction"}}}},"webhook_url":{"type":"string","format":"uri","nullable":true,"description":"REQUIRED on `webhook` nodes — creating one without it returns 422. A webhook with no destination can never fire, and the dashboard refuses to save one for the same reason. Must be `https://` unless the account has `allow_http_webhooks: true`.\n\nGet the URL from the user. There is no sensible default and no way to infer it.\n"},"webhook_method":{"type":"string","enum":["GET","POST"],"default":"GET","description":"The flow worker only sends GET or POST; any other value is a 422 (it would silently go out as GET).","nullable":true},"webhook_payload_type":{"type":"string","enum":["json","form"],"default":"json","nullable":true},"webhook_fields":{"type":"array","nullable":true,"description":"REQUIRED on `webhook` nodes: at least one `{key, value}` pair with a non-empty `key` and `value` (`\"0\"` counts as empty). The flow worker builds the request only from such pairs and sends NOTHING when there are none — for GET (query string) as well as POST — so a node without one is a 422. Every entry must be an object with string `key` and `value`. `key` may use dot notation for nesting. Ask the user what the receiving system expects.\n","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string","description":"Supports `{placeholder}` interpolation from contact fields (e.g., `{first_name}`, `{email}`, `{data.custom_field}`)."}}}},"webhook_header_fields":{"type":"array","nullable":true,"description":"Optional request headers. Each entry needs a non-empty `key` and `value` (422 otherwise — the worker would drop it).","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}}}},"mariana_action":{"type":"object","nullable":true,"description":"Required for `mariana_action` nodes. Gives the enrolled contact something in the workroom's Mariana Tek studio. The contact is found by their Mariana id or exact email; with `if_not_found: create` a Mariana account is created from their email and name and Mariana emails them a set-password link. Each enrollment gives at most once. Amount and credit caps are the workroom's limits (default 100 and 20); values over them, or a malformed config, are rejected 422 so a saved node always runs.\n","required":["type"],"properties":{"type":{"type":"string","enum":["pack","class_credits","account_credit"]},"package_id":{"type":"string","description":"Mariana pack (package) id. `pack`: gives that pack's class credits with the pack's own expiry."},"package_name":{"type":"string","description":"Display name for the pack."},"credit_id":{"type":"string","description":"`class_credits`: Mariana credit type id."},"credit_name":{"type":"string"},"quantity":{"type":"integer","minimum":1,"description":"`class_credits`: number of credits (at most the workroom limit, default 20)."},"expiry_days":{"type":"string","description":"`class_credits`: whole days until the credits expire; empty for no expiry."},"amount":{"type":"number","description":"`account_credit`: amount to add, up to 2 decimals and the workroom limit (default 100)."},"currency":{"type":"string","description":"`account_credit`: 3-letter code, default USD."},"note":{"type":"string","maxLength":60,"description":"Shown on the credit in Mariana."},"if_not_found":{"type":"string","enum":["create","skip"],"default":"create"},"recipient":{"type":"string","enum":["contact","referrer"],"default":"contact","description":"`referrer` gives to the member who referred the contact (their `referred_by_id` in the same workroom, set by the referral intake) instead of the contact, once per enrollment. Use it in a referred friend's flow to reward the member."}}}}},"FlowNodeType":{"type":"string","enum":["email_campaign","sms_campaign","delay","condition","sales_automation","webhook","mariana_action"],"description":"The 7 node types the engine actually supports (`mariana_action` gives the contact a pack, class credits or account credit in the workroom's Mariana Tek studio). Richer vocab from the main spec (`send_message`, `tag`, `add_to_segment`, `update_contact`, `create_task`, `create_opportunity`, `wait_for_event`, `split`, `end`) is NOT implemented — express those via `sales_automation` (pointing at a CRM sub-automation) or return 501 `node_type_not_supported`. See Flow Engine companion doc §10.\n"},"CampaignId":{"type":"string","pattern":"^cam_[0-9a-f]{24}$"},"TemplateId":{"type":"string","pattern":"^tpl_[0-9a-f]{24}$"},"FlowConditionMode":{"type":"string","enum":["yes_no","multi_choice","wait_till_true"],"description":"`yes_no` — evaluates the `segment_users` predicate once, immediately, and branches: children set `parent_branch: \"yes\"` or `\"no\"` (see FlowNode's parent/child edges note). `multi_choice` — evaluates `multi_conditions` in order; the first match's slugified `value` becomes the child branch. `wait_till_true` — does NOT branch. It re-evaluates the SAME predicate, on the SAME node, on the engine's existing cron cadence, until it matches; only then does execution advance (linearly, via the ordinary `next` edge — there is no \"no\" child to fall through to). Confirmed against the dashboard/flow engine (`Cron.php`'s condition handling): while unmatched, the node is flagged `condition_repeat: true` and re-checked on the next cron pass rather than branching, and — unlike a `yes_no` match — a `wait_till_true` match never writes `operation_parent_type`/`operation_parent_id` on its action-story entry, confirming it has no yes/no children of its own.\n\n**Materialization (fixed — previously a known gap):** both `yes_no` and `wait_till_true` are evaluated by the engine against a legacy `yes_condition` field, which this API materializes from `segment_users` into a hidden shadow segment at creation time. `wait_till_true` is now included in that materialization the same way `yes_no` already was — a `wait_till_true` node created via this API is fully wired for the live cron to evaluate, not merely accepted and stored. Archiving a flow deletes these shadow segments (the node keeps `segment_users`, so duplicating the flow rebuilds them).\n"},"FlowMultiCondition":{"type":"object","required":["value"],"description":"One branch of a `multi_choice` condition. The engine evaluates each in order; the first `segment_users` match wins. Up to 6 regular branches plus one optional catch-all.\n\n**Storage.** Regular branches are stored as `Condition A`..`Condition F` in the order given, with your label kept as `name_alias` (what the dashboard shows). Children may reference a branch by your label, by `Condition A`, or by `condition_a`.\n\n**Catch-all.** Mark a branch with `is_other: true` (or `value: \"Other\"` / `\"Condition Other\"`). It is stored exactly as the dashboard stores it — `{value: \"Condition Other\", segment_users: [{segment: \"other\"}]}` — always last, and it matches every contact no earlier branch matched; any `segment_users` you give it are ignored (warning `other_branch_conditions_ignored`). Children reference it as `Other` / `condition_other`. Without a catch-all, a contact who matches no branch does not advance. More than 6 regular branches, or two catch-alls, is a 422. Reads echo `is_other: true` on the catch-all.\n","properties":{"value":{"type":"string","description":"Human-readable branch name (stored as `name_alias`; `value` becomes `Condition A`..`F`). `Other` / `Condition Other` marks the catch-all."},"is_other":{"type":"boolean","default":false,"description":"Marks this branch as the catch-all (see above)."},"name_alias":{"type":"string","description":"Display label. Set from `value` on write."},"segment_users":{"type":"array","items":{"$ref":"#/components/schemas/SegmentCondition"},"description":"Segment DSL conditions (see the Segment Query DSL doc). Ignored on the catch-all branch, which is stored with `[{segment: \"other\"}]`.\n\n**Before constructing this**: call `describeSegmentSchema` (or `GET /v3/segments/schema`) and copy each condition's `condition_template` verbatim, same as the condition node's own top-level `segment_users` — don't invent field/operator tokens here just because this is a nested branch.\n"},"with_or_segment_users":{"type":"array","description":"Alternate inclusion groups for THIS branch only, same OR-logic semantics as Segments' `query.with_or_segment_users`: each inner array is a set of conditions ANDed together, and the outer array is OR-joined with this branch's own `segment_users` and every other group here. Use this to build \"criteria A OR criteria B\" matching for one multi_choice branch without touching its `segment_users`. Optional; has no effect on the `Condition Other` fallback branch or on any other branch's matching.\n","items":{"type":"array","items":{"$ref":"#/components/schemas/SegmentCondition"}}}}},"SalesAutomationAction":{"type":"object","required":["type"],"description":"Polymorphic on `type`. 13 action types available — see `describeFlowSchema` for the full guide + params per action.\n","properties":{"type":{"type":"string","enum":["tags","remove_tags","task","add_stage","move_stage","sync_stage","remove_stage","assign","remove_assign","status","priority","add_note","enroll_in_flow"]},"tag_names":{"type":"array","items":{"type":"string"},"description":"For `tags` / `remove_tags`."},"task_name":{"type":"string","description":"For `task`."},"description":{"type":"string","description":"For `task`."},"due_at":{"$ref":"#/components/schemas/Timestamp","description":"For `task` (write only; converted to `due_in_days`)."},"due_in_days":{"type":"integer","description":"For `task`. Days from the trigger until the task is due. Default 1."},"assignee_staff_id":{"$ref":"#/components/schemas/StaffId","description":"For `task`: one responsible (\"Specific\"). Omit both assignee fields for the contact owner (\"Owner\")."},"assignee_staff_ids":{"type":"array","items":{"$ref":"#/components/schemas/StaffId"},"description":"For `task`: round-robin across these staff."},"assignee_mode":{"type":"string","readOnly":true,"enum":["Owner","Specific","Round Robin"],"description":"For `task`, read only."},"task_type":{"type":"string","description":"For `task`: task type id (`tst_…`). Defaults to the workroom's first type."},"stage_id":{"$ref":"#/components/schemas/StageId","description":"For stage actions. Required: a stage action with no valid stage is rejected (422), since the worker cannot run it."},"staff_ids":{"type":"array","items":{"$ref":"#/components/schemas/StaffId"},"description":"For `assign` / `remove_assign`. Required (non-empty)."},"distribution":{"type":"string","enum":["All","Round Robin"],"description":"For `assign`. Other values (including the dashboard's \"Round Robin By Day\", which needs a per-day roster) are stored as `All` with a warning."},"reassign":{"type":"boolean","default":false,"description":"For `assign`: true replaces a contact's existing responsible; false only fills unassigned contacts."},"value":{"type":"string","description":"For `status` / `priority`."},"note":{"type":"string","description":"For `add_note`."},"flow_id":{"type":"string","description":"For `enroll_in_flow`."},"applies_to":{"type":"string","description":"Segment scope — usually \"All\" or a segment name.","default":"All"}}},"StaffId":{"type":"string","pattern":"^usr_[0-9a-f]{24}$","description":"A staff user (from the legacy `users` collection). Used for `owner_id`, `responsible_id`, `created_by`, `assigned_to`, etc."},"StageId":{"type":"string","pattern":"^stg_[0-9a-f]{24}$"},"FlowStats":{"type":"object","description":"Run counters. `active_runs` and `completed_runs` are current state and do not move with the analytics window; `entered` and `unenrolled` are windowed.\n","properties":{"active_runs":{"type":"integer","minimum":0,"description":"Runs open right now."},"completed_runs":{"type":"integer","minimum":0,"description":"Runs finished","all time.":null},"entered":{"type":"integer","minimum":0,"description":"Contacts enrolled within the window."},"unenrolled":{"type":"integer","minimum":0,"description":"Contacts unenrolled within the window."},"entered_last_30d":{"type":"integer","minimum":0,"deprecated":true,"description":"Same value as `entered`. Kept for existing callers; the name is only accurate when the window is the default 30 days."},"unenrolled_last_30d":{"type":"integer","minimum":0,"deprecated":true,"description":"Same value as `unenrolled`."}}},"Timezone":{"type":"string","description":"IANA timezone name."},"UserId":{"type":"string","pattern":"^usr_[0-9A-HJKMNP-TV-Z]{26}$"}}},"paths":{"/flows":{"get":{"tags":["Flows"],"operationId":"listFlows","summary":"List flows.","description":"Paginated list. Common filters: `?filter[status]=active`, `?filter[name]=welcome` (case-insensitive prefix). `?fields=name,status` keeps only those top-level fields (plus `id`, `object`). Flows in a list never include `nodes`. Rate limit bucket: `read`.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"},{"$ref":"#/components/parameters/LimitParam"},{"$ref":"#/components/parameters/CursorParam"},{"$ref":"#/components/parameters/SortParam"},{"$ref":"#/components/parameters/FieldsParam"},{"name":"filter","in":"query","style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":{"type":"string"}}}],"responses":{"200":{"description":"A page of flows.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ListEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Flow"}}}}]}}}}}}}}}
```

## Create a draft flow.

> Creates a flow in \`draft\` status — nothing enrolls until \`POST /v3/flows/{id}/publish\`. The DAG is validated at save (cycle detection, orphan-parent detection, node-type-specific field checks). Rate limit bucket: \`write\`.\
> \
> \*\*CRITICAL for \`email\_campaign\` and \`sms\_campaign\` nodes: provide actual content.\*\* Each such node MUST specify one of:\
> &#x20; \- inline \`subject\` + \`message\_body\` (+ optional \`preheader\_text\`, \`from\_name\`, \`from\_email\` for email)\
> &#x20; \- \`template\_id\` referencing a template\
> &#x20; \- \`campaign\_id\` referencing a campaign that already has content\
> \
> A campaign-type node with none of these creates an empty shadow campaign that the send worker will refuse to fire. Flow message nodes need finished copy: blank or stubbed subject lines and bodies are what the flow will actually send. \`from\_name\`/\`from\_email\`/\`from\_number\` inherit from the workroom's app defaults when omitted, so it's fine to leave those unset.\
> \
> \*\*CRITICAL: set the enrollment trigger.\*\* \`entry.segment\_ids\` is what makes the flow fire, and publishing is refused without it (\`no\_entry\_segment\`) because an empty entry segment would enroll the whole workroom. A flow created with an empty \`entry\` comes back with a \`no\_entry\_trigger\` warning, cannot be published, and shows an empty "Enroll the audience" panel in the dashboard. Entry is by segment membership, so a trigger expressed in words ("when someone cancels", "new leads") corresponds to a segment that has to exist and be attached here. A flow with no \`entry.segment\_ids\` is created but never enrols anyone.\
> \
> The flow is placed in the workroom that owns \`entry.segment\_ids\`, so you normally don't pass \`workroom\` at all. Segments from two different workrooms in one flow are rejected. Response \`warnings\[]\` names any ID that could not be attached (\`unknown\_segment\_id:…\`, \`cross\_workroom\_segment\_id:…\`), so a flow can be created with its trigger silently unattached.\
> \
> \`describeSegmentSchema\` (\`GET /v3/segments/schema\`) returns the available categories. Concepts with a first-class category resolve against that category rather than a custom field; see \`createSegment\` for the full rule.\
> \
> Requires a name, an entry audience (\`entry.segment\_ids\`) and the step definitions. Optional fields fall back to a server-side default when omitted, including the workroom — an omitted workroom resolves to the account default, and a flow created in the wrong workroom is invisible where it was expected.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Flows","description":"Multi-step automations. Enrollment is driven by segment membership. 7 node types are supported by the engine — see the Flow Engine companion doc for the full model, including the versioning and in-flight-edit caveats."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["flows:write"]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"},"OAuth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE. Use for third-party apps acting on behalf of a Gleantap user.\nAuthorization Code + PKCE is the only supported grant for interactive flows; refresh_token grant is supported and rotates on every use.\n","flows":{"authorizationCode":{"authorizationUrl":"https://api.gleantap.com/v3/oauth/authorize","tokenUrl":"https://api.gleantap.com/v3/oauth/token","refreshUrl":"https://api.gleantap.com/v3/oauth/token","scopes":{"contacts:read":"Read contact records.","contacts:write":"Create, update, delete contacts (soft delete).","contacts:delete_hard":"Hard-delete contacts (irreversible).","events:read":"Read event records.","events:write":"Record events.","segments:read":"Read segments and preview membership.","segments:write":"Create, update, delete segments.","templates:read":"Read message templates.","templates:write":"Create, update, delete templates.","campaigns:read":"Read campaigns and analytics.","campaigns:write":"Create, schedule, cancel campaigns.","flows:read":"Read flow definitions and analytics.","flows:write":"Create, edit, publish flows.","flows:publish":"Publish/unpublish flows (separately scoped for governance).","messaging:send":"Send transactional messages (SMS, email, voice).","conversations:read":"Read conversations and messages.","conversations:write":"Send messages, close/reopen conversations.","webhooks:manage":"Create, update, delete webhook endpoints.","forms:manage":"Create, update, delete, publish, duplicate forms; list submissions and rotate the submission_token.","campaigns:manage":"Create, schedule, cancel, duplicate campaigns; read recipients and analytics. (Supersedes the earlier `campaigns:read` + `campaigns:write` split; the split scopes still work.)","admin:impersonate:read":"Gleantap staff only — read any customer account named via `Gleantap-Account`. Not available through dynamic client registration.","admin:impersonate:write":"Gleantap staff only — required for any state-changing method while impersonating. Not available through dynamic client registration."}}}}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"WorkroomQuery":{"name":"workroom","in":"query","required":false,"description":"Same semantics as the `Gleantap-Workroom` header, including that a write should never be sent without a workroom the user actually chose, and that an omitted workroom scopes a read to the account default rather than spanning the account. Prefer this on GETs so proxies and caches can key on it. Accepts name, prefixed ID, raw hex, or `all`.\n","schema":{"type":"string"}},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"description":"A unique key (≤255 chars) chosen by the client. Replays with the same key + same body return the cached response. Replays with the same key + different body return 409 `idempotency_conflict`. Required on messaging sends and bulk operations; recommended elsewhere.\n","schema":{"type":"string","maxLength":255}}},"schemas":{"FlowCreate":{"type":"object","required":["name","entry","nodes"],"description":"Creates a `draft` flow. Nothing enrolls until `POST /v3/flows/{id}/publish`. The DAG is validated at save time (cycle detection, orphan-parent detection, node-type-specific field requirements).\n","properties":{"name":{"type":"string","maxLength":200},"description":{"type":"string","maxLength":2000},"entry":{"$ref":"#/components/schemas/FlowEntry"},"nodes":{"type":"array","items":{"$ref":"#/components/schemas/FlowNode"}},"conversion_config":{"type":"object","properties":{"conversion_ids":{"type":"array","items":{"type":"string"}},"attribution_window_days":{"type":"integer","minimum":1}}},"timezone":{"$ref":"#/components/schemas/Timezone"},"metadata":{"$ref":"#/components/schemas/Metadata"}}},"FlowEntry":{"type":"object","description":"Flow enrollment configuration. Enrollment is driven by segment membership — contacts entering `segment_ids` are enrolled on the next cron pass. Rich trigger vocab (`event`, `form_submission`, `appointment_booked`, etc.) is not first-class in the engine; model those via a segment that captures the trigger criteria.\n\n**Set a trigger.** Publishing requires `segment_ids`. A flow without them is created with a `no_entry_trigger` warning and publishing is refused with `no_entry_segment`: the send worker enrolls every contact in the entry segment, so a flow with none would enroll the whole workroom. `segment_criteria` and `manual_only` are not read by the worker; save criteria as a segment and use its id.\n\n**Workroom matching.** A flow lives in exactly one workroom and can only be triggered by segments from that same workroom. Compare `Segment.workroom_id` with `Flow.workroom_id`. On create you don't need to pass `workroom`: the flow is placed in the workroom that owns `segment_ids`. Segments spanning two workrooms are rejected — build one flow per workroom. On PATCH the workroom is already fixed, so a sibling-workroom segment is rejected with `422 invalid_segment_ids`.\n","properties":{"segment_ids":{"type":"array","items":{"$ref":"#/components/schemas/SegmentId"},"description":"Contacts entering ANY of these segments enter the flow. Must all belong to one workroom."},"segments":{"type":"array","items":{"$ref":"#/components/schemas/Segment"},"description":"Inlined Segment objects when `?expand=entry.segments` is requested."},"unenroll_segment_ids":{"type":"array","items":{"$ref":"#/components/schemas/SegmentId"},"description":"Contacts entering ANY of these segments are unenrolled from in-flight runs. Must belong to the flow's workroom."},"unenroll_segments":{"type":"array","items":{"$ref":"#/components/schemas/Segment"},"description":"Inlined unenroll Segment objects when `?expand=entry.segments` is requested."},"manual_only":{"type":"boolean","default":false,"description":"Marks a flow meant for `POST /v3/flows/{id}/enroll`. It does not remove the need for `segment_ids` to publish: the send worker enrolls the entry segment regardless, so use a segment that matches nobody until you enroll contacts."},"reenroll":{"type":"boolean","default":false,"description":"Allow contacts who completed the flow to enter again. Stored as the dashboard's `reenroll_status`, which is the only field the flow worker reads. The worker re-enrolls a contact who still matches the entry segment once their finished run started before today (account timezone); the old run moves to history and the new run has `reenroll: true`. Manual enroll (`POST /enroll`) follows the same rule.\n\nReads report what the worker will do: flows saved by older API versions with only `reenroll` set read `false` until re-saved.\n"},"reentry_cooldown_days":{"type":"integer","nullable":true,"deprecated":true,"description":"Not supported, and ignored. The flow worker has no re-entry cooldown. Sending a value returns a `reentry_cooldown_days_unsupported` warning and nothing is stored. To space re-entries, build the gap into the entry segment."},"end_date_time":{"$ref":"#/components/schemas/Timestamp","nullable":true,"description":"Flow auto-completes past this time. New enrollments halted; in-flight runs continue."},"segment_criteria":{"$ref":"#/components/schemas/SegmentQuery","nullable":true,"description":"Stored and echoed back only. The enrollment worker never reads it: who enters is decided by `segment_ids` alone, and it does not narrow them. To enroll on criteria, save them as a segment (`POST /v3/segments`) and put its id in `segment_ids`."}}},"SegmentId":{"type":"string","pattern":"^seg_[0-9A-HJKMNP-TV-Z]{26}$"},"Segment":{"type":"object","description":"A named collection of contacts. Either static (hand-managed list) or dynamic (query-defined). Discriminated by the `type` field, which is immutable after creation.\n","required":["id","object","type","name","size","created_at","updated_at"],"properties":{"id":{"$ref":"#/components/schemas/SegmentId"},"object":{"type":"string","const":"segment"},"workroom_id":{"$ref":"#/components/schemas/WorkroomId","nullable":true,"description":"The workroom that owns this segment. A flow can only be triggered by segments in its own workroom — compare against `Flow.workroom_id`."},"type":{"$ref":"#/components/schemas/SegmentType"},"name":{"type":"string","maxLength":200},"description":{"type":"string","nullable":true,"maxLength":2000},"query":{"$ref":"#/components/schemas/SegmentQuery","nullable":true,"description":"The segment's criteria. **Present on BOTH static and dynamic segments** — a \"static\" segment only means the engine doesn't auto-refresh membership; the criteria that defined the initial membership list is still stored and returned. When diagnosing \"why did this contact match this segment?\", read `query.segment_users` (+ `with_or_segment_users` and `exclude_segment_users`). May be `null` only on segments imported without criteria or created empty.\n"},"size":{"type":"integer","minimum":0,"description":"Current member count. Eventually consistent — up to minutes of lag on dynamic segments."},"email_count":{"type":"integer","minimum":0,"description":"Members with a non-empty, non-invalid email."},"phone_count":{"type":"integer","minimum":0,"description":"Members with a non-empty, non-invalid phone."},"last_evaluated_at":{"$ref":"#/components/schemas/Timestamp","nullable":true,"description":"When this dynamic segment was last recomputed. Null on static."},"folder_id":{"$ref":"#/components/schemas/SegmentFolderId","nullable":true,"description":"The segment folder this segment currently belongs to, or `null` if unfoldered."},"segment_summary":{"type":"string","nullable":true,"description":"AI-generated narrative summary of the segment's criteria. Populated on demand via `POST /v3/segments/{id}/summary`."},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"metadata":{"$ref":"#/components/schemas/Metadata"}}},"WorkroomId":{"type":"string","pattern":"^wrm_[0-9a-f]{24}$"},"SegmentType":{"type":"string","enum":["static","dynamic"],"description":"`static` — hand-managed member list. Contacts are added/removed explicitly.\n`dynamic` — query-defined membership. Auto-evaluated; membership changes as contact data changes.\nImmutable after creation.\n"},"SegmentQuery":{"type":"object","description":"The segment criteria. **Present on BOTH `static` and `dynamic` segments** — \"static\" only means the engine doesn't auto-refresh membership; the criteria that defined the segment is still on the doc, and diagnostic tools (like \"why did this contact match this segment?\") MUST read it here.\n\nFull match logic:\n\n  (all `segment_users` ANDed together)\n  OR (all conditions in `with_or_segment_users[0]` ANDed)\n  OR (all conditions in `with_or_segment_users[1]` ANDed)\n  OR ...\n  MINUS contacts removed by `exclude_segment_users` (all ANDed) — self-match or shared-copy match per the account setting below\n\nHow `exclude_segment_users` matches depends on the account's `shared_contact_status` (surfaced as `shared_contacts_enabled` on `GET /segments/schema`). When shared contacts are ENABLED it is the dashboard's \"exclude shared contacts\" rule: a contact is removed when one of its linked copies in another workroom (`shared_contacts[]`) matches these conditions, NOT when the contact itself matches. When shared contacts are OFF it is a plain self-subtraction: the contact is removed when its OWN fields match. The exclusion can be any condition (attribute match, event done, tag, form filled — just the positive form of what to exclude). Either way the segment must keep at least one primary condition in `segment_users`; an exclude-only (or `with_or`-only) query is rejected. To exclude by a contact's own attributes regardless of the account setting, you can also use a negative condition in `segment_users` (e.g. `Is Not One Of`, `Has not Filled a Form`, `Does Not Contain`).\n\nConditions are stored in the exact tokens the dashboard's segment engine evaluates: friendly category names are rewritten on write (`Custom`/`attributes` → `Attributes`, `email_engagement` → `EmailCampaigns`, `salesattributes` → `sales`, …), and an absolute-date `<`/`>` on a Date field is stored as `Before`/`After` with an `MM-DD-YYYY` value. A retrieved segment therefore shows the stored (engine) form.\n\nThere is no additional `all/any/none` grouping. Express further OR via multi-value operators (`Is One Of`, `Segments` with an array).\n","properties":{"segment_users":{"type":"array","items":{"$ref":"#/components/schemas/SegmentCondition"},"description":"Base inclusion conditions. All ANDed. A contact must satisfy every one to be included via this group."},"with_or_segment_users":{"type":"array","description":"Alternate inclusion groups. Each inner array is a set of conditions that are ANDed together; the outer array is OR-joined with `segment_users` and each other inner array. Use this to build \"criteria A OR criteria B\" queries without touching the top-level `segment_users`.\n","items":{"type":"array","items":{"$ref":"#/components/schemas/SegmentCondition"}}},"exclude_segment_users":{"type":"array","items":{"$ref":"#/components/schemas/SegmentCondition"},"description":"Exclusion conditions, ANDed. How they match depends on the account's `shared_contact_status` — shared-copy match when shared contacts are ON (a contact is removed when a linked copy in another workroom, `shared_contacts[]`, matches all of them), self-match when OFF (removed when the contact's own fields match all of them). Same condition shape as `segment_users`. Cannot stand alone — `segment_users` must be non-empty. See the match logic above."}}},"SegmentCondition":{"type":"object","description":"A single condition in a dynamic segment query. Shape and operator vocabulary are documented in the Segment Query DSL companion doc — the query language supports 28 segment types (Attributes, Tags, Event Trigger, External Events, Segments, SalesAttributes, Forms, Flows, Optin, and more) and 60+ operators. This schema is intentionally loose to accommodate that surface; the server validates the concrete shape.\n","required":["segment","operator"],"additionalProperties":true,"properties":{"segment":{"type":"string","description":"Segment-type discriminator. Full inventory in the DSL doc. Common values include `Attributes`, `Tags`, `Country`, `City`, `Event Trigger`, `External Events`, `Segments`, `SalesAttributes`, `Forms`, `Flows`, `SMS Optin`, `SMS Opted Out`, `Email Topics`, `Add Date`, `Last Access`.\n"},"data":{"type":"string","description":"Field or attribute within the segment type. E.g., `first_name`, `city`, `sales.pipeline.stage`.","nullable":true},"event":{"type":"string","description":"Event name — used only when `segment` is `Event Trigger`.","nullable":true},"operator":{"type":"string","description":"Operator vocabulary. Full list in the DSL doc. Common: `=`, `!=`, `<`, `>` (numeric — on a Date field they are stored as `Before`/`After`), `Contains`, `Does Not Contain`, `Is One Of`, `Is Not One Of`, `Is Empty`, `Is Not Empty`, `Exists`, `Does Not Exist`, `Is True`, `Is False`, `InLast`, `OverDays`, `InNext`, `Before`, `After`, `IsToday`, `DayInNext`, `DayInMonth`, `Is In Segment`, `Is Not In Segment`, `Has Filled a Form`. For recurring day-of-year fields (`data_type: Day`, e.g. Birthday) use the `DayInNext`/`DayInNextXY`/`DayInMonth` family — not the absolute-date `InNext`/`=` — so \"birthday in the next N days\" recurs every year (see `describeSegmentSchema`).\n\n`Exists`/`Does Not Exist` vs `Is Not Empty`/`Is Empty`: both check for a populated value and are usually close in practice, but `Exists` is what the dashboard UI itself uses when a user says a field \"exists\" - prefer `Exists`/`Does Not Exist` for that phrasing, especially inside `with_or_segment_users`, to match what the UI would produce for the same request.\n"},"value":{"type":["string","number","boolean","array","null"],"description":"The operand. Which type applies depends on the operator: a scalar for `=` and `Contains`, an array (or comma-separated string) for `Is One Of`, a number for count comparisons, and omitted entirely for `Exists` / `Is Empty`.\n"},"value2":{"type":["string","number","null"],"description":"Secondary operand for two-parameter conditions (currently `External Events` count comparison and `SalesAttributes` pipeline-stage filter)."},"operator2":{"type":"string","description":"Secondary operator for two-parameter conditions.","nullable":true},"value2_id":{"type":"array","items":{"type":"string"},"nullable":true,"description":"Object-ID list for stage-title disambiguation on `SalesAttributes`."},"data_type":{"type":"string","enum":["String","Numeric","Date","List"],"nullable":true,"description":"Optional hint for the engine's disambiguation logic."},"dataAlias":{"type":"string","nullable":true,"description":"Human-readable alias shown in the UI. Not evaluated."}}},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"SegmentFolderId":{"type":"string","pattern":"^sfd_[0-9a-fA-F]{24}$","description":"Segment folder ID."},"Metadata":{"type":"object","description":"Free-form key/value pairs the caller stores on the resource. Not evaluated by Gleantap.\nUse for opaque identifiers, integration state, or notes you need to survive round-trips.\n","additionalProperties":true},"FlowNode":{"type":"object","required":["id","type"],"description":"A node in a flow's DAG. Polymorphic on `type` — only the fields relevant to that type should be set (unused fields ignored). See per-type notes below.\n\n**Parent/child edges:** each node has `parent_id` pointing at another node's `id`. Root nodes have `parent_id: null` and `parent_branch: \"root\"`. For `condition` nodes with `action_type: \"yes_no\"`, children set `parent_branch: \"yes\"` or `\"no\"`. For `multi_choice` conditions, children set `parent_branch: \"<matched value>\"` (slugified — spaces → underscores, lowercased). For `wait_till_true` conditions, there is no branching at all — the node re-evaluates itself until its predicate matches (see `FlowConditionMode`), and its child (if any) hangs off the ordinary linear `parent_branch: \"next\"` edge, the same as a non-condition node.\n\n**Client-supplied `id`:** you supply a string identifier per node (unique within the flow). The server uses it to resolve `parent_id` references. IDs need not survive updates — the server maps them to internal IDs at save time.\n","properties":{"id":{"type":"string","maxLength":100,"pattern":"^[a-zA-Z0-9_-]+$","description":"Client-supplied identifier, unique within this flow."},"type":{"$ref":"#/components/schemas/FlowNodeType"},"parent_id":{"type":"string","nullable":true,"description":"The `id` of this node's parent. Null for root nodes."},"parent_branch":{"type":"string","default":"root","description":"Which branch of the parent this node hangs off. `root` for the flow's entry node, `next` for a linear step, `yes`/`no` for a yes_no condition child, the slugified condition `value` for a multi_choice child, or `converge` to rejoin branches after a condition node.\n"},"action_name":{"type":"string","maxLength":200,"description":"Label shown in the UI. Optional; defaults per node type."},"campaign_id":{"$ref":"#/components/schemas/CampaignId","nullable":true,"description":"Optional. If provided, the server upgrades that existing campaign into a \"shadow\" dedicated to this flow node (adds `isAutomationCampaign=true` + `automation_id` + `automation_details_id`). The campaign is no longer a standalone after this — do not share campaign_ids across flows or reuse for one-off sends.\n"},"template_id":{"$ref":"#/components/schemas/TemplateId","nullable":true,"description":"Optional. Seeds the shadow campaign's content from a library template. For `email_campaign` the template's rendered HTML, its editor design JSON and its thumbnail are all copied onto the node, which is what makes the dashboard open it as an **HTML email** (the \"HTML Email\" toggle) rather than a plain-text one — a node given only inline `message_body` is plain text by design. An explicit `message_body` on the same node overrides the template's HTML body; `subject` is never taken from the template. Render happens at send time — merge tags interpolate per-recipient using the flow's audience data.\n"},"subject":{"type":"string","nullable":true,"description":"For `email_campaign` nodes. Email subject line. Supports merge tags (`{first_name}`, `{data.company}`). REQUIRED unless `template_id` or `campaign_id` provided.\n"},"message_body":{"type":"string","nullable":true,"description":"For both `email_campaign` (HTML body) and `sms_campaign` (plain-text body). Supports merge tags. REQUIRED unless `template_id` or `campaign_id` provided.\n`sms_campaign`: At most 10 SMS segments: 1530 plain (GSM-7) characters, or 670 if the text contains emoji or any other non-GSM character (once split, each segment holds 153 GSM / 67 unicode characters; emoji count as 2). Merge tags count as written, not expanded. A longer body (inline or from `template_id`) is rejected with 422 `validation_failed`.\n"},"preheader_text":{"type":"string","nullable":true,"description":"For `email_campaign`. Preheader shown in inbox previews after subject."},"from_name":{"type":"string","nullable":true,"description":"For `email_campaign`. Sender display name. Inherits app default when omitted."},"from_email":{"type":"string","format":"email","nullable":true,"description":"For `email_campaign`. Sender address. Inherits app default when omitted."},"from_number":{"type":"string","nullable":true,"description":"For `sms_campaign`. E.164 sender phone. Inherits app default when omitted."},"schedule":{"type":"string","enum":["Relative","Specific Date & Time"],"nullable":true,"description":"For `delay` nodes."},"delayTimeHour":{"type":"integer","nullable":true,"description":"For `delay` with `schedule: \"Relative\"`. Amount of `delayTimetype`."},"delayTimetype":{"type":"string","enum":["minutes","hours","days","weeks","months"],"nullable":true,"description":"For `delay` with `schedule: \"Relative\"`."},"selected_date":{"type":"string","format":"date","nullable":true,"description":"For `delay` with `schedule: \"Specific Date & Time\"`."},"selected_time":{"type":"string","nullable":true,"description":"For `delay` with `schedule: \"Specific Date & Time\"`. `HH:mm:ss` in the flow's timezone."},"action_type":{"$ref":"#/components/schemas/FlowConditionMode","nullable":true,"description":"For `condition` nodes."},"segment_users":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/SegmentCondition"},"description":"For `condition` with `action_type: \"yes_no\"` or `\"wait_till_true\"`. Segment DSL predicates — materialized into a hidden shadow segment for either mode (see `FlowConditionMode`) so the live cron can evaluate it.\n\n**Before constructing this**: call `describeSegmentSchema` (or `GET /v3/segments/schema`) to see available categories and copy each attribute's `condition_template` (segment/data/dataAlias/data_type) verbatim, using an `operator` from that field's `operators[]` — the same rule `createSegment`'s conditions follow. Don't guess a field key or reach for a human phrase like \"Before\" from general knowledge; the schema call is what tells you the exact tokens the engine expects.\n"},"with_or_segment_users":{"type":"array","nullable":true,"description":"For `condition` with `action_type: \"yes_no\"` or `\"wait_till_true\"` only — same OR-logic semantics as Segments' `query.with_or_segment_users`: each inner array is ANDed, and the outer array is OR-joined with `segment_users` and every other group. Materialized into the same hidden shadow segment as `segment_users` (confirmed live: `attach_condition_segment()` writes both fields identically onto the shadow segment doc, and the engine reads it from there). For `multi_choice`, use `with_or_segment_users` on the individual `FlowMultiCondition` branch instead — this top-level field is ignored for that mode.\n\nEchoed back on create/retrieve just like `segment_users` (it is persisted on the condition node itself in addition to the shadow segment), so a round-trip reflects exactly what you sent.\n","items":{"type":"array","items":{"$ref":"#/components/schemas/SegmentCondition"}}},"multi_conditions":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/FlowMultiCondition"},"description":"For `condition` with `action_type: \"multi_choice\"`."},"salesautomation_id":{"type":"string","nullable":true,"pattern":"^saut_[0-9A-HJKMNP-TV-Z]{26}$","description":"For `sales_automation` nodes. References a CRM automation created via `POST /v3/pipelines/{pipeline_id}/automations`."},"sales_automation":{"type":"object","nullable":true,"description":"For `sales_automation` nodes, instead of `salesautomation_id`: an inline CRM rule. v3 creates the rule and binds it to this node. Send `action` for one action or `actions` for several (run in order). Do not send a `trigger`; the flow decides when it runs.","properties":{"action":{"$ref":"#/components/schemas/SalesAutomationAction"},"actions":{"type":"array","items":{"$ref":"#/components/schemas/SalesAutomationAction"}}}},"webhook_url":{"type":"string","format":"uri","nullable":true,"description":"REQUIRED on `webhook` nodes — creating one without it returns 422. A webhook with no destination can never fire, and the dashboard refuses to save one for the same reason. Must be `https://` unless the account has `allow_http_webhooks: true`.\n\nGet the URL from the user. There is no sensible default and no way to infer it.\n"},"webhook_method":{"type":"string","enum":["GET","POST"],"default":"GET","description":"The flow worker only sends GET or POST; any other value is a 422 (it would silently go out as GET).","nullable":true},"webhook_payload_type":{"type":"string","enum":["json","form"],"default":"json","nullable":true},"webhook_fields":{"type":"array","nullable":true,"description":"REQUIRED on `webhook` nodes: at least one `{key, value}` pair with a non-empty `key` and `value` (`\"0\"` counts as empty). The flow worker builds the request only from such pairs and sends NOTHING when there are none — for GET (query string) as well as POST — so a node without one is a 422. Every entry must be an object with string `key` and `value`. `key` may use dot notation for nesting. Ask the user what the receiving system expects.\n","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string","description":"Supports `{placeholder}` interpolation from contact fields (e.g., `{first_name}`, `{email}`, `{data.custom_field}`)."}}}},"webhook_header_fields":{"type":"array","nullable":true,"description":"Optional request headers. Each entry needs a non-empty `key` and `value` (422 otherwise — the worker would drop it).","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}}}},"mariana_action":{"type":"object","nullable":true,"description":"Required for `mariana_action` nodes. Gives the enrolled contact something in the workroom's Mariana Tek studio. The contact is found by their Mariana id or exact email; with `if_not_found: create` a Mariana account is created from their email and name and Mariana emails them a set-password link. Each enrollment gives at most once. Amount and credit caps are the workroom's limits (default 100 and 20); values over them, or a malformed config, are rejected 422 so a saved node always runs.\n","required":["type"],"properties":{"type":{"type":"string","enum":["pack","class_credits","account_credit"]},"package_id":{"type":"string","description":"Mariana pack (package) id. `pack`: gives that pack's class credits with the pack's own expiry."},"package_name":{"type":"string","description":"Display name for the pack."},"credit_id":{"type":"string","description":"`class_credits`: Mariana credit type id."},"credit_name":{"type":"string"},"quantity":{"type":"integer","minimum":1,"description":"`class_credits`: number of credits (at most the workroom limit, default 20)."},"expiry_days":{"type":"string","description":"`class_credits`: whole days until the credits expire; empty for no expiry."},"amount":{"type":"number","description":"`account_credit`: amount to add, up to 2 decimals and the workroom limit (default 100)."},"currency":{"type":"string","description":"`account_credit`: 3-letter code, default USD."},"note":{"type":"string","maxLength":60,"description":"Shown on the credit in Mariana."},"if_not_found":{"type":"string","enum":["create","skip"],"default":"create"},"recipient":{"type":"string","enum":["contact","referrer"],"default":"contact","description":"`referrer` gives to the member who referred the contact (their `referred_by_id` in the same workroom, set by the referral intake) instead of the contact, once per enrollment. Use it in a referred friend's flow to reward the member."}}}}},"FlowNodeType":{"type":"string","enum":["email_campaign","sms_campaign","delay","condition","sales_automation","webhook","mariana_action"],"description":"The 7 node types the engine actually supports (`mariana_action` gives the contact a pack, class credits or account credit in the workroom's Mariana Tek studio). Richer vocab from the main spec (`send_message`, `tag`, `add_to_segment`, `update_contact`, `create_task`, `create_opportunity`, `wait_for_event`, `split`, `end`) is NOT implemented — express those via `sales_automation` (pointing at a CRM sub-automation) or return 501 `node_type_not_supported`. See Flow Engine companion doc §10.\n"},"CampaignId":{"type":"string","pattern":"^cam_[0-9a-f]{24}$"},"TemplateId":{"type":"string","pattern":"^tpl_[0-9a-f]{24}$"},"FlowConditionMode":{"type":"string","enum":["yes_no","multi_choice","wait_till_true"],"description":"`yes_no` — evaluates the `segment_users` predicate once, immediately, and branches: children set `parent_branch: \"yes\"` or `\"no\"` (see FlowNode's parent/child edges note). `multi_choice` — evaluates `multi_conditions` in order; the first match's slugified `value` becomes the child branch. `wait_till_true` — does NOT branch. It re-evaluates the SAME predicate, on the SAME node, on the engine's existing cron cadence, until it matches; only then does execution advance (linearly, via the ordinary `next` edge — there is no \"no\" child to fall through to). Confirmed against the dashboard/flow engine (`Cron.php`'s condition handling): while unmatched, the node is flagged `condition_repeat: true` and re-checked on the next cron pass rather than branching, and — unlike a `yes_no` match — a `wait_till_true` match never writes `operation_parent_type`/`operation_parent_id` on its action-story entry, confirming it has no yes/no children of its own.\n\n**Materialization (fixed — previously a known gap):** both `yes_no` and `wait_till_true` are evaluated by the engine against a legacy `yes_condition` field, which this API materializes from `segment_users` into a hidden shadow segment at creation time. `wait_till_true` is now included in that materialization the same way `yes_no` already was — a `wait_till_true` node created via this API is fully wired for the live cron to evaluate, not merely accepted and stored. Archiving a flow deletes these shadow segments (the node keeps `segment_users`, so duplicating the flow rebuilds them).\n"},"FlowMultiCondition":{"type":"object","required":["value"],"description":"One branch of a `multi_choice` condition. The engine evaluates each in order; the first `segment_users` match wins. Up to 6 regular branches plus one optional catch-all.\n\n**Storage.** Regular branches are stored as `Condition A`..`Condition F` in the order given, with your label kept as `name_alias` (what the dashboard shows). Children may reference a branch by your label, by `Condition A`, or by `condition_a`.\n\n**Catch-all.** Mark a branch with `is_other: true` (or `value: \"Other\"` / `\"Condition Other\"`). It is stored exactly as the dashboard stores it — `{value: \"Condition Other\", segment_users: [{segment: \"other\"}]}` — always last, and it matches every contact no earlier branch matched; any `segment_users` you give it are ignored (warning `other_branch_conditions_ignored`). Children reference it as `Other` / `condition_other`. Without a catch-all, a contact who matches no branch does not advance. More than 6 regular branches, or two catch-alls, is a 422. Reads echo `is_other: true` on the catch-all.\n","properties":{"value":{"type":"string","description":"Human-readable branch name (stored as `name_alias`; `value` becomes `Condition A`..`F`). `Other` / `Condition Other` marks the catch-all."},"is_other":{"type":"boolean","default":false,"description":"Marks this branch as the catch-all (see above)."},"name_alias":{"type":"string","description":"Display label. Set from `value` on write."},"segment_users":{"type":"array","items":{"$ref":"#/components/schemas/SegmentCondition"},"description":"Segment DSL conditions (see the Segment Query DSL doc). Ignored on the catch-all branch, which is stored with `[{segment: \"other\"}]`.\n\n**Before constructing this**: call `describeSegmentSchema` (or `GET /v3/segments/schema`) and copy each condition's `condition_template` verbatim, same as the condition node's own top-level `segment_users` — don't invent field/operator tokens here just because this is a nested branch.\n"},"with_or_segment_users":{"type":"array","description":"Alternate inclusion groups for THIS branch only, same OR-logic semantics as Segments' `query.with_or_segment_users`: each inner array is a set of conditions ANDed together, and the outer array is OR-joined with this branch's own `segment_users` and every other group here. Use this to build \"criteria A OR criteria B\" matching for one multi_choice branch without touching its `segment_users`. Optional; has no effect on the `Condition Other` fallback branch or on any other branch's matching.\n","items":{"type":"array","items":{"$ref":"#/components/schemas/SegmentCondition"}}}}},"SalesAutomationAction":{"type":"object","required":["type"],"description":"Polymorphic on `type`. 13 action types available — see `describeFlowSchema` for the full guide + params per action.\n","properties":{"type":{"type":"string","enum":["tags","remove_tags","task","add_stage","move_stage","sync_stage","remove_stage","assign","remove_assign","status","priority","add_note","enroll_in_flow"]},"tag_names":{"type":"array","items":{"type":"string"},"description":"For `tags` / `remove_tags`."},"task_name":{"type":"string","description":"For `task`."},"description":{"type":"string","description":"For `task`."},"due_at":{"$ref":"#/components/schemas/Timestamp","description":"For `task` (write only; converted to `due_in_days`)."},"due_in_days":{"type":"integer","description":"For `task`. Days from the trigger until the task is due. Default 1."},"assignee_staff_id":{"$ref":"#/components/schemas/StaffId","description":"For `task`: one responsible (\"Specific\"). Omit both assignee fields for the contact owner (\"Owner\")."},"assignee_staff_ids":{"type":"array","items":{"$ref":"#/components/schemas/StaffId"},"description":"For `task`: round-robin across these staff."},"assignee_mode":{"type":"string","readOnly":true,"enum":["Owner","Specific","Round Robin"],"description":"For `task`, read only."},"task_type":{"type":"string","description":"For `task`: task type id (`tst_…`). Defaults to the workroom's first type."},"stage_id":{"$ref":"#/components/schemas/StageId","description":"For stage actions. Required: a stage action with no valid stage is rejected (422), since the worker cannot run it."},"staff_ids":{"type":"array","items":{"$ref":"#/components/schemas/StaffId"},"description":"For `assign` / `remove_assign`. Required (non-empty)."},"distribution":{"type":"string","enum":["All","Round Robin"],"description":"For `assign`. Other values (including the dashboard's \"Round Robin By Day\", which needs a per-day roster) are stored as `All` with a warning."},"reassign":{"type":"boolean","default":false,"description":"For `assign`: true replaces a contact's existing responsible; false only fills unassigned contacts."},"value":{"type":"string","description":"For `status` / `priority`."},"note":{"type":"string","description":"For `add_note`."},"flow_id":{"type":"string","description":"For `enroll_in_flow`."},"applies_to":{"type":"string","description":"Segment scope — usually \"All\" or a segment name.","default":"All"}}},"StaffId":{"type":"string","pattern":"^usr_[0-9a-f]{24}$","description":"A staff user (from the legacy `users` collection). Used for `owner_id`, `responsible_id`, `created_by`, `assigned_to`, etc."},"StageId":{"type":"string","pattern":"^stg_[0-9a-f]{24}$"},"Timezone":{"type":"string","description":"IANA timezone name."},"Flow":{"type":"object","required":["id","object","name","status","entry","nodes","created_at","updated_at"],"properties":{"id":{"$ref":"#/components/schemas/FlowId"},"object":{"type":"string","const":"flow"},"name":{"type":"string","maxLength":200},"description":{"type":"string","nullable":true,"maxLength":2000},"status":{"$ref":"#/components/schemas/FlowStatus"},"workroom_id":{"$ref":"#/components/schemas/WorkroomId","nullable":true,"description":"The workroom this flow lives in. Its `entry.segment_ids` must all belong to the same workroom."},"entry":{"$ref":"#/components/schemas/FlowEntry"},"nodes":{"type":"array","items":{"$ref":"#/components/schemas/FlowNode"}},"stats":{"$ref":"#/components/schemas/FlowStats"},"conversion_config":{"type":"object","nullable":true,"description":"Optional conversion goal(s) tracked per contact per run.","properties":{"conversion_ids":{"type":"array","items":{"type":"string"}},"attribution_window_days":{"type":"integer","minimum":1,"nullable":true}}},"timezone":{"$ref":"#/components/schemas/Timezone","nullable":true,"description":"Timezone used to interpret `delay` node \"Specific Date & Time\" values. Defaults to the account timezone."},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"published_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"archived_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"created_by_user_id":{"$ref":"#/components/schemas/UserId","nullable":true},"metadata":{"$ref":"#/components/schemas/Metadata"}}},"FlowId":{"type":"string","pattern":"^flw_[0-9A-HJKMNP-TV-Z]{26}$"},"FlowStatus":{"type":"string","enum":["draft","active","inactive","paused","completed","archived"],"description":"`draft` — never published. `active` — published and enrolling. `inactive` — unpublished; in-flight runs continue but no new entries. `paused` — enrollment and step execution both halted; can be resumed. `completed` — `end_date_time` passed. `archived` — soft-deleted.\n"},"FlowStats":{"type":"object","description":"Run counters. `active_runs` and `completed_runs` are current state and do not move with the analytics window; `entered` and `unenrolled` are windowed.\n","properties":{"active_runs":{"type":"integer","minimum":0,"description":"Runs open right now."},"completed_runs":{"type":"integer","minimum":0,"description":"Runs finished","all time.":null},"entered":{"type":"integer","minimum":0,"description":"Contacts enrolled within the window."},"unenrolled":{"type":"integer","minimum":0,"description":"Contacts unenrolled within the window."},"entered_last_30d":{"type":"integer","minimum":0,"deprecated":true,"description":"Same value as `entered`. Kept for existing callers; the name is only accurate when the window is the default 30 days."},"unenrolled_last_30d":{"type":"integer","minimum":0,"deprecated":true,"description":"Same value as `unenrolled`."}}},"UserId":{"type":"string","pattern":"^usr_[0-9A-HJKMNP-TV-Z]{26}$"},"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}},"responses":{"BadRequest":{"description":"Request could not be parsed or failed validation.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Unprocessable":{"description":"Semantic validation failed — the request is well-formed but references an object in the wrong state (e.g., sending to an opted-out contact).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/flows":{"post":{"tags":["Flows"],"operationId":"createFlow","summary":"Create a draft flow.","description":"Creates a flow in `draft` status — nothing enrolls until `POST /v3/flows/{id}/publish`. The DAG is validated at save (cycle detection, orphan-parent detection, node-type-specific field checks). Rate limit bucket: `write`.\n\n**CRITICAL for `email_campaign` and `sms_campaign` nodes: provide actual content.** Each such node MUST specify one of:\n  - inline `subject` + `message_body` (+ optional `preheader_text`, `from_name`, `from_email` for email)\n  - `template_id` referencing a template\n  - `campaign_id` referencing a campaign that already has content\n\nA campaign-type node with none of these creates an empty shadow campaign that the send worker will refuse to fire. Flow message nodes need finished copy: blank or stubbed subject lines and bodies are what the flow will actually send. `from_name`/`from_email`/`from_number` inherit from the workroom's app defaults when omitted, so it's fine to leave those unset.\n\n**CRITICAL: set the enrollment trigger.** `entry.segment_ids` is what makes the flow fire, and publishing is refused without it (`no_entry_segment`) because an empty entry segment would enroll the whole workroom. A flow created with an empty `entry` comes back with a `no_entry_trigger` warning, cannot be published, and shows an empty \"Enroll the audience\" panel in the dashboard. Entry is by segment membership, so a trigger expressed in words (\"when someone cancels\", \"new leads\") corresponds to a segment that has to exist and be attached here. A flow with no `entry.segment_ids` is created but never enrols anyone.\n\nThe flow is placed in the workroom that owns `entry.segment_ids`, so you normally don't pass `workroom` at all. Segments from two different workrooms in one flow are rejected. Response `warnings[]` names any ID that could not be attached (`unknown_segment_id:…`, `cross_workroom_segment_id:…`), so a flow can be created with its trigger silently unattached.\n\n`describeSegmentSchema` (`GET /v3/segments/schema`) returns the available categories. Concepts with a first-class category resolve against that category rather than a custom field; see `createSegment` for the full rule.\n\nRequires a name, an entry audience (`entry.segment_ids`) and the step definitions. Optional fields fall back to a server-side default when omitted, including the workroom — an omitted workroom resolves to the account default, and a flow created in the wrong workroom is invisible where it was expected.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlowCreate"}}}},"responses":{"201":{"description":"Draft flow created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Flow"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/Unprocessable"}}}}}}
```

## Retrieve a flow.

> Returns the flow with current \`stats\`. Use \`?expand=entry.segments\` to add \`entry.segments\` and \`entry.unenroll\_segments\` (full Segment objects for \`segment\_ids\` / \`unenroll\_segment\_ids\`); any other expand value is a 422. \`?fields=\` keeps only the listed top-level fields (plus \`id\`, \`object\`, and \`entry\` when expanding).<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Flows","description":"Multi-step automations. Enrollment is driven by segment membership. 7 node types are supported by the engine — see the Flow Engine companion doc for the full model, including the versioning and in-flight-edit caveats."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["flows:read"]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"},"OAuth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE. Use for third-party apps acting on behalf of a Gleantap user.\nAuthorization Code + PKCE is the only supported grant for interactive flows; refresh_token grant is supported and rotates on every use.\n","flows":{"authorizationCode":{"authorizationUrl":"https://api.gleantap.com/v3/oauth/authorize","tokenUrl":"https://api.gleantap.com/v3/oauth/token","refreshUrl":"https://api.gleantap.com/v3/oauth/token","scopes":{"contacts:read":"Read contact records.","contacts:write":"Create, update, delete contacts (soft delete).","contacts:delete_hard":"Hard-delete contacts (irreversible).","events:read":"Read event records.","events:write":"Record events.","segments:read":"Read segments and preview membership.","segments:write":"Create, update, delete segments.","templates:read":"Read message templates.","templates:write":"Create, update, delete templates.","campaigns:read":"Read campaigns and analytics.","campaigns:write":"Create, schedule, cancel campaigns.","flows:read":"Read flow definitions and analytics.","flows:write":"Create, edit, publish flows.","flows:publish":"Publish/unpublish flows (separately scoped for governance).","messaging:send":"Send transactional messages (SMS, email, voice).","conversations:read":"Read conversations and messages.","conversations:write":"Send messages, close/reopen conversations.","webhooks:manage":"Create, update, delete webhook endpoints.","forms:manage":"Create, update, delete, publish, duplicate forms; list submissions and rotate the submission_token.","campaigns:manage":"Create, schedule, cancel, duplicate campaigns; read recipients and analytics. (Supersedes the earlier `campaigns:read` + `campaigns:write` split; the split scopes still work.)","admin:impersonate:read":"Gleantap staff only — read any customer account named via `Gleantap-Account`. Not available through dynamic client registration.","admin:impersonate:write":"Gleantap staff only — required for any state-changing method while impersonating. Not available through dynamic client registration."}}}}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"WorkroomQuery":{"name":"workroom","in":"query","required":false,"description":"Same semantics as the `Gleantap-Workroom` header, including that a write should never be sent without a workroom the user actually chose, and that an omitted workroom scopes a read to the account default rather than spanning the account. Prefer this on GETs so proxies and caches can key on it. Accepts name, prefixed ID, raw hex, or `all`.\n","schema":{"type":"string"}},"FieldsParam":{"name":"fields","in":"query","required":false,"description":"Sparse fieldset — comma-separated list of fields to include in the response. Reduces payload size on high-volume reads. Nested field access is not supported; request the parent object.\n","schema":{"type":"string"}},"ExpandParam":{"name":"expand","in":"query","required":false,"description":"Comma-separated list of related resources to inline in the response. Without `expand`, a related field is just the ID string. With `expand`, it's the full sub-object. Up to two levels deep; max 4 expansions per request.\n","schema":{"type":"string"}}},"schemas":{"Flow":{"type":"object","required":["id","object","name","status","entry","nodes","created_at","updated_at"],"properties":{"id":{"$ref":"#/components/schemas/FlowId"},"object":{"type":"string","const":"flow"},"name":{"type":"string","maxLength":200},"description":{"type":"string","nullable":true,"maxLength":2000},"status":{"$ref":"#/components/schemas/FlowStatus"},"workroom_id":{"$ref":"#/components/schemas/WorkroomId","nullable":true,"description":"The workroom this flow lives in. Its `entry.segment_ids` must all belong to the same workroom."},"entry":{"$ref":"#/components/schemas/FlowEntry"},"nodes":{"type":"array","items":{"$ref":"#/components/schemas/FlowNode"}},"stats":{"$ref":"#/components/schemas/FlowStats"},"conversion_config":{"type":"object","nullable":true,"description":"Optional conversion goal(s) tracked per contact per run.","properties":{"conversion_ids":{"type":"array","items":{"type":"string"}},"attribution_window_days":{"type":"integer","minimum":1,"nullable":true}}},"timezone":{"$ref":"#/components/schemas/Timezone","nullable":true,"description":"Timezone used to interpret `delay` node \"Specific Date & Time\" values. Defaults to the account timezone."},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"published_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"archived_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"created_by_user_id":{"$ref":"#/components/schemas/UserId","nullable":true},"metadata":{"$ref":"#/components/schemas/Metadata"}}},"FlowId":{"type":"string","pattern":"^flw_[0-9A-HJKMNP-TV-Z]{26}$"},"FlowStatus":{"type":"string","enum":["draft","active","inactive","paused","completed","archived"],"description":"`draft` — never published. `active` — published and enrolling. `inactive` — unpublished; in-flight runs continue but no new entries. `paused` — enrollment and step execution both halted; can be resumed. `completed` — `end_date_time` passed. `archived` — soft-deleted.\n"},"WorkroomId":{"type":"string","pattern":"^wrm_[0-9a-f]{24}$"},"FlowEntry":{"type":"object","description":"Flow enrollment configuration. Enrollment is driven by segment membership — contacts entering `segment_ids` are enrolled on the next cron pass. Rich trigger vocab (`event`, `form_submission`, `appointment_booked`, etc.) is not first-class in the engine; model those via a segment that captures the trigger criteria.\n\n**Set a trigger.** Publishing requires `segment_ids`. A flow without them is created with a `no_entry_trigger` warning and publishing is refused with `no_entry_segment`: the send worker enrolls every contact in the entry segment, so a flow with none would enroll the whole workroom. `segment_criteria` and `manual_only` are not read by the worker; save criteria as a segment and use its id.\n\n**Workroom matching.** A flow lives in exactly one workroom and can only be triggered by segments from that same workroom. Compare `Segment.workroom_id` with `Flow.workroom_id`. On create you don't need to pass `workroom`: the flow is placed in the workroom that owns `segment_ids`. Segments spanning two workrooms are rejected — build one flow per workroom. On PATCH the workroom is already fixed, so a sibling-workroom segment is rejected with `422 invalid_segment_ids`.\n","properties":{"segment_ids":{"type":"array","items":{"$ref":"#/components/schemas/SegmentId"},"description":"Contacts entering ANY of these segments enter the flow. Must all belong to one workroom."},"segments":{"type":"array","items":{"$ref":"#/components/schemas/Segment"},"description":"Inlined Segment objects when `?expand=entry.segments` is requested."},"unenroll_segment_ids":{"type":"array","items":{"$ref":"#/components/schemas/SegmentId"},"description":"Contacts entering ANY of these segments are unenrolled from in-flight runs. Must belong to the flow's workroom."},"unenroll_segments":{"type":"array","items":{"$ref":"#/components/schemas/Segment"},"description":"Inlined unenroll Segment objects when `?expand=entry.segments` is requested."},"manual_only":{"type":"boolean","default":false,"description":"Marks a flow meant for `POST /v3/flows/{id}/enroll`. It does not remove the need for `segment_ids` to publish: the send worker enrolls the entry segment regardless, so use a segment that matches nobody until you enroll contacts."},"reenroll":{"type":"boolean","default":false,"description":"Allow contacts who completed the flow to enter again. Stored as the dashboard's `reenroll_status`, which is the only field the flow worker reads. The worker re-enrolls a contact who still matches the entry segment once their finished run started before today (account timezone); the old run moves to history and the new run has `reenroll: true`. Manual enroll (`POST /enroll`) follows the same rule.\n\nReads report what the worker will do: flows saved by older API versions with only `reenroll` set read `false` until re-saved.\n"},"reentry_cooldown_days":{"type":"integer","nullable":true,"deprecated":true,"description":"Not supported, and ignored. The flow worker has no re-entry cooldown. Sending a value returns a `reentry_cooldown_days_unsupported` warning and nothing is stored. To space re-entries, build the gap into the entry segment."},"end_date_time":{"$ref":"#/components/schemas/Timestamp","nullable":true,"description":"Flow auto-completes past this time. New enrollments halted; in-flight runs continue."},"segment_criteria":{"$ref":"#/components/schemas/SegmentQuery","nullable":true,"description":"Stored and echoed back only. The enrollment worker never reads it: who enters is decided by `segment_ids` alone, and it does not narrow them. To enroll on criteria, save them as a segment (`POST /v3/segments`) and put its id in `segment_ids`."}}},"SegmentId":{"type":"string","pattern":"^seg_[0-9A-HJKMNP-TV-Z]{26}$"},"Segment":{"type":"object","description":"A named collection of contacts. Either static (hand-managed list) or dynamic (query-defined). Discriminated by the `type` field, which is immutable after creation.\n","required":["id","object","type","name","size","created_at","updated_at"],"properties":{"id":{"$ref":"#/components/schemas/SegmentId"},"object":{"type":"string","const":"segment"},"workroom_id":{"$ref":"#/components/schemas/WorkroomId","nullable":true,"description":"The workroom that owns this segment. A flow can only be triggered by segments in its own workroom — compare against `Flow.workroom_id`."},"type":{"$ref":"#/components/schemas/SegmentType"},"name":{"type":"string","maxLength":200},"description":{"type":"string","nullable":true,"maxLength":2000},"query":{"$ref":"#/components/schemas/SegmentQuery","nullable":true,"description":"The segment's criteria. **Present on BOTH static and dynamic segments** — a \"static\" segment only means the engine doesn't auto-refresh membership; the criteria that defined the initial membership list is still stored and returned. When diagnosing \"why did this contact match this segment?\", read `query.segment_users` (+ `with_or_segment_users` and `exclude_segment_users`). May be `null` only on segments imported without criteria or created empty.\n"},"size":{"type":"integer","minimum":0,"description":"Current member count. Eventually consistent — up to minutes of lag on dynamic segments."},"email_count":{"type":"integer","minimum":0,"description":"Members with a non-empty, non-invalid email."},"phone_count":{"type":"integer","minimum":0,"description":"Members with a non-empty, non-invalid phone."},"last_evaluated_at":{"$ref":"#/components/schemas/Timestamp","nullable":true,"description":"When this dynamic segment was last recomputed. Null on static."},"folder_id":{"$ref":"#/components/schemas/SegmentFolderId","nullable":true,"description":"The segment folder this segment currently belongs to, or `null` if unfoldered."},"segment_summary":{"type":"string","nullable":true,"description":"AI-generated narrative summary of the segment's criteria. Populated on demand via `POST /v3/segments/{id}/summary`."},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"metadata":{"$ref":"#/components/schemas/Metadata"}}},"SegmentType":{"type":"string","enum":["static","dynamic"],"description":"`static` — hand-managed member list. Contacts are added/removed explicitly.\n`dynamic` — query-defined membership. Auto-evaluated; membership changes as contact data changes.\nImmutable after creation.\n"},"SegmentQuery":{"type":"object","description":"The segment criteria. **Present on BOTH `static` and `dynamic` segments** — \"static\" only means the engine doesn't auto-refresh membership; the criteria that defined the segment is still on the doc, and diagnostic tools (like \"why did this contact match this segment?\") MUST read it here.\n\nFull match logic:\n\n  (all `segment_users` ANDed together)\n  OR (all conditions in `with_or_segment_users[0]` ANDed)\n  OR (all conditions in `with_or_segment_users[1]` ANDed)\n  OR ...\n  MINUS contacts removed by `exclude_segment_users` (all ANDed) — self-match or shared-copy match per the account setting below\n\nHow `exclude_segment_users` matches depends on the account's `shared_contact_status` (surfaced as `shared_contacts_enabled` on `GET /segments/schema`). When shared contacts are ENABLED it is the dashboard's \"exclude shared contacts\" rule: a contact is removed when one of its linked copies in another workroom (`shared_contacts[]`) matches these conditions, NOT when the contact itself matches. When shared contacts are OFF it is a plain self-subtraction: the contact is removed when its OWN fields match. The exclusion can be any condition (attribute match, event done, tag, form filled — just the positive form of what to exclude). Either way the segment must keep at least one primary condition in `segment_users`; an exclude-only (or `with_or`-only) query is rejected. To exclude by a contact's own attributes regardless of the account setting, you can also use a negative condition in `segment_users` (e.g. `Is Not One Of`, `Has not Filled a Form`, `Does Not Contain`).\n\nConditions are stored in the exact tokens the dashboard's segment engine evaluates: friendly category names are rewritten on write (`Custom`/`attributes` → `Attributes`, `email_engagement` → `EmailCampaigns`, `salesattributes` → `sales`, …), and an absolute-date `<`/`>` on a Date field is stored as `Before`/`After` with an `MM-DD-YYYY` value. A retrieved segment therefore shows the stored (engine) form.\n\nThere is no additional `all/any/none` grouping. Express further OR via multi-value operators (`Is One Of`, `Segments` with an array).\n","properties":{"segment_users":{"type":"array","items":{"$ref":"#/components/schemas/SegmentCondition"},"description":"Base inclusion conditions. All ANDed. A contact must satisfy every one to be included via this group."},"with_or_segment_users":{"type":"array","description":"Alternate inclusion groups. Each inner array is a set of conditions that are ANDed together; the outer array is OR-joined with `segment_users` and each other inner array. Use this to build \"criteria A OR criteria B\" queries without touching the top-level `segment_users`.\n","items":{"type":"array","items":{"$ref":"#/components/schemas/SegmentCondition"}}},"exclude_segment_users":{"type":"array","items":{"$ref":"#/components/schemas/SegmentCondition"},"description":"Exclusion conditions, ANDed. How they match depends on the account's `shared_contact_status` — shared-copy match when shared contacts are ON (a contact is removed when a linked copy in another workroom, `shared_contacts[]`, matches all of them), self-match when OFF (removed when the contact's own fields match all of them). Same condition shape as `segment_users`. Cannot stand alone — `segment_users` must be non-empty. See the match logic above."}}},"SegmentCondition":{"type":"object","description":"A single condition in a dynamic segment query. Shape and operator vocabulary are documented in the Segment Query DSL companion doc — the query language supports 28 segment types (Attributes, Tags, Event Trigger, External Events, Segments, SalesAttributes, Forms, Flows, Optin, and more) and 60+ operators. This schema is intentionally loose to accommodate that surface; the server validates the concrete shape.\n","required":["segment","operator"],"additionalProperties":true,"properties":{"segment":{"type":"string","description":"Segment-type discriminator. Full inventory in the DSL doc. Common values include `Attributes`, `Tags`, `Country`, `City`, `Event Trigger`, `External Events`, `Segments`, `SalesAttributes`, `Forms`, `Flows`, `SMS Optin`, `SMS Opted Out`, `Email Topics`, `Add Date`, `Last Access`.\n"},"data":{"type":"string","description":"Field or attribute within the segment type. E.g., `first_name`, `city`, `sales.pipeline.stage`.","nullable":true},"event":{"type":"string","description":"Event name — used only when `segment` is `Event Trigger`.","nullable":true},"operator":{"type":"string","description":"Operator vocabulary. Full list in the DSL doc. Common: `=`, `!=`, `<`, `>` (numeric — on a Date field they are stored as `Before`/`After`), `Contains`, `Does Not Contain`, `Is One Of`, `Is Not One Of`, `Is Empty`, `Is Not Empty`, `Exists`, `Does Not Exist`, `Is True`, `Is False`, `InLast`, `OverDays`, `InNext`, `Before`, `After`, `IsToday`, `DayInNext`, `DayInMonth`, `Is In Segment`, `Is Not In Segment`, `Has Filled a Form`. For recurring day-of-year fields (`data_type: Day`, e.g. Birthday) use the `DayInNext`/`DayInNextXY`/`DayInMonth` family — not the absolute-date `InNext`/`=` — so \"birthday in the next N days\" recurs every year (see `describeSegmentSchema`).\n\n`Exists`/`Does Not Exist` vs `Is Not Empty`/`Is Empty`: both check for a populated value and are usually close in practice, but `Exists` is what the dashboard UI itself uses when a user says a field \"exists\" - prefer `Exists`/`Does Not Exist` for that phrasing, especially inside `with_or_segment_users`, to match what the UI would produce for the same request.\n"},"value":{"type":["string","number","boolean","array","null"],"description":"The operand. Which type applies depends on the operator: a scalar for `=` and `Contains`, an array (or comma-separated string) for `Is One Of`, a number for count comparisons, and omitted entirely for `Exists` / `Is Empty`.\n"},"value2":{"type":["string","number","null"],"description":"Secondary operand for two-parameter conditions (currently `External Events` count comparison and `SalesAttributes` pipeline-stage filter)."},"operator2":{"type":"string","description":"Secondary operator for two-parameter conditions.","nullable":true},"value2_id":{"type":"array","items":{"type":"string"},"nullable":true,"description":"Object-ID list for stage-title disambiguation on `SalesAttributes`."},"data_type":{"type":"string","enum":["String","Numeric","Date","List"],"nullable":true,"description":"Optional hint for the engine's disambiguation logic."},"dataAlias":{"type":"string","nullable":true,"description":"Human-readable alias shown in the UI. Not evaluated."}}},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"SegmentFolderId":{"type":"string","pattern":"^sfd_[0-9a-fA-F]{24}$","description":"Segment folder ID."},"Metadata":{"type":"object","description":"Free-form key/value pairs the caller stores on the resource. Not evaluated by Gleantap.\nUse for opaque identifiers, integration state, or notes you need to survive round-trips.\n","additionalProperties":true},"FlowNode":{"type":"object","required":["id","type"],"description":"A node in a flow's DAG. Polymorphic on `type` — only the fields relevant to that type should be set (unused fields ignored). See per-type notes below.\n\n**Parent/child edges:** each node has `parent_id` pointing at another node's `id`. Root nodes have `parent_id: null` and `parent_branch: \"root\"`. For `condition` nodes with `action_type: \"yes_no\"`, children set `parent_branch: \"yes\"` or `\"no\"`. For `multi_choice` conditions, children set `parent_branch: \"<matched value>\"` (slugified — spaces → underscores, lowercased). For `wait_till_true` conditions, there is no branching at all — the node re-evaluates itself until its predicate matches (see `FlowConditionMode`), and its child (if any) hangs off the ordinary linear `parent_branch: \"next\"` edge, the same as a non-condition node.\n\n**Client-supplied `id`:** you supply a string identifier per node (unique within the flow). The server uses it to resolve `parent_id` references. IDs need not survive updates — the server maps them to internal IDs at save time.\n","properties":{"id":{"type":"string","maxLength":100,"pattern":"^[a-zA-Z0-9_-]+$","description":"Client-supplied identifier, unique within this flow."},"type":{"$ref":"#/components/schemas/FlowNodeType"},"parent_id":{"type":"string","nullable":true,"description":"The `id` of this node's parent. Null for root nodes."},"parent_branch":{"type":"string","default":"root","description":"Which branch of the parent this node hangs off. `root` for the flow's entry node, `next` for a linear step, `yes`/`no` for a yes_no condition child, the slugified condition `value` for a multi_choice child, or `converge` to rejoin branches after a condition node.\n"},"action_name":{"type":"string","maxLength":200,"description":"Label shown in the UI. Optional; defaults per node type."},"campaign_id":{"$ref":"#/components/schemas/CampaignId","nullable":true,"description":"Optional. If provided, the server upgrades that existing campaign into a \"shadow\" dedicated to this flow node (adds `isAutomationCampaign=true` + `automation_id` + `automation_details_id`). The campaign is no longer a standalone after this — do not share campaign_ids across flows or reuse for one-off sends.\n"},"template_id":{"$ref":"#/components/schemas/TemplateId","nullable":true,"description":"Optional. Seeds the shadow campaign's content from a library template. For `email_campaign` the template's rendered HTML, its editor design JSON and its thumbnail are all copied onto the node, which is what makes the dashboard open it as an **HTML email** (the \"HTML Email\" toggle) rather than a plain-text one — a node given only inline `message_body` is plain text by design. An explicit `message_body` on the same node overrides the template's HTML body; `subject` is never taken from the template. Render happens at send time — merge tags interpolate per-recipient using the flow's audience data.\n"},"subject":{"type":"string","nullable":true,"description":"For `email_campaign` nodes. Email subject line. Supports merge tags (`{first_name}`, `{data.company}`). REQUIRED unless `template_id` or `campaign_id` provided.\n"},"message_body":{"type":"string","nullable":true,"description":"For both `email_campaign` (HTML body) and `sms_campaign` (plain-text body). Supports merge tags. REQUIRED unless `template_id` or `campaign_id` provided.\n`sms_campaign`: At most 10 SMS segments: 1530 plain (GSM-7) characters, or 670 if the text contains emoji or any other non-GSM character (once split, each segment holds 153 GSM / 67 unicode characters; emoji count as 2). Merge tags count as written, not expanded. A longer body (inline or from `template_id`) is rejected with 422 `validation_failed`.\n"},"preheader_text":{"type":"string","nullable":true,"description":"For `email_campaign`. Preheader shown in inbox previews after subject."},"from_name":{"type":"string","nullable":true,"description":"For `email_campaign`. Sender display name. Inherits app default when omitted."},"from_email":{"type":"string","format":"email","nullable":true,"description":"For `email_campaign`. Sender address. Inherits app default when omitted."},"from_number":{"type":"string","nullable":true,"description":"For `sms_campaign`. E.164 sender phone. Inherits app default when omitted."},"schedule":{"type":"string","enum":["Relative","Specific Date & Time"],"nullable":true,"description":"For `delay` nodes."},"delayTimeHour":{"type":"integer","nullable":true,"description":"For `delay` with `schedule: \"Relative\"`. Amount of `delayTimetype`."},"delayTimetype":{"type":"string","enum":["minutes","hours","days","weeks","months"],"nullable":true,"description":"For `delay` with `schedule: \"Relative\"`."},"selected_date":{"type":"string","format":"date","nullable":true,"description":"For `delay` with `schedule: \"Specific Date & Time\"`."},"selected_time":{"type":"string","nullable":true,"description":"For `delay` with `schedule: \"Specific Date & Time\"`. `HH:mm:ss` in the flow's timezone."},"action_type":{"$ref":"#/components/schemas/FlowConditionMode","nullable":true,"description":"For `condition` nodes."},"segment_users":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/SegmentCondition"},"description":"For `condition` with `action_type: \"yes_no\"` or `\"wait_till_true\"`. Segment DSL predicates — materialized into a hidden shadow segment for either mode (see `FlowConditionMode`) so the live cron can evaluate it.\n\n**Before constructing this**: call `describeSegmentSchema` (or `GET /v3/segments/schema`) to see available categories and copy each attribute's `condition_template` (segment/data/dataAlias/data_type) verbatim, using an `operator` from that field's `operators[]` — the same rule `createSegment`'s conditions follow. Don't guess a field key or reach for a human phrase like \"Before\" from general knowledge; the schema call is what tells you the exact tokens the engine expects.\n"},"with_or_segment_users":{"type":"array","nullable":true,"description":"For `condition` with `action_type: \"yes_no\"` or `\"wait_till_true\"` only — same OR-logic semantics as Segments' `query.with_or_segment_users`: each inner array is ANDed, and the outer array is OR-joined with `segment_users` and every other group. Materialized into the same hidden shadow segment as `segment_users` (confirmed live: `attach_condition_segment()` writes both fields identically onto the shadow segment doc, and the engine reads it from there). For `multi_choice`, use `with_or_segment_users` on the individual `FlowMultiCondition` branch instead — this top-level field is ignored for that mode.\n\nEchoed back on create/retrieve just like `segment_users` (it is persisted on the condition node itself in addition to the shadow segment), so a round-trip reflects exactly what you sent.\n","items":{"type":"array","items":{"$ref":"#/components/schemas/SegmentCondition"}}},"multi_conditions":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/FlowMultiCondition"},"description":"For `condition` with `action_type: \"multi_choice\"`."},"salesautomation_id":{"type":"string","nullable":true,"pattern":"^saut_[0-9A-HJKMNP-TV-Z]{26}$","description":"For `sales_automation` nodes. References a CRM automation created via `POST /v3/pipelines/{pipeline_id}/automations`."},"sales_automation":{"type":"object","nullable":true,"description":"For `sales_automation` nodes, instead of `salesautomation_id`: an inline CRM rule. v3 creates the rule and binds it to this node. Send `action` for one action or `actions` for several (run in order). Do not send a `trigger`; the flow decides when it runs.","properties":{"action":{"$ref":"#/components/schemas/SalesAutomationAction"},"actions":{"type":"array","items":{"$ref":"#/components/schemas/SalesAutomationAction"}}}},"webhook_url":{"type":"string","format":"uri","nullable":true,"description":"REQUIRED on `webhook` nodes — creating one without it returns 422. A webhook with no destination can never fire, and the dashboard refuses to save one for the same reason. Must be `https://` unless the account has `allow_http_webhooks: true`.\n\nGet the URL from the user. There is no sensible default and no way to infer it.\n"},"webhook_method":{"type":"string","enum":["GET","POST"],"default":"GET","description":"The flow worker only sends GET or POST; any other value is a 422 (it would silently go out as GET).","nullable":true},"webhook_payload_type":{"type":"string","enum":["json","form"],"default":"json","nullable":true},"webhook_fields":{"type":"array","nullable":true,"description":"REQUIRED on `webhook` nodes: at least one `{key, value}` pair with a non-empty `key` and `value` (`\"0\"` counts as empty). The flow worker builds the request only from such pairs and sends NOTHING when there are none — for GET (query string) as well as POST — so a node without one is a 422. Every entry must be an object with string `key` and `value`. `key` may use dot notation for nesting. Ask the user what the receiving system expects.\n","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string","description":"Supports `{placeholder}` interpolation from contact fields (e.g., `{first_name}`, `{email}`, `{data.custom_field}`)."}}}},"webhook_header_fields":{"type":"array","nullable":true,"description":"Optional request headers. Each entry needs a non-empty `key` and `value` (422 otherwise — the worker would drop it).","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}}}},"mariana_action":{"type":"object","nullable":true,"description":"Required for `mariana_action` nodes. Gives the enrolled contact something in the workroom's Mariana Tek studio. The contact is found by their Mariana id or exact email; with `if_not_found: create` a Mariana account is created from their email and name and Mariana emails them a set-password link. Each enrollment gives at most once. Amount and credit caps are the workroom's limits (default 100 and 20); values over them, or a malformed config, are rejected 422 so a saved node always runs.\n","required":["type"],"properties":{"type":{"type":"string","enum":["pack","class_credits","account_credit"]},"package_id":{"type":"string","description":"Mariana pack (package) id. `pack`: gives that pack's class credits with the pack's own expiry."},"package_name":{"type":"string","description":"Display name for the pack."},"credit_id":{"type":"string","description":"`class_credits`: Mariana credit type id."},"credit_name":{"type":"string"},"quantity":{"type":"integer","minimum":1,"description":"`class_credits`: number of credits (at most the workroom limit, default 20)."},"expiry_days":{"type":"string","description":"`class_credits`: whole days until the credits expire; empty for no expiry."},"amount":{"type":"number","description":"`account_credit`: amount to add, up to 2 decimals and the workroom limit (default 100)."},"currency":{"type":"string","description":"`account_credit`: 3-letter code, default USD."},"note":{"type":"string","maxLength":60,"description":"Shown on the credit in Mariana."},"if_not_found":{"type":"string","enum":["create","skip"],"default":"create"},"recipient":{"type":"string","enum":["contact","referrer"],"default":"contact","description":"`referrer` gives to the member who referred the contact (their `referred_by_id` in the same workroom, set by the referral intake) instead of the contact, once per enrollment. Use it in a referred friend's flow to reward the member."}}}}},"FlowNodeType":{"type":"string","enum":["email_campaign","sms_campaign","delay","condition","sales_automation","webhook","mariana_action"],"description":"The 7 node types the engine actually supports (`mariana_action` gives the contact a pack, class credits or account credit in the workroom's Mariana Tek studio). Richer vocab from the main spec (`send_message`, `tag`, `add_to_segment`, `update_contact`, `create_task`, `create_opportunity`, `wait_for_event`, `split`, `end`) is NOT implemented — express those via `sales_automation` (pointing at a CRM sub-automation) or return 501 `node_type_not_supported`. See Flow Engine companion doc §10.\n"},"CampaignId":{"type":"string","pattern":"^cam_[0-9a-f]{24}$"},"TemplateId":{"type":"string","pattern":"^tpl_[0-9a-f]{24}$"},"FlowConditionMode":{"type":"string","enum":["yes_no","multi_choice","wait_till_true"],"description":"`yes_no` — evaluates the `segment_users` predicate once, immediately, and branches: children set `parent_branch: \"yes\"` or `\"no\"` (see FlowNode's parent/child edges note). `multi_choice` — evaluates `multi_conditions` in order; the first match's slugified `value` becomes the child branch. `wait_till_true` — does NOT branch. It re-evaluates the SAME predicate, on the SAME node, on the engine's existing cron cadence, until it matches; only then does execution advance (linearly, via the ordinary `next` edge — there is no \"no\" child to fall through to). Confirmed against the dashboard/flow engine (`Cron.php`'s condition handling): while unmatched, the node is flagged `condition_repeat: true` and re-checked on the next cron pass rather than branching, and — unlike a `yes_no` match — a `wait_till_true` match never writes `operation_parent_type`/`operation_parent_id` on its action-story entry, confirming it has no yes/no children of its own.\n\n**Materialization (fixed — previously a known gap):** both `yes_no` and `wait_till_true` are evaluated by the engine against a legacy `yes_condition` field, which this API materializes from `segment_users` into a hidden shadow segment at creation time. `wait_till_true` is now included in that materialization the same way `yes_no` already was — a `wait_till_true` node created via this API is fully wired for the live cron to evaluate, not merely accepted and stored. Archiving a flow deletes these shadow segments (the node keeps `segment_users`, so duplicating the flow rebuilds them).\n"},"FlowMultiCondition":{"type":"object","required":["value"],"description":"One branch of a `multi_choice` condition. The engine evaluates each in order; the first `segment_users` match wins. Up to 6 regular branches plus one optional catch-all.\n\n**Storage.** Regular branches are stored as `Condition A`..`Condition F` in the order given, with your label kept as `name_alias` (what the dashboard shows). Children may reference a branch by your label, by `Condition A`, or by `condition_a`.\n\n**Catch-all.** Mark a branch with `is_other: true` (or `value: \"Other\"` / `\"Condition Other\"`). It is stored exactly as the dashboard stores it — `{value: \"Condition Other\", segment_users: [{segment: \"other\"}]}` — always last, and it matches every contact no earlier branch matched; any `segment_users` you give it are ignored (warning `other_branch_conditions_ignored`). Children reference it as `Other` / `condition_other`. Without a catch-all, a contact who matches no branch does not advance. More than 6 regular branches, or two catch-alls, is a 422. Reads echo `is_other: true` on the catch-all.\n","properties":{"value":{"type":"string","description":"Human-readable branch name (stored as `name_alias`; `value` becomes `Condition A`..`F`). `Other` / `Condition Other` marks the catch-all."},"is_other":{"type":"boolean","default":false,"description":"Marks this branch as the catch-all (see above)."},"name_alias":{"type":"string","description":"Display label. Set from `value` on write."},"segment_users":{"type":"array","items":{"$ref":"#/components/schemas/SegmentCondition"},"description":"Segment DSL conditions (see the Segment Query DSL doc). Ignored on the catch-all branch, which is stored with `[{segment: \"other\"}]`.\n\n**Before constructing this**: call `describeSegmentSchema` (or `GET /v3/segments/schema`) and copy each condition's `condition_template` verbatim, same as the condition node's own top-level `segment_users` — don't invent field/operator tokens here just because this is a nested branch.\n"},"with_or_segment_users":{"type":"array","description":"Alternate inclusion groups for THIS branch only, same OR-logic semantics as Segments' `query.with_or_segment_users`: each inner array is a set of conditions ANDed together, and the outer array is OR-joined with this branch's own `segment_users` and every other group here. Use this to build \"criteria A OR criteria B\" matching for one multi_choice branch without touching its `segment_users`. Optional; has no effect on the `Condition Other` fallback branch or on any other branch's matching.\n","items":{"type":"array","items":{"$ref":"#/components/schemas/SegmentCondition"}}}}},"SalesAutomationAction":{"type":"object","required":["type"],"description":"Polymorphic on `type`. 13 action types available — see `describeFlowSchema` for the full guide + params per action.\n","properties":{"type":{"type":"string","enum":["tags","remove_tags","task","add_stage","move_stage","sync_stage","remove_stage","assign","remove_assign","status","priority","add_note","enroll_in_flow"]},"tag_names":{"type":"array","items":{"type":"string"},"description":"For `tags` / `remove_tags`."},"task_name":{"type":"string","description":"For `task`."},"description":{"type":"string","description":"For `task`."},"due_at":{"$ref":"#/components/schemas/Timestamp","description":"For `task` (write only; converted to `due_in_days`)."},"due_in_days":{"type":"integer","description":"For `task`. Days from the trigger until the task is due. Default 1."},"assignee_staff_id":{"$ref":"#/components/schemas/StaffId","description":"For `task`: one responsible (\"Specific\"). Omit both assignee fields for the contact owner (\"Owner\")."},"assignee_staff_ids":{"type":"array","items":{"$ref":"#/components/schemas/StaffId"},"description":"For `task`: round-robin across these staff."},"assignee_mode":{"type":"string","readOnly":true,"enum":["Owner","Specific","Round Robin"],"description":"For `task`, read only."},"task_type":{"type":"string","description":"For `task`: task type id (`tst_…`). Defaults to the workroom's first type."},"stage_id":{"$ref":"#/components/schemas/StageId","description":"For stage actions. Required: a stage action with no valid stage is rejected (422), since the worker cannot run it."},"staff_ids":{"type":"array","items":{"$ref":"#/components/schemas/StaffId"},"description":"For `assign` / `remove_assign`. Required (non-empty)."},"distribution":{"type":"string","enum":["All","Round Robin"],"description":"For `assign`. Other values (including the dashboard's \"Round Robin By Day\", which needs a per-day roster) are stored as `All` with a warning."},"reassign":{"type":"boolean","default":false,"description":"For `assign`: true replaces a contact's existing responsible; false only fills unassigned contacts."},"value":{"type":"string","description":"For `status` / `priority`."},"note":{"type":"string","description":"For `add_note`."},"flow_id":{"type":"string","description":"For `enroll_in_flow`."},"applies_to":{"type":"string","description":"Segment scope — usually \"All\" or a segment name.","default":"All"}}},"StaffId":{"type":"string","pattern":"^usr_[0-9a-f]{24}$","description":"A staff user (from the legacy `users` collection). Used for `owner_id`, `responsible_id`, `created_by`, `assigned_to`, etc."},"StageId":{"type":"string","pattern":"^stg_[0-9a-f]{24}$"},"FlowStats":{"type":"object","description":"Run counters. `active_runs` and `completed_runs` are current state and do not move with the analytics window; `entered` and `unenrolled` are windowed.\n","properties":{"active_runs":{"type":"integer","minimum":0,"description":"Runs open right now."},"completed_runs":{"type":"integer","minimum":0,"description":"Runs finished","all time.":null},"entered":{"type":"integer","minimum":0,"description":"Contacts enrolled within the window."},"unenrolled":{"type":"integer","minimum":0,"description":"Contacts unenrolled within the window."},"entered_last_30d":{"type":"integer","minimum":0,"deprecated":true,"description":"Same value as `entered`. Kept for existing callers; the name is only accurate when the window is the default 30 days."},"unenrolled_last_30d":{"type":"integer","minimum":0,"deprecated":true,"description":"Same value as `unenrolled`."}}},"Timezone":{"type":"string","description":"IANA timezone name."},"UserId":{"type":"string","pattern":"^usr_[0-9A-HJKMNP-TV-Z]{26}$"},"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}},"responses":{"NotFound":{"description":"The resource doesn't exist or isn't visible to this caller.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/flows/{id}":{"get":{"tags":["Flows"],"operationId":"retrieveFlow","summary":"Retrieve a flow.","description":"Returns the flow with current `stats`. Use `?expand=entry.segments` to add `entry.segments` and `entry.unenroll_segments` (full Segment objects for `segment_ids` / `unenroll_segment_ids`); any other expand value is a 422. `?fields=` keeps only the listed top-level fields (plus `id`, `object`, and `entry` when expanding).\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"},{"$ref":"#/components/parameters/FieldsParam"},{"$ref":"#/components/parameters/ExpandParam"}],"responses":{"200":{"description":"The flow.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Flow"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## Update a flow definition.

> Editing \`nodes\` or \`entry\` on an \`active\` flow does NOT version-pin in-flight runs — they inherit the new definition. \`nodes\[]\` replaces the whole DAG, but a node you keep (same \`id\` and same \`type\`) keeps its internal id, its message's campaign and its condition segment, so contacts already in the flow carry on and are not re-sent steps they had. Pass nodes back with the \`id\`s a GET returns (for dashboard-built nodes that is the raw node id). Campaigns, condition segments and CRM rules belonging to removed nodes are deleted, as the dashboard does when you delete a step (send history is kept).\
> \
> \*\*Refused when it would strand contacts.\*\* If the flow has in-flight runs and the change removes or retypes a node they are positioned under, or renumbers a not-yet-reached step to at or below where they are (they would skip it), the update returns \`409 inflight\_runs\_affected\` with the details and nothing is written. Keep those nodes, wait until the runs finish, or retry with \`?force=true\` (the conflicts are then returned as \`warnings\[]\`). \`?dry\_run=true\` returns the same conflicts as warnings without persisting.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Flows","description":"Multi-step automations. Enrollment is driven by segment membership. 7 node types are supported by the engine — see the Flow Engine companion doc for the full model, including the versioning and in-flight-edit caveats."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["flows:write"]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"},"OAuth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE. Use for third-party apps acting on behalf of a Gleantap user.\nAuthorization Code + PKCE is the only supported grant for interactive flows; refresh_token grant is supported and rotates on every use.\n","flows":{"authorizationCode":{"authorizationUrl":"https://api.gleantap.com/v3/oauth/authorize","tokenUrl":"https://api.gleantap.com/v3/oauth/token","refreshUrl":"https://api.gleantap.com/v3/oauth/token","scopes":{"contacts:read":"Read contact records.","contacts:write":"Create, update, delete contacts (soft delete).","contacts:delete_hard":"Hard-delete contacts (irreversible).","events:read":"Read event records.","events:write":"Record events.","segments:read":"Read segments and preview membership.","segments:write":"Create, update, delete segments.","templates:read":"Read message templates.","templates:write":"Create, update, delete templates.","campaigns:read":"Read campaigns and analytics.","campaigns:write":"Create, schedule, cancel campaigns.","flows:read":"Read flow definitions and analytics.","flows:write":"Create, edit, publish flows.","flows:publish":"Publish/unpublish flows (separately scoped for governance).","messaging:send":"Send transactional messages (SMS, email, voice).","conversations:read":"Read conversations and messages.","conversations:write":"Send messages, close/reopen conversations.","webhooks:manage":"Create, update, delete webhook endpoints.","forms:manage":"Create, update, delete, publish, duplicate forms; list submissions and rotate the submission_token.","campaigns:manage":"Create, schedule, cancel, duplicate campaigns; read recipients and analytics. (Supersedes the earlier `campaigns:read` + `campaigns:write` split; the split scopes still work.)","admin:impersonate:read":"Gleantap staff only — read any customer account named via `Gleantap-Account`. Not available through dynamic client registration.","admin:impersonate:write":"Gleantap staff only — required for any state-changing method while impersonating. Not available through dynamic client registration."}}}}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"WorkroomQuery":{"name":"workroom","in":"query","required":false,"description":"Same semantics as the `Gleantap-Workroom` header, including that a write should never be sent without a workroom the user actually chose, and that an omitted workroom scopes a read to the account default rather than spanning the account. Prefer this on GETs so proxies and caches can key on it. Accepts name, prefixed ID, raw hex, or `all`.\n","schema":{"type":"string"}}},"schemas":{"FlowUpdate":{"type":"object","description":"Partial update. Editing `nodes` or `entry` on a live flow does NOT version-pin in-flight runs — they inherit the new definition. Deleted nodes that in-flight contacts have already passed cause the runs to stall; the response includes a `warnings[]` list flagging affected runs. Add `?dry_run=true` to preview warnings without persisting.\n","properties":{"name":{"type":"string","maxLength":200},"description":{"type":"string","nullable":true,"maxLength":2000},"entry":{"$ref":"#/components/schemas/FlowEntry"},"nodes":{"type":"array","items":{"$ref":"#/components/schemas/FlowNode"}},"conversion_config":{"type":"object","nullable":true},"timezone":{"$ref":"#/components/schemas/Timezone","nullable":true},"metadata":{"$ref":"#/components/schemas/Metadata"}}},"FlowEntry":{"type":"object","description":"Flow enrollment configuration. Enrollment is driven by segment membership — contacts entering `segment_ids` are enrolled on the next cron pass. Rich trigger vocab (`event`, `form_submission`, `appointment_booked`, etc.) is not first-class in the engine; model those via a segment that captures the trigger criteria.\n\n**Set a trigger.** Publishing requires `segment_ids`. A flow without them is created with a `no_entry_trigger` warning and publishing is refused with `no_entry_segment`: the send worker enrolls every contact in the entry segment, so a flow with none would enroll the whole workroom. `segment_criteria` and `manual_only` are not read by the worker; save criteria as a segment and use its id.\n\n**Workroom matching.** A flow lives in exactly one workroom and can only be triggered by segments from that same workroom. Compare `Segment.workroom_id` with `Flow.workroom_id`. On create you don't need to pass `workroom`: the flow is placed in the workroom that owns `segment_ids`. Segments spanning two workrooms are rejected — build one flow per workroom. On PATCH the workroom is already fixed, so a sibling-workroom segment is rejected with `422 invalid_segment_ids`.\n","properties":{"segment_ids":{"type":"array","items":{"$ref":"#/components/schemas/SegmentId"},"description":"Contacts entering ANY of these segments enter the flow. Must all belong to one workroom."},"segments":{"type":"array","items":{"$ref":"#/components/schemas/Segment"},"description":"Inlined Segment objects when `?expand=entry.segments` is requested."},"unenroll_segment_ids":{"type":"array","items":{"$ref":"#/components/schemas/SegmentId"},"description":"Contacts entering ANY of these segments are unenrolled from in-flight runs. Must belong to the flow's workroom."},"unenroll_segments":{"type":"array","items":{"$ref":"#/components/schemas/Segment"},"description":"Inlined unenroll Segment objects when `?expand=entry.segments` is requested."},"manual_only":{"type":"boolean","default":false,"description":"Marks a flow meant for `POST /v3/flows/{id}/enroll`. It does not remove the need for `segment_ids` to publish: the send worker enrolls the entry segment regardless, so use a segment that matches nobody until you enroll contacts."},"reenroll":{"type":"boolean","default":false,"description":"Allow contacts who completed the flow to enter again. Stored as the dashboard's `reenroll_status`, which is the only field the flow worker reads. The worker re-enrolls a contact who still matches the entry segment once their finished run started before today (account timezone); the old run moves to history and the new run has `reenroll: true`. Manual enroll (`POST /enroll`) follows the same rule.\n\nReads report what the worker will do: flows saved by older API versions with only `reenroll` set read `false` until re-saved.\n"},"reentry_cooldown_days":{"type":"integer","nullable":true,"deprecated":true,"description":"Not supported, and ignored. The flow worker has no re-entry cooldown. Sending a value returns a `reentry_cooldown_days_unsupported` warning and nothing is stored. To space re-entries, build the gap into the entry segment."},"end_date_time":{"$ref":"#/components/schemas/Timestamp","nullable":true,"description":"Flow auto-completes past this time. New enrollments halted; in-flight runs continue."},"segment_criteria":{"$ref":"#/components/schemas/SegmentQuery","nullable":true,"description":"Stored and echoed back only. The enrollment worker never reads it: who enters is decided by `segment_ids` alone, and it does not narrow them. To enroll on criteria, save them as a segment (`POST /v3/segments`) and put its id in `segment_ids`."}}},"SegmentId":{"type":"string","pattern":"^seg_[0-9A-HJKMNP-TV-Z]{26}$"},"Segment":{"type":"object","description":"A named collection of contacts. Either static (hand-managed list) or dynamic (query-defined). Discriminated by the `type` field, which is immutable after creation.\n","required":["id","object","type","name","size","created_at","updated_at"],"properties":{"id":{"$ref":"#/components/schemas/SegmentId"},"object":{"type":"string","const":"segment"},"workroom_id":{"$ref":"#/components/schemas/WorkroomId","nullable":true,"description":"The workroom that owns this segment. A flow can only be triggered by segments in its own workroom — compare against `Flow.workroom_id`."},"type":{"$ref":"#/components/schemas/SegmentType"},"name":{"type":"string","maxLength":200},"description":{"type":"string","nullable":true,"maxLength":2000},"query":{"$ref":"#/components/schemas/SegmentQuery","nullable":true,"description":"The segment's criteria. **Present on BOTH static and dynamic segments** — a \"static\" segment only means the engine doesn't auto-refresh membership; the criteria that defined the initial membership list is still stored and returned. When diagnosing \"why did this contact match this segment?\", read `query.segment_users` (+ `with_or_segment_users` and `exclude_segment_users`). May be `null` only on segments imported without criteria or created empty.\n"},"size":{"type":"integer","minimum":0,"description":"Current member count. Eventually consistent — up to minutes of lag on dynamic segments."},"email_count":{"type":"integer","minimum":0,"description":"Members with a non-empty, non-invalid email."},"phone_count":{"type":"integer","minimum":0,"description":"Members with a non-empty, non-invalid phone."},"last_evaluated_at":{"$ref":"#/components/schemas/Timestamp","nullable":true,"description":"When this dynamic segment was last recomputed. Null on static."},"folder_id":{"$ref":"#/components/schemas/SegmentFolderId","nullable":true,"description":"The segment folder this segment currently belongs to, or `null` if unfoldered."},"segment_summary":{"type":"string","nullable":true,"description":"AI-generated narrative summary of the segment's criteria. Populated on demand via `POST /v3/segments/{id}/summary`."},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"metadata":{"$ref":"#/components/schemas/Metadata"}}},"WorkroomId":{"type":"string","pattern":"^wrm_[0-9a-f]{24}$"},"SegmentType":{"type":"string","enum":["static","dynamic"],"description":"`static` — hand-managed member list. Contacts are added/removed explicitly.\n`dynamic` — query-defined membership. Auto-evaluated; membership changes as contact data changes.\nImmutable after creation.\n"},"SegmentQuery":{"type":"object","description":"The segment criteria. **Present on BOTH `static` and `dynamic` segments** — \"static\" only means the engine doesn't auto-refresh membership; the criteria that defined the segment is still on the doc, and diagnostic tools (like \"why did this contact match this segment?\") MUST read it here.\n\nFull match logic:\n\n  (all `segment_users` ANDed together)\n  OR (all conditions in `with_or_segment_users[0]` ANDed)\n  OR (all conditions in `with_or_segment_users[1]` ANDed)\n  OR ...\n  MINUS contacts removed by `exclude_segment_users` (all ANDed) — self-match or shared-copy match per the account setting below\n\nHow `exclude_segment_users` matches depends on the account's `shared_contact_status` (surfaced as `shared_contacts_enabled` on `GET /segments/schema`). When shared contacts are ENABLED it is the dashboard's \"exclude shared contacts\" rule: a contact is removed when one of its linked copies in another workroom (`shared_contacts[]`) matches these conditions, NOT when the contact itself matches. When shared contacts are OFF it is a plain self-subtraction: the contact is removed when its OWN fields match. The exclusion can be any condition (attribute match, event done, tag, form filled — just the positive form of what to exclude). Either way the segment must keep at least one primary condition in `segment_users`; an exclude-only (or `with_or`-only) query is rejected. To exclude by a contact's own attributes regardless of the account setting, you can also use a negative condition in `segment_users` (e.g. `Is Not One Of`, `Has not Filled a Form`, `Does Not Contain`).\n\nConditions are stored in the exact tokens the dashboard's segment engine evaluates: friendly category names are rewritten on write (`Custom`/`attributes` → `Attributes`, `email_engagement` → `EmailCampaigns`, `salesattributes` → `sales`, …), and an absolute-date `<`/`>` on a Date field is stored as `Before`/`After` with an `MM-DD-YYYY` value. A retrieved segment therefore shows the stored (engine) form.\n\nThere is no additional `all/any/none` grouping. Express further OR via multi-value operators (`Is One Of`, `Segments` with an array).\n","properties":{"segment_users":{"type":"array","items":{"$ref":"#/components/schemas/SegmentCondition"},"description":"Base inclusion conditions. All ANDed. A contact must satisfy every one to be included via this group."},"with_or_segment_users":{"type":"array","description":"Alternate inclusion groups. Each inner array is a set of conditions that are ANDed together; the outer array is OR-joined with `segment_users` and each other inner array. Use this to build \"criteria A OR criteria B\" queries without touching the top-level `segment_users`.\n","items":{"type":"array","items":{"$ref":"#/components/schemas/SegmentCondition"}}},"exclude_segment_users":{"type":"array","items":{"$ref":"#/components/schemas/SegmentCondition"},"description":"Exclusion conditions, ANDed. How they match depends on the account's `shared_contact_status` — shared-copy match when shared contacts are ON (a contact is removed when a linked copy in another workroom, `shared_contacts[]`, matches all of them), self-match when OFF (removed when the contact's own fields match all of them). Same condition shape as `segment_users`. Cannot stand alone — `segment_users` must be non-empty. See the match logic above."}}},"SegmentCondition":{"type":"object","description":"A single condition in a dynamic segment query. Shape and operator vocabulary are documented in the Segment Query DSL companion doc — the query language supports 28 segment types (Attributes, Tags, Event Trigger, External Events, Segments, SalesAttributes, Forms, Flows, Optin, and more) and 60+ operators. This schema is intentionally loose to accommodate that surface; the server validates the concrete shape.\n","required":["segment","operator"],"additionalProperties":true,"properties":{"segment":{"type":"string","description":"Segment-type discriminator. Full inventory in the DSL doc. Common values include `Attributes`, `Tags`, `Country`, `City`, `Event Trigger`, `External Events`, `Segments`, `SalesAttributes`, `Forms`, `Flows`, `SMS Optin`, `SMS Opted Out`, `Email Topics`, `Add Date`, `Last Access`.\n"},"data":{"type":"string","description":"Field or attribute within the segment type. E.g., `first_name`, `city`, `sales.pipeline.stage`.","nullable":true},"event":{"type":"string","description":"Event name — used only when `segment` is `Event Trigger`.","nullable":true},"operator":{"type":"string","description":"Operator vocabulary. Full list in the DSL doc. Common: `=`, `!=`, `<`, `>` (numeric — on a Date field they are stored as `Before`/`After`), `Contains`, `Does Not Contain`, `Is One Of`, `Is Not One Of`, `Is Empty`, `Is Not Empty`, `Exists`, `Does Not Exist`, `Is True`, `Is False`, `InLast`, `OverDays`, `InNext`, `Before`, `After`, `IsToday`, `DayInNext`, `DayInMonth`, `Is In Segment`, `Is Not In Segment`, `Has Filled a Form`. For recurring day-of-year fields (`data_type: Day`, e.g. Birthday) use the `DayInNext`/`DayInNextXY`/`DayInMonth` family — not the absolute-date `InNext`/`=` — so \"birthday in the next N days\" recurs every year (see `describeSegmentSchema`).\n\n`Exists`/`Does Not Exist` vs `Is Not Empty`/`Is Empty`: both check for a populated value and are usually close in practice, but `Exists` is what the dashboard UI itself uses when a user says a field \"exists\" - prefer `Exists`/`Does Not Exist` for that phrasing, especially inside `with_or_segment_users`, to match what the UI would produce for the same request.\n"},"value":{"type":["string","number","boolean","array","null"],"description":"The operand. Which type applies depends on the operator: a scalar for `=` and `Contains`, an array (or comma-separated string) for `Is One Of`, a number for count comparisons, and omitted entirely for `Exists` / `Is Empty`.\n"},"value2":{"type":["string","number","null"],"description":"Secondary operand for two-parameter conditions (currently `External Events` count comparison and `SalesAttributes` pipeline-stage filter)."},"operator2":{"type":"string","description":"Secondary operator for two-parameter conditions.","nullable":true},"value2_id":{"type":"array","items":{"type":"string"},"nullable":true,"description":"Object-ID list for stage-title disambiguation on `SalesAttributes`."},"data_type":{"type":"string","enum":["String","Numeric","Date","List"],"nullable":true,"description":"Optional hint for the engine's disambiguation logic."},"dataAlias":{"type":"string","nullable":true,"description":"Human-readable alias shown in the UI. Not evaluated."}}},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"SegmentFolderId":{"type":"string","pattern":"^sfd_[0-9a-fA-F]{24}$","description":"Segment folder ID."},"Metadata":{"type":"object","description":"Free-form key/value pairs the caller stores on the resource. Not evaluated by Gleantap.\nUse for opaque identifiers, integration state, or notes you need to survive round-trips.\n","additionalProperties":true},"FlowNode":{"type":"object","required":["id","type"],"description":"A node in a flow's DAG. Polymorphic on `type` — only the fields relevant to that type should be set (unused fields ignored). See per-type notes below.\n\n**Parent/child edges:** each node has `parent_id` pointing at another node's `id`. Root nodes have `parent_id: null` and `parent_branch: \"root\"`. For `condition` nodes with `action_type: \"yes_no\"`, children set `parent_branch: \"yes\"` or `\"no\"`. For `multi_choice` conditions, children set `parent_branch: \"<matched value>\"` (slugified — spaces → underscores, lowercased). For `wait_till_true` conditions, there is no branching at all — the node re-evaluates itself until its predicate matches (see `FlowConditionMode`), and its child (if any) hangs off the ordinary linear `parent_branch: \"next\"` edge, the same as a non-condition node.\n\n**Client-supplied `id`:** you supply a string identifier per node (unique within the flow). The server uses it to resolve `parent_id` references. IDs need not survive updates — the server maps them to internal IDs at save time.\n","properties":{"id":{"type":"string","maxLength":100,"pattern":"^[a-zA-Z0-9_-]+$","description":"Client-supplied identifier, unique within this flow."},"type":{"$ref":"#/components/schemas/FlowNodeType"},"parent_id":{"type":"string","nullable":true,"description":"The `id` of this node's parent. Null for root nodes."},"parent_branch":{"type":"string","default":"root","description":"Which branch of the parent this node hangs off. `root` for the flow's entry node, `next` for a linear step, `yes`/`no` for a yes_no condition child, the slugified condition `value` for a multi_choice child, or `converge` to rejoin branches after a condition node.\n"},"action_name":{"type":"string","maxLength":200,"description":"Label shown in the UI. Optional; defaults per node type."},"campaign_id":{"$ref":"#/components/schemas/CampaignId","nullable":true,"description":"Optional. If provided, the server upgrades that existing campaign into a \"shadow\" dedicated to this flow node (adds `isAutomationCampaign=true` + `automation_id` + `automation_details_id`). The campaign is no longer a standalone after this — do not share campaign_ids across flows or reuse for one-off sends.\n"},"template_id":{"$ref":"#/components/schemas/TemplateId","nullable":true,"description":"Optional. Seeds the shadow campaign's content from a library template. For `email_campaign` the template's rendered HTML, its editor design JSON and its thumbnail are all copied onto the node, which is what makes the dashboard open it as an **HTML email** (the \"HTML Email\" toggle) rather than a plain-text one — a node given only inline `message_body` is plain text by design. An explicit `message_body` on the same node overrides the template's HTML body; `subject` is never taken from the template. Render happens at send time — merge tags interpolate per-recipient using the flow's audience data.\n"},"subject":{"type":"string","nullable":true,"description":"For `email_campaign` nodes. Email subject line. Supports merge tags (`{first_name}`, `{data.company}`). REQUIRED unless `template_id` or `campaign_id` provided.\n"},"message_body":{"type":"string","nullable":true,"description":"For both `email_campaign` (HTML body) and `sms_campaign` (plain-text body). Supports merge tags. REQUIRED unless `template_id` or `campaign_id` provided.\n`sms_campaign`: At most 10 SMS segments: 1530 plain (GSM-7) characters, or 670 if the text contains emoji or any other non-GSM character (once split, each segment holds 153 GSM / 67 unicode characters; emoji count as 2). Merge tags count as written, not expanded. A longer body (inline or from `template_id`) is rejected with 422 `validation_failed`.\n"},"preheader_text":{"type":"string","nullable":true,"description":"For `email_campaign`. Preheader shown in inbox previews after subject."},"from_name":{"type":"string","nullable":true,"description":"For `email_campaign`. Sender display name. Inherits app default when omitted."},"from_email":{"type":"string","format":"email","nullable":true,"description":"For `email_campaign`. Sender address. Inherits app default when omitted."},"from_number":{"type":"string","nullable":true,"description":"For `sms_campaign`. E.164 sender phone. Inherits app default when omitted."},"schedule":{"type":"string","enum":["Relative","Specific Date & Time"],"nullable":true,"description":"For `delay` nodes."},"delayTimeHour":{"type":"integer","nullable":true,"description":"For `delay` with `schedule: \"Relative\"`. Amount of `delayTimetype`."},"delayTimetype":{"type":"string","enum":["minutes","hours","days","weeks","months"],"nullable":true,"description":"For `delay` with `schedule: \"Relative\"`."},"selected_date":{"type":"string","format":"date","nullable":true,"description":"For `delay` with `schedule: \"Specific Date & Time\"`."},"selected_time":{"type":"string","nullable":true,"description":"For `delay` with `schedule: \"Specific Date & Time\"`. `HH:mm:ss` in the flow's timezone."},"action_type":{"$ref":"#/components/schemas/FlowConditionMode","nullable":true,"description":"For `condition` nodes."},"segment_users":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/SegmentCondition"},"description":"For `condition` with `action_type: \"yes_no\"` or `\"wait_till_true\"`. Segment DSL predicates — materialized into a hidden shadow segment for either mode (see `FlowConditionMode`) so the live cron can evaluate it.\n\n**Before constructing this**: call `describeSegmentSchema` (or `GET /v3/segments/schema`) to see available categories and copy each attribute's `condition_template` (segment/data/dataAlias/data_type) verbatim, using an `operator` from that field's `operators[]` — the same rule `createSegment`'s conditions follow. Don't guess a field key or reach for a human phrase like \"Before\" from general knowledge; the schema call is what tells you the exact tokens the engine expects.\n"},"with_or_segment_users":{"type":"array","nullable":true,"description":"For `condition` with `action_type: \"yes_no\"` or `\"wait_till_true\"` only — same OR-logic semantics as Segments' `query.with_or_segment_users`: each inner array is ANDed, and the outer array is OR-joined with `segment_users` and every other group. Materialized into the same hidden shadow segment as `segment_users` (confirmed live: `attach_condition_segment()` writes both fields identically onto the shadow segment doc, and the engine reads it from there). For `multi_choice`, use `with_or_segment_users` on the individual `FlowMultiCondition` branch instead — this top-level field is ignored for that mode.\n\nEchoed back on create/retrieve just like `segment_users` (it is persisted on the condition node itself in addition to the shadow segment), so a round-trip reflects exactly what you sent.\n","items":{"type":"array","items":{"$ref":"#/components/schemas/SegmentCondition"}}},"multi_conditions":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/FlowMultiCondition"},"description":"For `condition` with `action_type: \"multi_choice\"`."},"salesautomation_id":{"type":"string","nullable":true,"pattern":"^saut_[0-9A-HJKMNP-TV-Z]{26}$","description":"For `sales_automation` nodes. References a CRM automation created via `POST /v3/pipelines/{pipeline_id}/automations`."},"sales_automation":{"type":"object","nullable":true,"description":"For `sales_automation` nodes, instead of `salesautomation_id`: an inline CRM rule. v3 creates the rule and binds it to this node. Send `action` for one action or `actions` for several (run in order). Do not send a `trigger`; the flow decides when it runs.","properties":{"action":{"$ref":"#/components/schemas/SalesAutomationAction"},"actions":{"type":"array","items":{"$ref":"#/components/schemas/SalesAutomationAction"}}}},"webhook_url":{"type":"string","format":"uri","nullable":true,"description":"REQUIRED on `webhook` nodes — creating one without it returns 422. A webhook with no destination can never fire, and the dashboard refuses to save one for the same reason. Must be `https://` unless the account has `allow_http_webhooks: true`.\n\nGet the URL from the user. There is no sensible default and no way to infer it.\n"},"webhook_method":{"type":"string","enum":["GET","POST"],"default":"GET","description":"The flow worker only sends GET or POST; any other value is a 422 (it would silently go out as GET).","nullable":true},"webhook_payload_type":{"type":"string","enum":["json","form"],"default":"json","nullable":true},"webhook_fields":{"type":"array","nullable":true,"description":"REQUIRED on `webhook` nodes: at least one `{key, value}` pair with a non-empty `key` and `value` (`\"0\"` counts as empty). The flow worker builds the request only from such pairs and sends NOTHING when there are none — for GET (query string) as well as POST — so a node without one is a 422. Every entry must be an object with string `key` and `value`. `key` may use dot notation for nesting. Ask the user what the receiving system expects.\n","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string","description":"Supports `{placeholder}` interpolation from contact fields (e.g., `{first_name}`, `{email}`, `{data.custom_field}`)."}}}},"webhook_header_fields":{"type":"array","nullable":true,"description":"Optional request headers. Each entry needs a non-empty `key` and `value` (422 otherwise — the worker would drop it).","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}}}},"mariana_action":{"type":"object","nullable":true,"description":"Required for `mariana_action` nodes. Gives the enrolled contact something in the workroom's Mariana Tek studio. The contact is found by their Mariana id or exact email; with `if_not_found: create` a Mariana account is created from their email and name and Mariana emails them a set-password link. Each enrollment gives at most once. Amount and credit caps are the workroom's limits (default 100 and 20); values over them, or a malformed config, are rejected 422 so a saved node always runs.\n","required":["type"],"properties":{"type":{"type":"string","enum":["pack","class_credits","account_credit"]},"package_id":{"type":"string","description":"Mariana pack (package) id. `pack`: gives that pack's class credits with the pack's own expiry."},"package_name":{"type":"string","description":"Display name for the pack."},"credit_id":{"type":"string","description":"`class_credits`: Mariana credit type id."},"credit_name":{"type":"string"},"quantity":{"type":"integer","minimum":1,"description":"`class_credits`: number of credits (at most the workroom limit, default 20)."},"expiry_days":{"type":"string","description":"`class_credits`: whole days until the credits expire; empty for no expiry."},"amount":{"type":"number","description":"`account_credit`: amount to add, up to 2 decimals and the workroom limit (default 100)."},"currency":{"type":"string","description":"`account_credit`: 3-letter code, default USD."},"note":{"type":"string","maxLength":60,"description":"Shown on the credit in Mariana."},"if_not_found":{"type":"string","enum":["create","skip"],"default":"create"},"recipient":{"type":"string","enum":["contact","referrer"],"default":"contact","description":"`referrer` gives to the member who referred the contact (their `referred_by_id` in the same workroom, set by the referral intake) instead of the contact, once per enrollment. Use it in a referred friend's flow to reward the member."}}}}},"FlowNodeType":{"type":"string","enum":["email_campaign","sms_campaign","delay","condition","sales_automation","webhook","mariana_action"],"description":"The 7 node types the engine actually supports (`mariana_action` gives the contact a pack, class credits or account credit in the workroom's Mariana Tek studio). Richer vocab from the main spec (`send_message`, `tag`, `add_to_segment`, `update_contact`, `create_task`, `create_opportunity`, `wait_for_event`, `split`, `end`) is NOT implemented — express those via `sales_automation` (pointing at a CRM sub-automation) or return 501 `node_type_not_supported`. See Flow Engine companion doc §10.\n"},"CampaignId":{"type":"string","pattern":"^cam_[0-9a-f]{24}$"},"TemplateId":{"type":"string","pattern":"^tpl_[0-9a-f]{24}$"},"FlowConditionMode":{"type":"string","enum":["yes_no","multi_choice","wait_till_true"],"description":"`yes_no` — evaluates the `segment_users` predicate once, immediately, and branches: children set `parent_branch: \"yes\"` or `\"no\"` (see FlowNode's parent/child edges note). `multi_choice` — evaluates `multi_conditions` in order; the first match's slugified `value` becomes the child branch. `wait_till_true` — does NOT branch. It re-evaluates the SAME predicate, on the SAME node, on the engine's existing cron cadence, until it matches; only then does execution advance (linearly, via the ordinary `next` edge — there is no \"no\" child to fall through to). Confirmed against the dashboard/flow engine (`Cron.php`'s condition handling): while unmatched, the node is flagged `condition_repeat: true` and re-checked on the next cron pass rather than branching, and — unlike a `yes_no` match — a `wait_till_true` match never writes `operation_parent_type`/`operation_parent_id` on its action-story entry, confirming it has no yes/no children of its own.\n\n**Materialization (fixed — previously a known gap):** both `yes_no` and `wait_till_true` are evaluated by the engine against a legacy `yes_condition` field, which this API materializes from `segment_users` into a hidden shadow segment at creation time. `wait_till_true` is now included in that materialization the same way `yes_no` already was — a `wait_till_true` node created via this API is fully wired for the live cron to evaluate, not merely accepted and stored. Archiving a flow deletes these shadow segments (the node keeps `segment_users`, so duplicating the flow rebuilds them).\n"},"FlowMultiCondition":{"type":"object","required":["value"],"description":"One branch of a `multi_choice` condition. The engine evaluates each in order; the first `segment_users` match wins. Up to 6 regular branches plus one optional catch-all.\n\n**Storage.** Regular branches are stored as `Condition A`..`Condition F` in the order given, with your label kept as `name_alias` (what the dashboard shows). Children may reference a branch by your label, by `Condition A`, or by `condition_a`.\n\n**Catch-all.** Mark a branch with `is_other: true` (or `value: \"Other\"` / `\"Condition Other\"`). It is stored exactly as the dashboard stores it — `{value: \"Condition Other\", segment_users: [{segment: \"other\"}]}` — always last, and it matches every contact no earlier branch matched; any `segment_users` you give it are ignored (warning `other_branch_conditions_ignored`). Children reference it as `Other` / `condition_other`. Without a catch-all, a contact who matches no branch does not advance. More than 6 regular branches, or two catch-alls, is a 422. Reads echo `is_other: true` on the catch-all.\n","properties":{"value":{"type":"string","description":"Human-readable branch name (stored as `name_alias`; `value` becomes `Condition A`..`F`). `Other` / `Condition Other` marks the catch-all."},"is_other":{"type":"boolean","default":false,"description":"Marks this branch as the catch-all (see above)."},"name_alias":{"type":"string","description":"Display label. Set from `value` on write."},"segment_users":{"type":"array","items":{"$ref":"#/components/schemas/SegmentCondition"},"description":"Segment DSL conditions (see the Segment Query DSL doc). Ignored on the catch-all branch, which is stored with `[{segment: \"other\"}]`.\n\n**Before constructing this**: call `describeSegmentSchema` (or `GET /v3/segments/schema`) and copy each condition's `condition_template` verbatim, same as the condition node's own top-level `segment_users` — don't invent field/operator tokens here just because this is a nested branch.\n"},"with_or_segment_users":{"type":"array","description":"Alternate inclusion groups for THIS branch only, same OR-logic semantics as Segments' `query.with_or_segment_users`: each inner array is a set of conditions ANDed together, and the outer array is OR-joined with this branch's own `segment_users` and every other group here. Use this to build \"criteria A OR criteria B\" matching for one multi_choice branch without touching its `segment_users`. Optional; has no effect on the `Condition Other` fallback branch or on any other branch's matching.\n","items":{"type":"array","items":{"$ref":"#/components/schemas/SegmentCondition"}}}}},"SalesAutomationAction":{"type":"object","required":["type"],"description":"Polymorphic on `type`. 13 action types available — see `describeFlowSchema` for the full guide + params per action.\n","properties":{"type":{"type":"string","enum":["tags","remove_tags","task","add_stage","move_stage","sync_stage","remove_stage","assign","remove_assign","status","priority","add_note","enroll_in_flow"]},"tag_names":{"type":"array","items":{"type":"string"},"description":"For `tags` / `remove_tags`."},"task_name":{"type":"string","description":"For `task`."},"description":{"type":"string","description":"For `task`."},"due_at":{"$ref":"#/components/schemas/Timestamp","description":"For `task` (write only; converted to `due_in_days`)."},"due_in_days":{"type":"integer","description":"For `task`. Days from the trigger until the task is due. Default 1."},"assignee_staff_id":{"$ref":"#/components/schemas/StaffId","description":"For `task`: one responsible (\"Specific\"). Omit both assignee fields for the contact owner (\"Owner\")."},"assignee_staff_ids":{"type":"array","items":{"$ref":"#/components/schemas/StaffId"},"description":"For `task`: round-robin across these staff."},"assignee_mode":{"type":"string","readOnly":true,"enum":["Owner","Specific","Round Robin"],"description":"For `task`, read only."},"task_type":{"type":"string","description":"For `task`: task type id (`tst_…`). Defaults to the workroom's first type."},"stage_id":{"$ref":"#/components/schemas/StageId","description":"For stage actions. Required: a stage action with no valid stage is rejected (422), since the worker cannot run it."},"staff_ids":{"type":"array","items":{"$ref":"#/components/schemas/StaffId"},"description":"For `assign` / `remove_assign`. Required (non-empty)."},"distribution":{"type":"string","enum":["All","Round Robin"],"description":"For `assign`. Other values (including the dashboard's \"Round Robin By Day\", which needs a per-day roster) are stored as `All` with a warning."},"reassign":{"type":"boolean","default":false,"description":"For `assign`: true replaces a contact's existing responsible; false only fills unassigned contacts."},"value":{"type":"string","description":"For `status` / `priority`."},"note":{"type":"string","description":"For `add_note`."},"flow_id":{"type":"string","description":"For `enroll_in_flow`."},"applies_to":{"type":"string","description":"Segment scope — usually \"All\" or a segment name.","default":"All"}}},"StaffId":{"type":"string","pattern":"^usr_[0-9a-f]{24}$","description":"A staff user (from the legacy `users` collection). Used for `owner_id`, `responsible_id`, `created_by`, `assigned_to`, etc."},"StageId":{"type":"string","pattern":"^stg_[0-9a-f]{24}$"},"Timezone":{"type":"string","description":"IANA timezone name."},"FlowUpdateResponse":{"type":"object","description":"The updated flow plus advisory warnings about in-flight impact.","properties":{"flow":{"$ref":"#/components/schemas/Flow"},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","enum":["in_flight_at_deleted_node","in_flight_at_modified_condition","segment_reference_changed"]},"message":{"type":"string"},"affected_run_count":{"type":"integer"}}}},"dry_run":{"type":"boolean","description":"Echoes the `?dry_run` query param. When true, nothing was persisted."}}},"Flow":{"type":"object","required":["id","object","name","status","entry","nodes","created_at","updated_at"],"properties":{"id":{"$ref":"#/components/schemas/FlowId"},"object":{"type":"string","const":"flow"},"name":{"type":"string","maxLength":200},"description":{"type":"string","nullable":true,"maxLength":2000},"status":{"$ref":"#/components/schemas/FlowStatus"},"workroom_id":{"$ref":"#/components/schemas/WorkroomId","nullable":true,"description":"The workroom this flow lives in. Its `entry.segment_ids` must all belong to the same workroom."},"entry":{"$ref":"#/components/schemas/FlowEntry"},"nodes":{"type":"array","items":{"$ref":"#/components/schemas/FlowNode"}},"stats":{"$ref":"#/components/schemas/FlowStats"},"conversion_config":{"type":"object","nullable":true,"description":"Optional conversion goal(s) tracked per contact per run.","properties":{"conversion_ids":{"type":"array","items":{"type":"string"}},"attribution_window_days":{"type":"integer","minimum":1,"nullable":true}}},"timezone":{"$ref":"#/components/schemas/Timezone","nullable":true,"description":"Timezone used to interpret `delay` node \"Specific Date & Time\" values. Defaults to the account timezone."},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"published_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"archived_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"created_by_user_id":{"$ref":"#/components/schemas/UserId","nullable":true},"metadata":{"$ref":"#/components/schemas/Metadata"}}},"FlowId":{"type":"string","pattern":"^flw_[0-9A-HJKMNP-TV-Z]{26}$"},"FlowStatus":{"type":"string","enum":["draft","active","inactive","paused","completed","archived"],"description":"`draft` — never published. `active` — published and enrolling. `inactive` — unpublished; in-flight runs continue but no new entries. `paused` — enrollment and step execution both halted; can be resumed. `completed` — `end_date_time` passed. `archived` — soft-deleted.\n"},"FlowStats":{"type":"object","description":"Run counters. `active_runs` and `completed_runs` are current state and do not move with the analytics window; `entered` and `unenrolled` are windowed.\n","properties":{"active_runs":{"type":"integer","minimum":0,"description":"Runs open right now."},"completed_runs":{"type":"integer","minimum":0,"description":"Runs finished","all time.":null},"entered":{"type":"integer","minimum":0,"description":"Contacts enrolled within the window."},"unenrolled":{"type":"integer","minimum":0,"description":"Contacts unenrolled within the window."},"entered_last_30d":{"type":"integer","minimum":0,"deprecated":true,"description":"Same value as `entered`. Kept for existing callers; the name is only accurate when the window is the default 30 days."},"unenrolled_last_30d":{"type":"integer","minimum":0,"deprecated":true,"description":"Same value as `unenrolled`."}}},"UserId":{"type":"string","pattern":"^usr_[0-9A-HJKMNP-TV-Z]{26}$"},"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}},"responses":{"BadRequest":{"description":"Request could not be parsed or failed validation.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"NotFound":{"description":"The resource doesn't exist or isn't visible to this caller.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Unprocessable":{"description":"Semantic validation failed — the request is well-formed but references an object in the wrong state (e.g., sending to an opted-out contact).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/flows/{id}":{"patch":{"tags":["Flows"],"operationId":"updateFlow","summary":"Update a flow definition.","description":"Editing `nodes` or `entry` on an `active` flow does NOT version-pin in-flight runs — they inherit the new definition. `nodes[]` replaces the whole DAG, but a node you keep (same `id` and same `type`) keeps its internal id, its message's campaign and its condition segment, so contacts already in the flow carry on and are not re-sent steps they had. Pass nodes back with the `id`s a GET returns (for dashboard-built nodes that is the raw node id). Campaigns, condition segments and CRM rules belonging to removed nodes are deleted, as the dashboard does when you delete a step (send history is kept).\n\n**Refused when it would strand contacts.** If the flow has in-flight runs and the change removes or retypes a node they are positioned under, or renumbers a not-yet-reached step to at or below where they are (they would skip it), the update returns `409 inflight_runs_affected` with the details and nothing is written. Keep those nodes, wait until the runs finish, or retry with `?force=true` (the conflicts are then returned as `warnings[]`). `?dry_run=true` returns the same conflicts as warnings without persisting.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"If true, validate + return warnings but don't persist."},{"name":"force","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Apply a `nodes[]` change even though it strands or skips in-flight contacts (see above)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlowUpdate"}}}},"responses":{"200":{"description":"Updated (or, if `?dry_run=true`, what the update would look like).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlowUpdateResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"`inflight_runs_affected` — see above.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"$ref":"#/components/responses/Unprocessable"}}}}}}
```

## Archive a flow.

> Soft delete — the flow moves to \`archived\`. Every unfinished run is completed with \`flow\_complete\_reason: "flow\_archived"\` (on the run and on the contact's flow entry). Its nodes and shadow campaigns move to \`archived\`, its flow-bound CRM rules go inactive, and its hidden condition segments are deleted — what the dashboard's status cascade and Delete do, minus anything that holds history: campaign docs, sent messages and run records are retained. Archive is terminal: publishing an archived flow returns 409 \`flow\_archived\`; duplicate it instead (the copy gets fresh shadow campaigns, condition segments and CRM rules). Repeating the call is safe. Gleantap retains archived flows for history and auditing; there is no hard delete endpoint.\
> \
> \*\*Stops journeys people are already in.\*\* Archiving halts every in-flight run immediately, so contacts partway through stop receiving the rest of the sequence. \`listFlowRuns\` reports how many runs are currently active.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Flows","description":"Multi-step automations. Enrollment is driven by segment membership. 7 node types are supported by the engine — see the Flow Engine companion doc for the full model, including the versioning and in-flight-edit caveats."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["flows:write"]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"},"OAuth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE. Use for third-party apps acting on behalf of a Gleantap user.\nAuthorization Code + PKCE is the only supported grant for interactive flows; refresh_token grant is supported and rotates on every use.\n","flows":{"authorizationCode":{"authorizationUrl":"https://api.gleantap.com/v3/oauth/authorize","tokenUrl":"https://api.gleantap.com/v3/oauth/token","refreshUrl":"https://api.gleantap.com/v3/oauth/token","scopes":{"contacts:read":"Read contact records.","contacts:write":"Create, update, delete contacts (soft delete).","contacts:delete_hard":"Hard-delete contacts (irreversible).","events:read":"Read event records.","events:write":"Record events.","segments:read":"Read segments and preview membership.","segments:write":"Create, update, delete segments.","templates:read":"Read message templates.","templates:write":"Create, update, delete templates.","campaigns:read":"Read campaigns and analytics.","campaigns:write":"Create, schedule, cancel campaigns.","flows:read":"Read flow definitions and analytics.","flows:write":"Create, edit, publish flows.","flows:publish":"Publish/unpublish flows (separately scoped for governance).","messaging:send":"Send transactional messages (SMS, email, voice).","conversations:read":"Read conversations and messages.","conversations:write":"Send messages, close/reopen conversations.","webhooks:manage":"Create, update, delete webhook endpoints.","forms:manage":"Create, update, delete, publish, duplicate forms; list submissions and rotate the submission_token.","campaigns:manage":"Create, schedule, cancel, duplicate campaigns; read recipients and analytics. (Supersedes the earlier `campaigns:read` + `campaigns:write` split; the split scopes still work.)","admin:impersonate:read":"Gleantap staff only — read any customer account named via `Gleantap-Account`. Not available through dynamic client registration.","admin:impersonate:write":"Gleantap staff only — required for any state-changing method while impersonating. Not available through dynamic client registration."}}}}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"WorkroomQuery":{"name":"workroom","in":"query","required":false,"description":"Same semantics as the `Gleantap-Workroom` header, including that a write should never be sent without a workroom the user actually chose, and that an omitted workroom scopes a read to the account default rather than spanning the account. Prefer this on GETs so proxies and caches can key on it. Accepts name, prefixed ID, raw hex, or `all`.\n","schema":{"type":"string"}}},"responses":{"NotFound":{"description":"The resource doesn't exist or isn't visible to this caller.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"schemas":{"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"paths":{"/flows/{id}":{"delete":{"tags":["Flows"],"operationId":"archiveFlow","summary":"Archive a flow.","description":"Soft delete — the flow moves to `archived`. Every unfinished run is completed with `flow_complete_reason: \"flow_archived\"` (on the run and on the contact's flow entry). Its nodes and shadow campaigns move to `archived`, its flow-bound CRM rules go inactive, and its hidden condition segments are deleted — what the dashboard's status cascade and Delete do, minus anything that holds history: campaign docs, sent messages and run records are retained. Archive is terminal: publishing an archived flow returns 409 `flow_archived`; duplicate it instead (the copy gets fresh shadow campaigns, condition segments and CRM rules). Repeating the call is safe. Gleantap retains archived flows for history and auditing; there is no hard delete endpoint.\n\n**Stops journeys people are already in.** Archiving halts every in-flight run immediately, so contacts partway through stop receiving the rest of the sequence. `listFlowRuns` reports how many runs are currently active.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"}],"responses":{"204":{"description":"Archived."},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## Publish a flow (activate).

> Transitions \`draft\` → \`active\`. Enrollment begins on the next cron tick (typically within 30 min). Publish re-validates the DAG — orphan nodes, cycles, missing campaign references, or empty entry segments return 422. An archived flow returns 409 \`flow\_archived\`.\
> \
> \*\*Goes live.\*\* Once live it keeps reaching real contacts on its own, with no further call.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Flows","description":"Multi-step automations. Enrollment is driven by segment membership. 7 node types are supported by the engine — see the Flow Engine companion doc for the full model, including the versioning and in-flight-edit caveats."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["flows:publish"]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"},"OAuth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE. Use for third-party apps acting on behalf of a Gleantap user.\nAuthorization Code + PKCE is the only supported grant for interactive flows; refresh_token grant is supported and rotates on every use.\n","flows":{"authorizationCode":{"authorizationUrl":"https://api.gleantap.com/v3/oauth/authorize","tokenUrl":"https://api.gleantap.com/v3/oauth/token","refreshUrl":"https://api.gleantap.com/v3/oauth/token","scopes":{"contacts:read":"Read contact records.","contacts:write":"Create, update, delete contacts (soft delete).","contacts:delete_hard":"Hard-delete contacts (irreversible).","events:read":"Read event records.","events:write":"Record events.","segments:read":"Read segments and preview membership.","segments:write":"Create, update, delete segments.","templates:read":"Read message templates.","templates:write":"Create, update, delete templates.","campaigns:read":"Read campaigns and analytics.","campaigns:write":"Create, schedule, cancel campaigns.","flows:read":"Read flow definitions and analytics.","flows:write":"Create, edit, publish flows.","flows:publish":"Publish/unpublish flows (separately scoped for governance).","messaging:send":"Send transactional messages (SMS, email, voice).","conversations:read":"Read conversations and messages.","conversations:write":"Send messages, close/reopen conversations.","webhooks:manage":"Create, update, delete webhook endpoints.","forms:manage":"Create, update, delete, publish, duplicate forms; list submissions and rotate the submission_token.","campaigns:manage":"Create, schedule, cancel, duplicate campaigns; read recipients and analytics. (Supersedes the earlier `campaigns:read` + `campaigns:write` split; the split scopes still work.)","admin:impersonate:read":"Gleantap staff only — read any customer account named via `Gleantap-Account`. Not available through dynamic client registration.","admin:impersonate:write":"Gleantap staff only — required for any state-changing method while impersonating. Not available through dynamic client registration."}}}}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"WorkroomQuery":{"name":"workroom","in":"query","required":false,"description":"Same semantics as the `Gleantap-Workroom` header, including that a write should never be sent without a workroom the user actually chose, and that an omitted workroom scopes a read to the account default rather than spanning the account. Prefer this on GETs so proxies and caches can key on it. Accepts name, prefixed ID, raw hex, or `all`.\n","schema":{"type":"string"}}},"schemas":{"Flow":{"type":"object","required":["id","object","name","status","entry","nodes","created_at","updated_at"],"properties":{"id":{"$ref":"#/components/schemas/FlowId"},"object":{"type":"string","const":"flow"},"name":{"type":"string","maxLength":200},"description":{"type":"string","nullable":true,"maxLength":2000},"status":{"$ref":"#/components/schemas/FlowStatus"},"workroom_id":{"$ref":"#/components/schemas/WorkroomId","nullable":true,"description":"The workroom this flow lives in. Its `entry.segment_ids` must all belong to the same workroom."},"entry":{"$ref":"#/components/schemas/FlowEntry"},"nodes":{"type":"array","items":{"$ref":"#/components/schemas/FlowNode"}},"stats":{"$ref":"#/components/schemas/FlowStats"},"conversion_config":{"type":"object","nullable":true,"description":"Optional conversion goal(s) tracked per contact per run.","properties":{"conversion_ids":{"type":"array","items":{"type":"string"}},"attribution_window_days":{"type":"integer","minimum":1,"nullable":true}}},"timezone":{"$ref":"#/components/schemas/Timezone","nullable":true,"description":"Timezone used to interpret `delay` node \"Specific Date & Time\" values. Defaults to the account timezone."},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"published_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"archived_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"created_by_user_id":{"$ref":"#/components/schemas/UserId","nullable":true},"metadata":{"$ref":"#/components/schemas/Metadata"}}},"FlowId":{"type":"string","pattern":"^flw_[0-9A-HJKMNP-TV-Z]{26}$"},"FlowStatus":{"type":"string","enum":["draft","active","inactive","paused","completed","archived"],"description":"`draft` — never published. `active` — published and enrolling. `inactive` — unpublished; in-flight runs continue but no new entries. `paused` — enrollment and step execution both halted; can be resumed. `completed` — `end_date_time` passed. `archived` — soft-deleted.\n"},"WorkroomId":{"type":"string","pattern":"^wrm_[0-9a-f]{24}$"},"FlowEntry":{"type":"object","description":"Flow enrollment configuration. Enrollment is driven by segment membership — contacts entering `segment_ids` are enrolled on the next cron pass. Rich trigger vocab (`event`, `form_submission`, `appointment_booked`, etc.) is not first-class in the engine; model those via a segment that captures the trigger criteria.\n\n**Set a trigger.** Publishing requires `segment_ids`. A flow without them is created with a `no_entry_trigger` warning and publishing is refused with `no_entry_segment`: the send worker enrolls every contact in the entry segment, so a flow with none would enroll the whole workroom. `segment_criteria` and `manual_only` are not read by the worker; save criteria as a segment and use its id.\n\n**Workroom matching.** A flow lives in exactly one workroom and can only be triggered by segments from that same workroom. Compare `Segment.workroom_id` with `Flow.workroom_id`. On create you don't need to pass `workroom`: the flow is placed in the workroom that owns `segment_ids`. Segments spanning two workrooms are rejected — build one flow per workroom. On PATCH the workroom is already fixed, so a sibling-workroom segment is rejected with `422 invalid_segment_ids`.\n","properties":{"segment_ids":{"type":"array","items":{"$ref":"#/components/schemas/SegmentId"},"description":"Contacts entering ANY of these segments enter the flow. Must all belong to one workroom."},"segments":{"type":"array","items":{"$ref":"#/components/schemas/Segment"},"description":"Inlined Segment objects when `?expand=entry.segments` is requested."},"unenroll_segment_ids":{"type":"array","items":{"$ref":"#/components/schemas/SegmentId"},"description":"Contacts entering ANY of these segments are unenrolled from in-flight runs. Must belong to the flow's workroom."},"unenroll_segments":{"type":"array","items":{"$ref":"#/components/schemas/Segment"},"description":"Inlined unenroll Segment objects when `?expand=entry.segments` is requested."},"manual_only":{"type":"boolean","default":false,"description":"Marks a flow meant for `POST /v3/flows/{id}/enroll`. It does not remove the need for `segment_ids` to publish: the send worker enrolls the entry segment regardless, so use a segment that matches nobody until you enroll contacts."},"reenroll":{"type":"boolean","default":false,"description":"Allow contacts who completed the flow to enter again. Stored as the dashboard's `reenroll_status`, which is the only field the flow worker reads. The worker re-enrolls a contact who still matches the entry segment once their finished run started before today (account timezone); the old run moves to history and the new run has `reenroll: true`. Manual enroll (`POST /enroll`) follows the same rule.\n\nReads report what the worker will do: flows saved by older API versions with only `reenroll` set read `false` until re-saved.\n"},"reentry_cooldown_days":{"type":"integer","nullable":true,"deprecated":true,"description":"Not supported, and ignored. The flow worker has no re-entry cooldown. Sending a value returns a `reentry_cooldown_days_unsupported` warning and nothing is stored. To space re-entries, build the gap into the entry segment."},"end_date_time":{"$ref":"#/components/schemas/Timestamp","nullable":true,"description":"Flow auto-completes past this time. New enrollments halted; in-flight runs continue."},"segment_criteria":{"$ref":"#/components/schemas/SegmentQuery","nullable":true,"description":"Stored and echoed back only. The enrollment worker never reads it: who enters is decided by `segment_ids` alone, and it does not narrow them. To enroll on criteria, save them as a segment (`POST /v3/segments`) and put its id in `segment_ids`."}}},"SegmentId":{"type":"string","pattern":"^seg_[0-9A-HJKMNP-TV-Z]{26}$"},"Segment":{"type":"object","description":"A named collection of contacts. Either static (hand-managed list) or dynamic (query-defined). Discriminated by the `type` field, which is immutable after creation.\n","required":["id","object","type","name","size","created_at","updated_at"],"properties":{"id":{"$ref":"#/components/schemas/SegmentId"},"object":{"type":"string","const":"segment"},"workroom_id":{"$ref":"#/components/schemas/WorkroomId","nullable":true,"description":"The workroom that owns this segment. A flow can only be triggered by segments in its own workroom — compare against `Flow.workroom_id`."},"type":{"$ref":"#/components/schemas/SegmentType"},"name":{"type":"string","maxLength":200},"description":{"type":"string","nullable":true,"maxLength":2000},"query":{"$ref":"#/components/schemas/SegmentQuery","nullable":true,"description":"The segment's criteria. **Present on BOTH static and dynamic segments** — a \"static\" segment only means the engine doesn't auto-refresh membership; the criteria that defined the initial membership list is still stored and returned. When diagnosing \"why did this contact match this segment?\", read `query.segment_users` (+ `with_or_segment_users` and `exclude_segment_users`). May be `null` only on segments imported without criteria or created empty.\n"},"size":{"type":"integer","minimum":0,"description":"Current member count. Eventually consistent — up to minutes of lag on dynamic segments."},"email_count":{"type":"integer","minimum":0,"description":"Members with a non-empty, non-invalid email."},"phone_count":{"type":"integer","minimum":0,"description":"Members with a non-empty, non-invalid phone."},"last_evaluated_at":{"$ref":"#/components/schemas/Timestamp","nullable":true,"description":"When this dynamic segment was last recomputed. Null on static."},"folder_id":{"$ref":"#/components/schemas/SegmentFolderId","nullable":true,"description":"The segment folder this segment currently belongs to, or `null` if unfoldered."},"segment_summary":{"type":"string","nullable":true,"description":"AI-generated narrative summary of the segment's criteria. Populated on demand via `POST /v3/segments/{id}/summary`."},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"metadata":{"$ref":"#/components/schemas/Metadata"}}},"SegmentType":{"type":"string","enum":["static","dynamic"],"description":"`static` — hand-managed member list. Contacts are added/removed explicitly.\n`dynamic` — query-defined membership. Auto-evaluated; membership changes as contact data changes.\nImmutable after creation.\n"},"SegmentQuery":{"type":"object","description":"The segment criteria. **Present on BOTH `static` and `dynamic` segments** — \"static\" only means the engine doesn't auto-refresh membership; the criteria that defined the segment is still on the doc, and diagnostic tools (like \"why did this contact match this segment?\") MUST read it here.\n\nFull match logic:\n\n  (all `segment_users` ANDed together)\n  OR (all conditions in `with_or_segment_users[0]` ANDed)\n  OR (all conditions in `with_or_segment_users[1]` ANDed)\n  OR ...\n  MINUS contacts removed by `exclude_segment_users` (all ANDed) — self-match or shared-copy match per the account setting below\n\nHow `exclude_segment_users` matches depends on the account's `shared_contact_status` (surfaced as `shared_contacts_enabled` on `GET /segments/schema`). When shared contacts are ENABLED it is the dashboard's \"exclude shared contacts\" rule: a contact is removed when one of its linked copies in another workroom (`shared_contacts[]`) matches these conditions, NOT when the contact itself matches. When shared contacts are OFF it is a plain self-subtraction: the contact is removed when its OWN fields match. The exclusion can be any condition (attribute match, event done, tag, form filled — just the positive form of what to exclude). Either way the segment must keep at least one primary condition in `segment_users`; an exclude-only (or `with_or`-only) query is rejected. To exclude by a contact's own attributes regardless of the account setting, you can also use a negative condition in `segment_users` (e.g. `Is Not One Of`, `Has not Filled a Form`, `Does Not Contain`).\n\nConditions are stored in the exact tokens the dashboard's segment engine evaluates: friendly category names are rewritten on write (`Custom`/`attributes` → `Attributes`, `email_engagement` → `EmailCampaigns`, `salesattributes` → `sales`, …), and an absolute-date `<`/`>` on a Date field is stored as `Before`/`After` with an `MM-DD-YYYY` value. A retrieved segment therefore shows the stored (engine) form.\n\nThere is no additional `all/any/none` grouping. Express further OR via multi-value operators (`Is One Of`, `Segments` with an array).\n","properties":{"segment_users":{"type":"array","items":{"$ref":"#/components/schemas/SegmentCondition"},"description":"Base inclusion conditions. All ANDed. A contact must satisfy every one to be included via this group."},"with_or_segment_users":{"type":"array","description":"Alternate inclusion groups. Each inner array is a set of conditions that are ANDed together; the outer array is OR-joined with `segment_users` and each other inner array. Use this to build \"criteria A OR criteria B\" queries without touching the top-level `segment_users`.\n","items":{"type":"array","items":{"$ref":"#/components/schemas/SegmentCondition"}}},"exclude_segment_users":{"type":"array","items":{"$ref":"#/components/schemas/SegmentCondition"},"description":"Exclusion conditions, ANDed. How they match depends on the account's `shared_contact_status` — shared-copy match when shared contacts are ON (a contact is removed when a linked copy in another workroom, `shared_contacts[]`, matches all of them), self-match when OFF (removed when the contact's own fields match all of them). Same condition shape as `segment_users`. Cannot stand alone — `segment_users` must be non-empty. See the match logic above."}}},"SegmentCondition":{"type":"object","description":"A single condition in a dynamic segment query. Shape and operator vocabulary are documented in the Segment Query DSL companion doc — the query language supports 28 segment types (Attributes, Tags, Event Trigger, External Events, Segments, SalesAttributes, Forms, Flows, Optin, and more) and 60+ operators. This schema is intentionally loose to accommodate that surface; the server validates the concrete shape.\n","required":["segment","operator"],"additionalProperties":true,"properties":{"segment":{"type":"string","description":"Segment-type discriminator. Full inventory in the DSL doc. Common values include `Attributes`, `Tags`, `Country`, `City`, `Event Trigger`, `External Events`, `Segments`, `SalesAttributes`, `Forms`, `Flows`, `SMS Optin`, `SMS Opted Out`, `Email Topics`, `Add Date`, `Last Access`.\n"},"data":{"type":"string","description":"Field or attribute within the segment type. E.g., `first_name`, `city`, `sales.pipeline.stage`.","nullable":true},"event":{"type":"string","description":"Event name — used only when `segment` is `Event Trigger`.","nullable":true},"operator":{"type":"string","description":"Operator vocabulary. Full list in the DSL doc. Common: `=`, `!=`, `<`, `>` (numeric — on a Date field they are stored as `Before`/`After`), `Contains`, `Does Not Contain`, `Is One Of`, `Is Not One Of`, `Is Empty`, `Is Not Empty`, `Exists`, `Does Not Exist`, `Is True`, `Is False`, `InLast`, `OverDays`, `InNext`, `Before`, `After`, `IsToday`, `DayInNext`, `DayInMonth`, `Is In Segment`, `Is Not In Segment`, `Has Filled a Form`. For recurring day-of-year fields (`data_type: Day`, e.g. Birthday) use the `DayInNext`/`DayInNextXY`/`DayInMonth` family — not the absolute-date `InNext`/`=` — so \"birthday in the next N days\" recurs every year (see `describeSegmentSchema`).\n\n`Exists`/`Does Not Exist` vs `Is Not Empty`/`Is Empty`: both check for a populated value and are usually close in practice, but `Exists` is what the dashboard UI itself uses when a user says a field \"exists\" - prefer `Exists`/`Does Not Exist` for that phrasing, especially inside `with_or_segment_users`, to match what the UI would produce for the same request.\n"},"value":{"type":["string","number","boolean","array","null"],"description":"The operand. Which type applies depends on the operator: a scalar for `=` and `Contains`, an array (or comma-separated string) for `Is One Of`, a number for count comparisons, and omitted entirely for `Exists` / `Is Empty`.\n"},"value2":{"type":["string","number","null"],"description":"Secondary operand for two-parameter conditions (currently `External Events` count comparison and `SalesAttributes` pipeline-stage filter)."},"operator2":{"type":"string","description":"Secondary operator for two-parameter conditions.","nullable":true},"value2_id":{"type":"array","items":{"type":"string"},"nullable":true,"description":"Object-ID list for stage-title disambiguation on `SalesAttributes`."},"data_type":{"type":"string","enum":["String","Numeric","Date","List"],"nullable":true,"description":"Optional hint for the engine's disambiguation logic."},"dataAlias":{"type":"string","nullable":true,"description":"Human-readable alias shown in the UI. Not evaluated."}}},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"SegmentFolderId":{"type":"string","pattern":"^sfd_[0-9a-fA-F]{24}$","description":"Segment folder ID."},"Metadata":{"type":"object","description":"Free-form key/value pairs the caller stores on the resource. Not evaluated by Gleantap.\nUse for opaque identifiers, integration state, or notes you need to survive round-trips.\n","additionalProperties":true},"FlowNode":{"type":"object","required":["id","type"],"description":"A node in a flow's DAG. Polymorphic on `type` — only the fields relevant to that type should be set (unused fields ignored). See per-type notes below.\n\n**Parent/child edges:** each node has `parent_id` pointing at another node's `id`. Root nodes have `parent_id: null` and `parent_branch: \"root\"`. For `condition` nodes with `action_type: \"yes_no\"`, children set `parent_branch: \"yes\"` or `\"no\"`. For `multi_choice` conditions, children set `parent_branch: \"<matched value>\"` (slugified — spaces → underscores, lowercased). For `wait_till_true` conditions, there is no branching at all — the node re-evaluates itself until its predicate matches (see `FlowConditionMode`), and its child (if any) hangs off the ordinary linear `parent_branch: \"next\"` edge, the same as a non-condition node.\n\n**Client-supplied `id`:** you supply a string identifier per node (unique within the flow). The server uses it to resolve `parent_id` references. IDs need not survive updates — the server maps them to internal IDs at save time.\n","properties":{"id":{"type":"string","maxLength":100,"pattern":"^[a-zA-Z0-9_-]+$","description":"Client-supplied identifier, unique within this flow."},"type":{"$ref":"#/components/schemas/FlowNodeType"},"parent_id":{"type":"string","nullable":true,"description":"The `id` of this node's parent. Null for root nodes."},"parent_branch":{"type":"string","default":"root","description":"Which branch of the parent this node hangs off. `root` for the flow's entry node, `next` for a linear step, `yes`/`no` for a yes_no condition child, the slugified condition `value` for a multi_choice child, or `converge` to rejoin branches after a condition node.\n"},"action_name":{"type":"string","maxLength":200,"description":"Label shown in the UI. Optional; defaults per node type."},"campaign_id":{"$ref":"#/components/schemas/CampaignId","nullable":true,"description":"Optional. If provided, the server upgrades that existing campaign into a \"shadow\" dedicated to this flow node (adds `isAutomationCampaign=true` + `automation_id` + `automation_details_id`). The campaign is no longer a standalone after this — do not share campaign_ids across flows or reuse for one-off sends.\n"},"template_id":{"$ref":"#/components/schemas/TemplateId","nullable":true,"description":"Optional. Seeds the shadow campaign's content from a library template. For `email_campaign` the template's rendered HTML, its editor design JSON and its thumbnail are all copied onto the node, which is what makes the dashboard open it as an **HTML email** (the \"HTML Email\" toggle) rather than a plain-text one — a node given only inline `message_body` is plain text by design. An explicit `message_body` on the same node overrides the template's HTML body; `subject` is never taken from the template. Render happens at send time — merge tags interpolate per-recipient using the flow's audience data.\n"},"subject":{"type":"string","nullable":true,"description":"For `email_campaign` nodes. Email subject line. Supports merge tags (`{first_name}`, `{data.company}`). REQUIRED unless `template_id` or `campaign_id` provided.\n"},"message_body":{"type":"string","nullable":true,"description":"For both `email_campaign` (HTML body) and `sms_campaign` (plain-text body). Supports merge tags. REQUIRED unless `template_id` or `campaign_id` provided.\n`sms_campaign`: At most 10 SMS segments: 1530 plain (GSM-7) characters, or 670 if the text contains emoji or any other non-GSM character (once split, each segment holds 153 GSM / 67 unicode characters; emoji count as 2). Merge tags count as written, not expanded. A longer body (inline or from `template_id`) is rejected with 422 `validation_failed`.\n"},"preheader_text":{"type":"string","nullable":true,"description":"For `email_campaign`. Preheader shown in inbox previews after subject."},"from_name":{"type":"string","nullable":true,"description":"For `email_campaign`. Sender display name. Inherits app default when omitted."},"from_email":{"type":"string","format":"email","nullable":true,"description":"For `email_campaign`. Sender address. Inherits app default when omitted."},"from_number":{"type":"string","nullable":true,"description":"For `sms_campaign`. E.164 sender phone. Inherits app default when omitted."},"schedule":{"type":"string","enum":["Relative","Specific Date & Time"],"nullable":true,"description":"For `delay` nodes."},"delayTimeHour":{"type":"integer","nullable":true,"description":"For `delay` with `schedule: \"Relative\"`. Amount of `delayTimetype`."},"delayTimetype":{"type":"string","enum":["minutes","hours","days","weeks","months"],"nullable":true,"description":"For `delay` with `schedule: \"Relative\"`."},"selected_date":{"type":"string","format":"date","nullable":true,"description":"For `delay` with `schedule: \"Specific Date & Time\"`."},"selected_time":{"type":"string","nullable":true,"description":"For `delay` with `schedule: \"Specific Date & Time\"`. `HH:mm:ss` in the flow's timezone."},"action_type":{"$ref":"#/components/schemas/FlowConditionMode","nullable":true,"description":"For `condition` nodes."},"segment_users":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/SegmentCondition"},"description":"For `condition` with `action_type: \"yes_no\"` or `\"wait_till_true\"`. Segment DSL predicates — materialized into a hidden shadow segment for either mode (see `FlowConditionMode`) so the live cron can evaluate it.\n\n**Before constructing this**: call `describeSegmentSchema` (or `GET /v3/segments/schema`) to see available categories and copy each attribute's `condition_template` (segment/data/dataAlias/data_type) verbatim, using an `operator` from that field's `operators[]` — the same rule `createSegment`'s conditions follow. Don't guess a field key or reach for a human phrase like \"Before\" from general knowledge; the schema call is what tells you the exact tokens the engine expects.\n"},"with_or_segment_users":{"type":"array","nullable":true,"description":"For `condition` with `action_type: \"yes_no\"` or `\"wait_till_true\"` only — same OR-logic semantics as Segments' `query.with_or_segment_users`: each inner array is ANDed, and the outer array is OR-joined with `segment_users` and every other group. Materialized into the same hidden shadow segment as `segment_users` (confirmed live: `attach_condition_segment()` writes both fields identically onto the shadow segment doc, and the engine reads it from there). For `multi_choice`, use `with_or_segment_users` on the individual `FlowMultiCondition` branch instead — this top-level field is ignored for that mode.\n\nEchoed back on create/retrieve just like `segment_users` (it is persisted on the condition node itself in addition to the shadow segment), so a round-trip reflects exactly what you sent.\n","items":{"type":"array","items":{"$ref":"#/components/schemas/SegmentCondition"}}},"multi_conditions":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/FlowMultiCondition"},"description":"For `condition` with `action_type: \"multi_choice\"`."},"salesautomation_id":{"type":"string","nullable":true,"pattern":"^saut_[0-9A-HJKMNP-TV-Z]{26}$","description":"For `sales_automation` nodes. References a CRM automation created via `POST /v3/pipelines/{pipeline_id}/automations`."},"sales_automation":{"type":"object","nullable":true,"description":"For `sales_automation` nodes, instead of `salesautomation_id`: an inline CRM rule. v3 creates the rule and binds it to this node. Send `action` for one action or `actions` for several (run in order). Do not send a `trigger`; the flow decides when it runs.","properties":{"action":{"$ref":"#/components/schemas/SalesAutomationAction"},"actions":{"type":"array","items":{"$ref":"#/components/schemas/SalesAutomationAction"}}}},"webhook_url":{"type":"string","format":"uri","nullable":true,"description":"REQUIRED on `webhook` nodes — creating one without it returns 422. A webhook with no destination can never fire, and the dashboard refuses to save one for the same reason. Must be `https://` unless the account has `allow_http_webhooks: true`.\n\nGet the URL from the user. There is no sensible default and no way to infer it.\n"},"webhook_method":{"type":"string","enum":["GET","POST"],"default":"GET","description":"The flow worker only sends GET or POST; any other value is a 422 (it would silently go out as GET).","nullable":true},"webhook_payload_type":{"type":"string","enum":["json","form"],"default":"json","nullable":true},"webhook_fields":{"type":"array","nullable":true,"description":"REQUIRED on `webhook` nodes: at least one `{key, value}` pair with a non-empty `key` and `value` (`\"0\"` counts as empty). The flow worker builds the request only from such pairs and sends NOTHING when there are none — for GET (query string) as well as POST — so a node without one is a 422. Every entry must be an object with string `key` and `value`. `key` may use dot notation for nesting. Ask the user what the receiving system expects.\n","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string","description":"Supports `{placeholder}` interpolation from contact fields (e.g., `{first_name}`, `{email}`, `{data.custom_field}`)."}}}},"webhook_header_fields":{"type":"array","nullable":true,"description":"Optional request headers. Each entry needs a non-empty `key` and `value` (422 otherwise — the worker would drop it).","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}}}},"mariana_action":{"type":"object","nullable":true,"description":"Required for `mariana_action` nodes. Gives the enrolled contact something in the workroom's Mariana Tek studio. The contact is found by their Mariana id or exact email; with `if_not_found: create` a Mariana account is created from their email and name and Mariana emails them a set-password link. Each enrollment gives at most once. Amount and credit caps are the workroom's limits (default 100 and 20); values over them, or a malformed config, are rejected 422 so a saved node always runs.\n","required":["type"],"properties":{"type":{"type":"string","enum":["pack","class_credits","account_credit"]},"package_id":{"type":"string","description":"Mariana pack (package) id. `pack`: gives that pack's class credits with the pack's own expiry."},"package_name":{"type":"string","description":"Display name for the pack."},"credit_id":{"type":"string","description":"`class_credits`: Mariana credit type id."},"credit_name":{"type":"string"},"quantity":{"type":"integer","minimum":1,"description":"`class_credits`: number of credits (at most the workroom limit, default 20)."},"expiry_days":{"type":"string","description":"`class_credits`: whole days until the credits expire; empty for no expiry."},"amount":{"type":"number","description":"`account_credit`: amount to add, up to 2 decimals and the workroom limit (default 100)."},"currency":{"type":"string","description":"`account_credit`: 3-letter code, default USD."},"note":{"type":"string","maxLength":60,"description":"Shown on the credit in Mariana."},"if_not_found":{"type":"string","enum":["create","skip"],"default":"create"},"recipient":{"type":"string","enum":["contact","referrer"],"default":"contact","description":"`referrer` gives to the member who referred the contact (their `referred_by_id` in the same workroom, set by the referral intake) instead of the contact, once per enrollment. Use it in a referred friend's flow to reward the member."}}}}},"FlowNodeType":{"type":"string","enum":["email_campaign","sms_campaign","delay","condition","sales_automation","webhook","mariana_action"],"description":"The 7 node types the engine actually supports (`mariana_action` gives the contact a pack, class credits or account credit in the workroom's Mariana Tek studio). Richer vocab from the main spec (`send_message`, `tag`, `add_to_segment`, `update_contact`, `create_task`, `create_opportunity`, `wait_for_event`, `split`, `end`) is NOT implemented — express those via `sales_automation` (pointing at a CRM sub-automation) or return 501 `node_type_not_supported`. See Flow Engine companion doc §10.\n"},"CampaignId":{"type":"string","pattern":"^cam_[0-9a-f]{24}$"},"TemplateId":{"type":"string","pattern":"^tpl_[0-9a-f]{24}$"},"FlowConditionMode":{"type":"string","enum":["yes_no","multi_choice","wait_till_true"],"description":"`yes_no` — evaluates the `segment_users` predicate once, immediately, and branches: children set `parent_branch: \"yes\"` or `\"no\"` (see FlowNode's parent/child edges note). `multi_choice` — evaluates `multi_conditions` in order; the first match's slugified `value` becomes the child branch. `wait_till_true` — does NOT branch. It re-evaluates the SAME predicate, on the SAME node, on the engine's existing cron cadence, until it matches; only then does execution advance (linearly, via the ordinary `next` edge — there is no \"no\" child to fall through to). Confirmed against the dashboard/flow engine (`Cron.php`'s condition handling): while unmatched, the node is flagged `condition_repeat: true` and re-checked on the next cron pass rather than branching, and — unlike a `yes_no` match — a `wait_till_true` match never writes `operation_parent_type`/`operation_parent_id` on its action-story entry, confirming it has no yes/no children of its own.\n\n**Materialization (fixed — previously a known gap):** both `yes_no` and `wait_till_true` are evaluated by the engine against a legacy `yes_condition` field, which this API materializes from `segment_users` into a hidden shadow segment at creation time. `wait_till_true` is now included in that materialization the same way `yes_no` already was — a `wait_till_true` node created via this API is fully wired for the live cron to evaluate, not merely accepted and stored. Archiving a flow deletes these shadow segments (the node keeps `segment_users`, so duplicating the flow rebuilds them).\n"},"FlowMultiCondition":{"type":"object","required":["value"],"description":"One branch of a `multi_choice` condition. The engine evaluates each in order; the first `segment_users` match wins. Up to 6 regular branches plus one optional catch-all.\n\n**Storage.** Regular branches are stored as `Condition A`..`Condition F` in the order given, with your label kept as `name_alias` (what the dashboard shows). Children may reference a branch by your label, by `Condition A`, or by `condition_a`.\n\n**Catch-all.** Mark a branch with `is_other: true` (or `value: \"Other\"` / `\"Condition Other\"`). It is stored exactly as the dashboard stores it — `{value: \"Condition Other\", segment_users: [{segment: \"other\"}]}` — always last, and it matches every contact no earlier branch matched; any `segment_users` you give it are ignored (warning `other_branch_conditions_ignored`). Children reference it as `Other` / `condition_other`. Without a catch-all, a contact who matches no branch does not advance. More than 6 regular branches, or two catch-alls, is a 422. Reads echo `is_other: true` on the catch-all.\n","properties":{"value":{"type":"string","description":"Human-readable branch name (stored as `name_alias`; `value` becomes `Condition A`..`F`). `Other` / `Condition Other` marks the catch-all."},"is_other":{"type":"boolean","default":false,"description":"Marks this branch as the catch-all (see above)."},"name_alias":{"type":"string","description":"Display label. Set from `value` on write."},"segment_users":{"type":"array","items":{"$ref":"#/components/schemas/SegmentCondition"},"description":"Segment DSL conditions (see the Segment Query DSL doc). Ignored on the catch-all branch, which is stored with `[{segment: \"other\"}]`.\n\n**Before constructing this**: call `describeSegmentSchema` (or `GET /v3/segments/schema`) and copy each condition's `condition_template` verbatim, same as the condition node's own top-level `segment_users` — don't invent field/operator tokens here just because this is a nested branch.\n"},"with_or_segment_users":{"type":"array","description":"Alternate inclusion groups for THIS branch only, same OR-logic semantics as Segments' `query.with_or_segment_users`: each inner array is a set of conditions ANDed together, and the outer array is OR-joined with this branch's own `segment_users` and every other group here. Use this to build \"criteria A OR criteria B\" matching for one multi_choice branch without touching its `segment_users`. Optional; has no effect on the `Condition Other` fallback branch or on any other branch's matching.\n","items":{"type":"array","items":{"$ref":"#/components/schemas/SegmentCondition"}}}}},"SalesAutomationAction":{"type":"object","required":["type"],"description":"Polymorphic on `type`. 13 action types available — see `describeFlowSchema` for the full guide + params per action.\n","properties":{"type":{"type":"string","enum":["tags","remove_tags","task","add_stage","move_stage","sync_stage","remove_stage","assign","remove_assign","status","priority","add_note","enroll_in_flow"]},"tag_names":{"type":"array","items":{"type":"string"},"description":"For `tags` / `remove_tags`."},"task_name":{"type":"string","description":"For `task`."},"description":{"type":"string","description":"For `task`."},"due_at":{"$ref":"#/components/schemas/Timestamp","description":"For `task` (write only; converted to `due_in_days`)."},"due_in_days":{"type":"integer","description":"For `task`. Days from the trigger until the task is due. Default 1."},"assignee_staff_id":{"$ref":"#/components/schemas/StaffId","description":"For `task`: one responsible (\"Specific\"). Omit both assignee fields for the contact owner (\"Owner\")."},"assignee_staff_ids":{"type":"array","items":{"$ref":"#/components/schemas/StaffId"},"description":"For `task`: round-robin across these staff."},"assignee_mode":{"type":"string","readOnly":true,"enum":["Owner","Specific","Round Robin"],"description":"For `task`, read only."},"task_type":{"type":"string","description":"For `task`: task type id (`tst_…`). Defaults to the workroom's first type."},"stage_id":{"$ref":"#/components/schemas/StageId","description":"For stage actions. Required: a stage action with no valid stage is rejected (422), since the worker cannot run it."},"staff_ids":{"type":"array","items":{"$ref":"#/components/schemas/StaffId"},"description":"For `assign` / `remove_assign`. Required (non-empty)."},"distribution":{"type":"string","enum":["All","Round Robin"],"description":"For `assign`. Other values (including the dashboard's \"Round Robin By Day\", which needs a per-day roster) are stored as `All` with a warning."},"reassign":{"type":"boolean","default":false,"description":"For `assign`: true replaces a contact's existing responsible; false only fills unassigned contacts."},"value":{"type":"string","description":"For `status` / `priority`."},"note":{"type":"string","description":"For `add_note`."},"flow_id":{"type":"string","description":"For `enroll_in_flow`."},"applies_to":{"type":"string","description":"Segment scope — usually \"All\" or a segment name.","default":"All"}}},"StaffId":{"type":"string","pattern":"^usr_[0-9a-f]{24}$","description":"A staff user (from the legacy `users` collection). Used for `owner_id`, `responsible_id`, `created_by`, `assigned_to`, etc."},"StageId":{"type":"string","pattern":"^stg_[0-9a-f]{24}$"},"FlowStats":{"type":"object","description":"Run counters. `active_runs` and `completed_runs` are current state and do not move with the analytics window; `entered` and `unenrolled` are windowed.\n","properties":{"active_runs":{"type":"integer","minimum":0,"description":"Runs open right now."},"completed_runs":{"type":"integer","minimum":0,"description":"Runs finished","all time.":null},"entered":{"type":"integer","minimum":0,"description":"Contacts enrolled within the window."},"unenrolled":{"type":"integer","minimum":0,"description":"Contacts unenrolled within the window."},"entered_last_30d":{"type":"integer","minimum":0,"deprecated":true,"description":"Same value as `entered`. Kept for existing callers; the name is only accurate when the window is the default 30 days."},"unenrolled_last_30d":{"type":"integer","minimum":0,"deprecated":true,"description":"Same value as `unenrolled`."}}},"Timezone":{"type":"string","description":"IANA timezone name."},"UserId":{"type":"string","pattern":"^usr_[0-9A-HJKMNP-TV-Z]{26}$"},"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}},"responses":{"NotFound":{"description":"The resource doesn't exist or isn't visible to this caller.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Conflict":{"description":"Idempotency conflict, version conflict (`If-Match`), or state conflict.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Unprocessable":{"description":"Semantic validation failed — the request is well-formed but references an object in the wrong state (e.g., sending to an opted-out contact).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/flows/{id}/publish":{"post":{"tags":["Flows"],"operationId":"publishFlow","summary":"Publish a flow (activate).","description":"Transitions `draft` → `active`. Enrollment begins on the next cron tick (typically within 30 min). Publish re-validates the DAG — orphan nodes, cycles, missing campaign references, or empty entry segments return 422. An archived flow returns 409 `flow_archived`.\n\n**Goes live.** Once live it keeps reaching real contacts on its own, with no further call.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"}],"responses":{"200":{"description":"Published.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Flow"}}}},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}}}}}
```

## Unpublish a flow.

> Transitions \`active\` → \`inactive\`. Stops new enrollments; in-flight runs continue to completion. To stop in-flight runs too, use \`DELETE /v3/flows/{id}\` (archive).<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Flows","description":"Multi-step automations. Enrollment is driven by segment membership. 7 node types are supported by the engine — see the Flow Engine companion doc for the full model, including the versioning and in-flight-edit caveats."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["flows:publish"]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"},"OAuth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE. Use for third-party apps acting on behalf of a Gleantap user.\nAuthorization Code + PKCE is the only supported grant for interactive flows; refresh_token grant is supported and rotates on every use.\n","flows":{"authorizationCode":{"authorizationUrl":"https://api.gleantap.com/v3/oauth/authorize","tokenUrl":"https://api.gleantap.com/v3/oauth/token","refreshUrl":"https://api.gleantap.com/v3/oauth/token","scopes":{"contacts:read":"Read contact records.","contacts:write":"Create, update, delete contacts (soft delete).","contacts:delete_hard":"Hard-delete contacts (irreversible).","events:read":"Read event records.","events:write":"Record events.","segments:read":"Read segments and preview membership.","segments:write":"Create, update, delete segments.","templates:read":"Read message templates.","templates:write":"Create, update, delete templates.","campaigns:read":"Read campaigns and analytics.","campaigns:write":"Create, schedule, cancel campaigns.","flows:read":"Read flow definitions and analytics.","flows:write":"Create, edit, publish flows.","flows:publish":"Publish/unpublish flows (separately scoped for governance).","messaging:send":"Send transactional messages (SMS, email, voice).","conversations:read":"Read conversations and messages.","conversations:write":"Send messages, close/reopen conversations.","webhooks:manage":"Create, update, delete webhook endpoints.","forms:manage":"Create, update, delete, publish, duplicate forms; list submissions and rotate the submission_token.","campaigns:manage":"Create, schedule, cancel, duplicate campaigns; read recipients and analytics. (Supersedes the earlier `campaigns:read` + `campaigns:write` split; the split scopes still work.)","admin:impersonate:read":"Gleantap staff only — read any customer account named via `Gleantap-Account`. Not available through dynamic client registration.","admin:impersonate:write":"Gleantap staff only — required for any state-changing method while impersonating. Not available through dynamic client registration."}}}}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"WorkroomQuery":{"name":"workroom","in":"query","required":false,"description":"Same semantics as the `Gleantap-Workroom` header, including that a write should never be sent without a workroom the user actually chose, and that an omitted workroom scopes a read to the account default rather than spanning the account. Prefer this on GETs so proxies and caches can key on it. Accepts name, prefixed ID, raw hex, or `all`.\n","schema":{"type":"string"}}},"schemas":{"Flow":{"type":"object","required":["id","object","name","status","entry","nodes","created_at","updated_at"],"properties":{"id":{"$ref":"#/components/schemas/FlowId"},"object":{"type":"string","const":"flow"},"name":{"type":"string","maxLength":200},"description":{"type":"string","nullable":true,"maxLength":2000},"status":{"$ref":"#/components/schemas/FlowStatus"},"workroom_id":{"$ref":"#/components/schemas/WorkroomId","nullable":true,"description":"The workroom this flow lives in. Its `entry.segment_ids` must all belong to the same workroom."},"entry":{"$ref":"#/components/schemas/FlowEntry"},"nodes":{"type":"array","items":{"$ref":"#/components/schemas/FlowNode"}},"stats":{"$ref":"#/components/schemas/FlowStats"},"conversion_config":{"type":"object","nullable":true,"description":"Optional conversion goal(s) tracked per contact per run.","properties":{"conversion_ids":{"type":"array","items":{"type":"string"}},"attribution_window_days":{"type":"integer","minimum":1,"nullable":true}}},"timezone":{"$ref":"#/components/schemas/Timezone","nullable":true,"description":"Timezone used to interpret `delay` node \"Specific Date & Time\" values. Defaults to the account timezone."},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"published_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"archived_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"created_by_user_id":{"$ref":"#/components/schemas/UserId","nullable":true},"metadata":{"$ref":"#/components/schemas/Metadata"}}},"FlowId":{"type":"string","pattern":"^flw_[0-9A-HJKMNP-TV-Z]{26}$"},"FlowStatus":{"type":"string","enum":["draft","active","inactive","paused","completed","archived"],"description":"`draft` — never published. `active` — published and enrolling. `inactive` — unpublished; in-flight runs continue but no new entries. `paused` — enrollment and step execution both halted; can be resumed. `completed` — `end_date_time` passed. `archived` — soft-deleted.\n"},"WorkroomId":{"type":"string","pattern":"^wrm_[0-9a-f]{24}$"},"FlowEntry":{"type":"object","description":"Flow enrollment configuration. Enrollment is driven by segment membership — contacts entering `segment_ids` are enrolled on the next cron pass. Rich trigger vocab (`event`, `form_submission`, `appointment_booked`, etc.) is not first-class in the engine; model those via a segment that captures the trigger criteria.\n\n**Set a trigger.** Publishing requires `segment_ids`. A flow without them is created with a `no_entry_trigger` warning and publishing is refused with `no_entry_segment`: the send worker enrolls every contact in the entry segment, so a flow with none would enroll the whole workroom. `segment_criteria` and `manual_only` are not read by the worker; save criteria as a segment and use its id.\n\n**Workroom matching.** A flow lives in exactly one workroom and can only be triggered by segments from that same workroom. Compare `Segment.workroom_id` with `Flow.workroom_id`. On create you don't need to pass `workroom`: the flow is placed in the workroom that owns `segment_ids`. Segments spanning two workrooms are rejected — build one flow per workroom. On PATCH the workroom is already fixed, so a sibling-workroom segment is rejected with `422 invalid_segment_ids`.\n","properties":{"segment_ids":{"type":"array","items":{"$ref":"#/components/schemas/SegmentId"},"description":"Contacts entering ANY of these segments enter the flow. Must all belong to one workroom."},"segments":{"type":"array","items":{"$ref":"#/components/schemas/Segment"},"description":"Inlined Segment objects when `?expand=entry.segments` is requested."},"unenroll_segment_ids":{"type":"array","items":{"$ref":"#/components/schemas/SegmentId"},"description":"Contacts entering ANY of these segments are unenrolled from in-flight runs. Must belong to the flow's workroom."},"unenroll_segments":{"type":"array","items":{"$ref":"#/components/schemas/Segment"},"description":"Inlined unenroll Segment objects when `?expand=entry.segments` is requested."},"manual_only":{"type":"boolean","default":false,"description":"Marks a flow meant for `POST /v3/flows/{id}/enroll`. It does not remove the need for `segment_ids` to publish: the send worker enrolls the entry segment regardless, so use a segment that matches nobody until you enroll contacts."},"reenroll":{"type":"boolean","default":false,"description":"Allow contacts who completed the flow to enter again. Stored as the dashboard's `reenroll_status`, which is the only field the flow worker reads. The worker re-enrolls a contact who still matches the entry segment once their finished run started before today (account timezone); the old run moves to history and the new run has `reenroll: true`. Manual enroll (`POST /enroll`) follows the same rule.\n\nReads report what the worker will do: flows saved by older API versions with only `reenroll` set read `false` until re-saved.\n"},"reentry_cooldown_days":{"type":"integer","nullable":true,"deprecated":true,"description":"Not supported, and ignored. The flow worker has no re-entry cooldown. Sending a value returns a `reentry_cooldown_days_unsupported` warning and nothing is stored. To space re-entries, build the gap into the entry segment."},"end_date_time":{"$ref":"#/components/schemas/Timestamp","nullable":true,"description":"Flow auto-completes past this time. New enrollments halted; in-flight runs continue."},"segment_criteria":{"$ref":"#/components/schemas/SegmentQuery","nullable":true,"description":"Stored and echoed back only. The enrollment worker never reads it: who enters is decided by `segment_ids` alone, and it does not narrow them. To enroll on criteria, save them as a segment (`POST /v3/segments`) and put its id in `segment_ids`."}}},"SegmentId":{"type":"string","pattern":"^seg_[0-9A-HJKMNP-TV-Z]{26}$"},"Segment":{"type":"object","description":"A named collection of contacts. Either static (hand-managed list) or dynamic (query-defined). Discriminated by the `type` field, which is immutable after creation.\n","required":["id","object","type","name","size","created_at","updated_at"],"properties":{"id":{"$ref":"#/components/schemas/SegmentId"},"object":{"type":"string","const":"segment"},"workroom_id":{"$ref":"#/components/schemas/WorkroomId","nullable":true,"description":"The workroom that owns this segment. A flow can only be triggered by segments in its own workroom — compare against `Flow.workroom_id`."},"type":{"$ref":"#/components/schemas/SegmentType"},"name":{"type":"string","maxLength":200},"description":{"type":"string","nullable":true,"maxLength":2000},"query":{"$ref":"#/components/schemas/SegmentQuery","nullable":true,"description":"The segment's criteria. **Present on BOTH static and dynamic segments** — a \"static\" segment only means the engine doesn't auto-refresh membership; the criteria that defined the initial membership list is still stored and returned. When diagnosing \"why did this contact match this segment?\", read `query.segment_users` (+ `with_or_segment_users` and `exclude_segment_users`). May be `null` only on segments imported without criteria or created empty.\n"},"size":{"type":"integer","minimum":0,"description":"Current member count. Eventually consistent — up to minutes of lag on dynamic segments."},"email_count":{"type":"integer","minimum":0,"description":"Members with a non-empty, non-invalid email."},"phone_count":{"type":"integer","minimum":0,"description":"Members with a non-empty, non-invalid phone."},"last_evaluated_at":{"$ref":"#/components/schemas/Timestamp","nullable":true,"description":"When this dynamic segment was last recomputed. Null on static."},"folder_id":{"$ref":"#/components/schemas/SegmentFolderId","nullable":true,"description":"The segment folder this segment currently belongs to, or `null` if unfoldered."},"segment_summary":{"type":"string","nullable":true,"description":"AI-generated narrative summary of the segment's criteria. Populated on demand via `POST /v3/segments/{id}/summary`."},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"metadata":{"$ref":"#/components/schemas/Metadata"}}},"SegmentType":{"type":"string","enum":["static","dynamic"],"description":"`static` — hand-managed member list. Contacts are added/removed explicitly.\n`dynamic` — query-defined membership. Auto-evaluated; membership changes as contact data changes.\nImmutable after creation.\n"},"SegmentQuery":{"type":"object","description":"The segment criteria. **Present on BOTH `static` and `dynamic` segments** — \"static\" only means the engine doesn't auto-refresh membership; the criteria that defined the segment is still on the doc, and diagnostic tools (like \"why did this contact match this segment?\") MUST read it here.\n\nFull match logic:\n\n  (all `segment_users` ANDed together)\n  OR (all conditions in `with_or_segment_users[0]` ANDed)\n  OR (all conditions in `with_or_segment_users[1]` ANDed)\n  OR ...\n  MINUS contacts removed by `exclude_segment_users` (all ANDed) — self-match or shared-copy match per the account setting below\n\nHow `exclude_segment_users` matches depends on the account's `shared_contact_status` (surfaced as `shared_contacts_enabled` on `GET /segments/schema`). When shared contacts are ENABLED it is the dashboard's \"exclude shared contacts\" rule: a contact is removed when one of its linked copies in another workroom (`shared_contacts[]`) matches these conditions, NOT when the contact itself matches. When shared contacts are OFF it is a plain self-subtraction: the contact is removed when its OWN fields match. The exclusion can be any condition (attribute match, event done, tag, form filled — just the positive form of what to exclude). Either way the segment must keep at least one primary condition in `segment_users`; an exclude-only (or `with_or`-only) query is rejected. To exclude by a contact's own attributes regardless of the account setting, you can also use a negative condition in `segment_users` (e.g. `Is Not One Of`, `Has not Filled a Form`, `Does Not Contain`).\n\nConditions are stored in the exact tokens the dashboard's segment engine evaluates: friendly category names are rewritten on write (`Custom`/`attributes` → `Attributes`, `email_engagement` → `EmailCampaigns`, `salesattributes` → `sales`, …), and an absolute-date `<`/`>` on a Date field is stored as `Before`/`After` with an `MM-DD-YYYY` value. A retrieved segment therefore shows the stored (engine) form.\n\nThere is no additional `all/any/none` grouping. Express further OR via multi-value operators (`Is One Of`, `Segments` with an array).\n","properties":{"segment_users":{"type":"array","items":{"$ref":"#/components/schemas/SegmentCondition"},"description":"Base inclusion conditions. All ANDed. A contact must satisfy every one to be included via this group."},"with_or_segment_users":{"type":"array","description":"Alternate inclusion groups. Each inner array is a set of conditions that are ANDed together; the outer array is OR-joined with `segment_users` and each other inner array. Use this to build \"criteria A OR criteria B\" queries without touching the top-level `segment_users`.\n","items":{"type":"array","items":{"$ref":"#/components/schemas/SegmentCondition"}}},"exclude_segment_users":{"type":"array","items":{"$ref":"#/components/schemas/SegmentCondition"},"description":"Exclusion conditions, ANDed. How they match depends on the account's `shared_contact_status` — shared-copy match when shared contacts are ON (a contact is removed when a linked copy in another workroom, `shared_contacts[]`, matches all of them), self-match when OFF (removed when the contact's own fields match all of them). Same condition shape as `segment_users`. Cannot stand alone — `segment_users` must be non-empty. See the match logic above."}}},"SegmentCondition":{"type":"object","description":"A single condition in a dynamic segment query. Shape and operator vocabulary are documented in the Segment Query DSL companion doc — the query language supports 28 segment types (Attributes, Tags, Event Trigger, External Events, Segments, SalesAttributes, Forms, Flows, Optin, and more) and 60+ operators. This schema is intentionally loose to accommodate that surface; the server validates the concrete shape.\n","required":["segment","operator"],"additionalProperties":true,"properties":{"segment":{"type":"string","description":"Segment-type discriminator. Full inventory in the DSL doc. Common values include `Attributes`, `Tags`, `Country`, `City`, `Event Trigger`, `External Events`, `Segments`, `SalesAttributes`, `Forms`, `Flows`, `SMS Optin`, `SMS Opted Out`, `Email Topics`, `Add Date`, `Last Access`.\n"},"data":{"type":"string","description":"Field or attribute within the segment type. E.g., `first_name`, `city`, `sales.pipeline.stage`.","nullable":true},"event":{"type":"string","description":"Event name — used only when `segment` is `Event Trigger`.","nullable":true},"operator":{"type":"string","description":"Operator vocabulary. Full list in the DSL doc. Common: `=`, `!=`, `<`, `>` (numeric — on a Date field they are stored as `Before`/`After`), `Contains`, `Does Not Contain`, `Is One Of`, `Is Not One Of`, `Is Empty`, `Is Not Empty`, `Exists`, `Does Not Exist`, `Is True`, `Is False`, `InLast`, `OverDays`, `InNext`, `Before`, `After`, `IsToday`, `DayInNext`, `DayInMonth`, `Is In Segment`, `Is Not In Segment`, `Has Filled a Form`. For recurring day-of-year fields (`data_type: Day`, e.g. Birthday) use the `DayInNext`/`DayInNextXY`/`DayInMonth` family — not the absolute-date `InNext`/`=` — so \"birthday in the next N days\" recurs every year (see `describeSegmentSchema`).\n\n`Exists`/`Does Not Exist` vs `Is Not Empty`/`Is Empty`: both check for a populated value and are usually close in practice, but `Exists` is what the dashboard UI itself uses when a user says a field \"exists\" - prefer `Exists`/`Does Not Exist` for that phrasing, especially inside `with_or_segment_users`, to match what the UI would produce for the same request.\n"},"value":{"type":["string","number","boolean","array","null"],"description":"The operand. Which type applies depends on the operator: a scalar for `=` and `Contains`, an array (or comma-separated string) for `Is One Of`, a number for count comparisons, and omitted entirely for `Exists` / `Is Empty`.\n"},"value2":{"type":["string","number","null"],"description":"Secondary operand for two-parameter conditions (currently `External Events` count comparison and `SalesAttributes` pipeline-stage filter)."},"operator2":{"type":"string","description":"Secondary operator for two-parameter conditions.","nullable":true},"value2_id":{"type":"array","items":{"type":"string"},"nullable":true,"description":"Object-ID list for stage-title disambiguation on `SalesAttributes`."},"data_type":{"type":"string","enum":["String","Numeric","Date","List"],"nullable":true,"description":"Optional hint for the engine's disambiguation logic."},"dataAlias":{"type":"string","nullable":true,"description":"Human-readable alias shown in the UI. Not evaluated."}}},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"SegmentFolderId":{"type":"string","pattern":"^sfd_[0-9a-fA-F]{24}$","description":"Segment folder ID."},"Metadata":{"type":"object","description":"Free-form key/value pairs the caller stores on the resource. Not evaluated by Gleantap.\nUse for opaque identifiers, integration state, or notes you need to survive round-trips.\n","additionalProperties":true},"FlowNode":{"type":"object","required":["id","type"],"description":"A node in a flow's DAG. Polymorphic on `type` — only the fields relevant to that type should be set (unused fields ignored). See per-type notes below.\n\n**Parent/child edges:** each node has `parent_id` pointing at another node's `id`. Root nodes have `parent_id: null` and `parent_branch: \"root\"`. For `condition` nodes with `action_type: \"yes_no\"`, children set `parent_branch: \"yes\"` or `\"no\"`. For `multi_choice` conditions, children set `parent_branch: \"<matched value>\"` (slugified — spaces → underscores, lowercased). For `wait_till_true` conditions, there is no branching at all — the node re-evaluates itself until its predicate matches (see `FlowConditionMode`), and its child (if any) hangs off the ordinary linear `parent_branch: \"next\"` edge, the same as a non-condition node.\n\n**Client-supplied `id`:** you supply a string identifier per node (unique within the flow). The server uses it to resolve `parent_id` references. IDs need not survive updates — the server maps them to internal IDs at save time.\n","properties":{"id":{"type":"string","maxLength":100,"pattern":"^[a-zA-Z0-9_-]+$","description":"Client-supplied identifier, unique within this flow."},"type":{"$ref":"#/components/schemas/FlowNodeType"},"parent_id":{"type":"string","nullable":true,"description":"The `id` of this node's parent. Null for root nodes."},"parent_branch":{"type":"string","default":"root","description":"Which branch of the parent this node hangs off. `root` for the flow's entry node, `next` for a linear step, `yes`/`no` for a yes_no condition child, the slugified condition `value` for a multi_choice child, or `converge` to rejoin branches after a condition node.\n"},"action_name":{"type":"string","maxLength":200,"description":"Label shown in the UI. Optional; defaults per node type."},"campaign_id":{"$ref":"#/components/schemas/CampaignId","nullable":true,"description":"Optional. If provided, the server upgrades that existing campaign into a \"shadow\" dedicated to this flow node (adds `isAutomationCampaign=true` + `automation_id` + `automation_details_id`). The campaign is no longer a standalone after this — do not share campaign_ids across flows or reuse for one-off sends.\n"},"template_id":{"$ref":"#/components/schemas/TemplateId","nullable":true,"description":"Optional. Seeds the shadow campaign's content from a library template. For `email_campaign` the template's rendered HTML, its editor design JSON and its thumbnail are all copied onto the node, which is what makes the dashboard open it as an **HTML email** (the \"HTML Email\" toggle) rather than a plain-text one — a node given only inline `message_body` is plain text by design. An explicit `message_body` on the same node overrides the template's HTML body; `subject` is never taken from the template. Render happens at send time — merge tags interpolate per-recipient using the flow's audience data.\n"},"subject":{"type":"string","nullable":true,"description":"For `email_campaign` nodes. Email subject line. Supports merge tags (`{first_name}`, `{data.company}`). REQUIRED unless `template_id` or `campaign_id` provided.\n"},"message_body":{"type":"string","nullable":true,"description":"For both `email_campaign` (HTML body) and `sms_campaign` (plain-text body). Supports merge tags. REQUIRED unless `template_id` or `campaign_id` provided.\n`sms_campaign`: At most 10 SMS segments: 1530 plain (GSM-7) characters, or 670 if the text contains emoji or any other non-GSM character (once split, each segment holds 153 GSM / 67 unicode characters; emoji count as 2). Merge tags count as written, not expanded. A longer body (inline or from `template_id`) is rejected with 422 `validation_failed`.\n"},"preheader_text":{"type":"string","nullable":true,"description":"For `email_campaign`. Preheader shown in inbox previews after subject."},"from_name":{"type":"string","nullable":true,"description":"For `email_campaign`. Sender display name. Inherits app default when omitted."},"from_email":{"type":"string","format":"email","nullable":true,"description":"For `email_campaign`. Sender address. Inherits app default when omitted."},"from_number":{"type":"string","nullable":true,"description":"For `sms_campaign`. E.164 sender phone. Inherits app default when omitted."},"schedule":{"type":"string","enum":["Relative","Specific Date & Time"],"nullable":true,"description":"For `delay` nodes."},"delayTimeHour":{"type":"integer","nullable":true,"description":"For `delay` with `schedule: \"Relative\"`. Amount of `delayTimetype`."},"delayTimetype":{"type":"string","enum":["minutes","hours","days","weeks","months"],"nullable":true,"description":"For `delay` with `schedule: \"Relative\"`."},"selected_date":{"type":"string","format":"date","nullable":true,"description":"For `delay` with `schedule: \"Specific Date & Time\"`."},"selected_time":{"type":"string","nullable":true,"description":"For `delay` with `schedule: \"Specific Date & Time\"`. `HH:mm:ss` in the flow's timezone."},"action_type":{"$ref":"#/components/schemas/FlowConditionMode","nullable":true,"description":"For `condition` nodes."},"segment_users":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/SegmentCondition"},"description":"For `condition` with `action_type: \"yes_no\"` or `\"wait_till_true\"`. Segment DSL predicates — materialized into a hidden shadow segment for either mode (see `FlowConditionMode`) so the live cron can evaluate it.\n\n**Before constructing this**: call `describeSegmentSchema` (or `GET /v3/segments/schema`) to see available categories and copy each attribute's `condition_template` (segment/data/dataAlias/data_type) verbatim, using an `operator` from that field's `operators[]` — the same rule `createSegment`'s conditions follow. Don't guess a field key or reach for a human phrase like \"Before\" from general knowledge; the schema call is what tells you the exact tokens the engine expects.\n"},"with_or_segment_users":{"type":"array","nullable":true,"description":"For `condition` with `action_type: \"yes_no\"` or `\"wait_till_true\"` only — same OR-logic semantics as Segments' `query.with_or_segment_users`: each inner array is ANDed, and the outer array is OR-joined with `segment_users` and every other group. Materialized into the same hidden shadow segment as `segment_users` (confirmed live: `attach_condition_segment()` writes both fields identically onto the shadow segment doc, and the engine reads it from there). For `multi_choice`, use `with_or_segment_users` on the individual `FlowMultiCondition` branch instead — this top-level field is ignored for that mode.\n\nEchoed back on create/retrieve just like `segment_users` (it is persisted on the condition node itself in addition to the shadow segment), so a round-trip reflects exactly what you sent.\n","items":{"type":"array","items":{"$ref":"#/components/schemas/SegmentCondition"}}},"multi_conditions":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/FlowMultiCondition"},"description":"For `condition` with `action_type: \"multi_choice\"`."},"salesautomation_id":{"type":"string","nullable":true,"pattern":"^saut_[0-9A-HJKMNP-TV-Z]{26}$","description":"For `sales_automation` nodes. References a CRM automation created via `POST /v3/pipelines/{pipeline_id}/automations`."},"sales_automation":{"type":"object","nullable":true,"description":"For `sales_automation` nodes, instead of `salesautomation_id`: an inline CRM rule. v3 creates the rule and binds it to this node. Send `action` for one action or `actions` for several (run in order). Do not send a `trigger`; the flow decides when it runs.","properties":{"action":{"$ref":"#/components/schemas/SalesAutomationAction"},"actions":{"type":"array","items":{"$ref":"#/components/schemas/SalesAutomationAction"}}}},"webhook_url":{"type":"string","format":"uri","nullable":true,"description":"REQUIRED on `webhook` nodes — creating one without it returns 422. A webhook with no destination can never fire, and the dashboard refuses to save one for the same reason. Must be `https://` unless the account has `allow_http_webhooks: true`.\n\nGet the URL from the user. There is no sensible default and no way to infer it.\n"},"webhook_method":{"type":"string","enum":["GET","POST"],"default":"GET","description":"The flow worker only sends GET or POST; any other value is a 422 (it would silently go out as GET).","nullable":true},"webhook_payload_type":{"type":"string","enum":["json","form"],"default":"json","nullable":true},"webhook_fields":{"type":"array","nullable":true,"description":"REQUIRED on `webhook` nodes: at least one `{key, value}` pair with a non-empty `key` and `value` (`\"0\"` counts as empty). The flow worker builds the request only from such pairs and sends NOTHING when there are none — for GET (query string) as well as POST — so a node without one is a 422. Every entry must be an object with string `key` and `value`. `key` may use dot notation for nesting. Ask the user what the receiving system expects.\n","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string","description":"Supports `{placeholder}` interpolation from contact fields (e.g., `{first_name}`, `{email}`, `{data.custom_field}`)."}}}},"webhook_header_fields":{"type":"array","nullable":true,"description":"Optional request headers. Each entry needs a non-empty `key` and `value` (422 otherwise — the worker would drop it).","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}}}},"mariana_action":{"type":"object","nullable":true,"description":"Required for `mariana_action` nodes. Gives the enrolled contact something in the workroom's Mariana Tek studio. The contact is found by their Mariana id or exact email; with `if_not_found: create` a Mariana account is created from their email and name and Mariana emails them a set-password link. Each enrollment gives at most once. Amount and credit caps are the workroom's limits (default 100 and 20); values over them, or a malformed config, are rejected 422 so a saved node always runs.\n","required":["type"],"properties":{"type":{"type":"string","enum":["pack","class_credits","account_credit"]},"package_id":{"type":"string","description":"Mariana pack (package) id. `pack`: gives that pack's class credits with the pack's own expiry."},"package_name":{"type":"string","description":"Display name for the pack."},"credit_id":{"type":"string","description":"`class_credits`: Mariana credit type id."},"credit_name":{"type":"string"},"quantity":{"type":"integer","minimum":1,"description":"`class_credits`: number of credits (at most the workroom limit, default 20)."},"expiry_days":{"type":"string","description":"`class_credits`: whole days until the credits expire; empty for no expiry."},"amount":{"type":"number","description":"`account_credit`: amount to add, up to 2 decimals and the workroom limit (default 100)."},"currency":{"type":"string","description":"`account_credit`: 3-letter code, default USD."},"note":{"type":"string","maxLength":60,"description":"Shown on the credit in Mariana."},"if_not_found":{"type":"string","enum":["create","skip"],"default":"create"},"recipient":{"type":"string","enum":["contact","referrer"],"default":"contact","description":"`referrer` gives to the member who referred the contact (their `referred_by_id` in the same workroom, set by the referral intake) instead of the contact, once per enrollment. Use it in a referred friend's flow to reward the member."}}}}},"FlowNodeType":{"type":"string","enum":["email_campaign","sms_campaign","delay","condition","sales_automation","webhook","mariana_action"],"description":"The 7 node types the engine actually supports (`mariana_action` gives the contact a pack, class credits or account credit in the workroom's Mariana Tek studio). Richer vocab from the main spec (`send_message`, `tag`, `add_to_segment`, `update_contact`, `create_task`, `create_opportunity`, `wait_for_event`, `split`, `end`) is NOT implemented — express those via `sales_automation` (pointing at a CRM sub-automation) or return 501 `node_type_not_supported`. See Flow Engine companion doc §10.\n"},"CampaignId":{"type":"string","pattern":"^cam_[0-9a-f]{24}$"},"TemplateId":{"type":"string","pattern":"^tpl_[0-9a-f]{24}$"},"FlowConditionMode":{"type":"string","enum":["yes_no","multi_choice","wait_till_true"],"description":"`yes_no` — evaluates the `segment_users` predicate once, immediately, and branches: children set `parent_branch: \"yes\"` or `\"no\"` (see FlowNode's parent/child edges note). `multi_choice` — evaluates `multi_conditions` in order; the first match's slugified `value` becomes the child branch. `wait_till_true` — does NOT branch. It re-evaluates the SAME predicate, on the SAME node, on the engine's existing cron cadence, until it matches; only then does execution advance (linearly, via the ordinary `next` edge — there is no \"no\" child to fall through to). Confirmed against the dashboard/flow engine (`Cron.php`'s condition handling): while unmatched, the node is flagged `condition_repeat: true` and re-checked on the next cron pass rather than branching, and — unlike a `yes_no` match — a `wait_till_true` match never writes `operation_parent_type`/`operation_parent_id` on its action-story entry, confirming it has no yes/no children of its own.\n\n**Materialization (fixed — previously a known gap):** both `yes_no` and `wait_till_true` are evaluated by the engine against a legacy `yes_condition` field, which this API materializes from `segment_users` into a hidden shadow segment at creation time. `wait_till_true` is now included in that materialization the same way `yes_no` already was — a `wait_till_true` node created via this API is fully wired for the live cron to evaluate, not merely accepted and stored. Archiving a flow deletes these shadow segments (the node keeps `segment_users`, so duplicating the flow rebuilds them).\n"},"FlowMultiCondition":{"type":"object","required":["value"],"description":"One branch of a `multi_choice` condition. The engine evaluates each in order; the first `segment_users` match wins. Up to 6 regular branches plus one optional catch-all.\n\n**Storage.** Regular branches are stored as `Condition A`..`Condition F` in the order given, with your label kept as `name_alias` (what the dashboard shows). Children may reference a branch by your label, by `Condition A`, or by `condition_a`.\n\n**Catch-all.** Mark a branch with `is_other: true` (or `value: \"Other\"` / `\"Condition Other\"`). It is stored exactly as the dashboard stores it — `{value: \"Condition Other\", segment_users: [{segment: \"other\"}]}` — always last, and it matches every contact no earlier branch matched; any `segment_users` you give it are ignored (warning `other_branch_conditions_ignored`). Children reference it as `Other` / `condition_other`. Without a catch-all, a contact who matches no branch does not advance. More than 6 regular branches, or two catch-alls, is a 422. Reads echo `is_other: true` on the catch-all.\n","properties":{"value":{"type":"string","description":"Human-readable branch name (stored as `name_alias`; `value` becomes `Condition A`..`F`). `Other` / `Condition Other` marks the catch-all."},"is_other":{"type":"boolean","default":false,"description":"Marks this branch as the catch-all (see above)."},"name_alias":{"type":"string","description":"Display label. Set from `value` on write."},"segment_users":{"type":"array","items":{"$ref":"#/components/schemas/SegmentCondition"},"description":"Segment DSL conditions (see the Segment Query DSL doc). Ignored on the catch-all branch, which is stored with `[{segment: \"other\"}]`.\n\n**Before constructing this**: call `describeSegmentSchema` (or `GET /v3/segments/schema`) and copy each condition's `condition_template` verbatim, same as the condition node's own top-level `segment_users` — don't invent field/operator tokens here just because this is a nested branch.\n"},"with_or_segment_users":{"type":"array","description":"Alternate inclusion groups for THIS branch only, same OR-logic semantics as Segments' `query.with_or_segment_users`: each inner array is a set of conditions ANDed together, and the outer array is OR-joined with this branch's own `segment_users` and every other group here. Use this to build \"criteria A OR criteria B\" matching for one multi_choice branch without touching its `segment_users`. Optional; has no effect on the `Condition Other` fallback branch or on any other branch's matching.\n","items":{"type":"array","items":{"$ref":"#/components/schemas/SegmentCondition"}}}}},"SalesAutomationAction":{"type":"object","required":["type"],"description":"Polymorphic on `type`. 13 action types available — see `describeFlowSchema` for the full guide + params per action.\n","properties":{"type":{"type":"string","enum":["tags","remove_tags","task","add_stage","move_stage","sync_stage","remove_stage","assign","remove_assign","status","priority","add_note","enroll_in_flow"]},"tag_names":{"type":"array","items":{"type":"string"},"description":"For `tags` / `remove_tags`."},"task_name":{"type":"string","description":"For `task`."},"description":{"type":"string","description":"For `task`."},"due_at":{"$ref":"#/components/schemas/Timestamp","description":"For `task` (write only; converted to `due_in_days`)."},"due_in_days":{"type":"integer","description":"For `task`. Days from the trigger until the task is due. Default 1."},"assignee_staff_id":{"$ref":"#/components/schemas/StaffId","description":"For `task`: one responsible (\"Specific\"). Omit both assignee fields for the contact owner (\"Owner\")."},"assignee_staff_ids":{"type":"array","items":{"$ref":"#/components/schemas/StaffId"},"description":"For `task`: round-robin across these staff."},"assignee_mode":{"type":"string","readOnly":true,"enum":["Owner","Specific","Round Robin"],"description":"For `task`, read only."},"task_type":{"type":"string","description":"For `task`: task type id (`tst_…`). Defaults to the workroom's first type."},"stage_id":{"$ref":"#/components/schemas/StageId","description":"For stage actions. Required: a stage action with no valid stage is rejected (422), since the worker cannot run it."},"staff_ids":{"type":"array","items":{"$ref":"#/components/schemas/StaffId"},"description":"For `assign` / `remove_assign`. Required (non-empty)."},"distribution":{"type":"string","enum":["All","Round Robin"],"description":"For `assign`. Other values (including the dashboard's \"Round Robin By Day\", which needs a per-day roster) are stored as `All` with a warning."},"reassign":{"type":"boolean","default":false,"description":"For `assign`: true replaces a contact's existing responsible; false only fills unassigned contacts."},"value":{"type":"string","description":"For `status` / `priority`."},"note":{"type":"string","description":"For `add_note`."},"flow_id":{"type":"string","description":"For `enroll_in_flow`."},"applies_to":{"type":"string","description":"Segment scope — usually \"All\" or a segment name.","default":"All"}}},"StaffId":{"type":"string","pattern":"^usr_[0-9a-f]{24}$","description":"A staff user (from the legacy `users` collection). Used for `owner_id`, `responsible_id`, `created_by`, `assigned_to`, etc."},"StageId":{"type":"string","pattern":"^stg_[0-9a-f]{24}$"},"FlowStats":{"type":"object","description":"Run counters. `active_runs` and `completed_runs` are current state and do not move with the analytics window; `entered` and `unenrolled` are windowed.\n","properties":{"active_runs":{"type":"integer","minimum":0,"description":"Runs open right now."},"completed_runs":{"type":"integer","minimum":0,"description":"Runs finished","all time.":null},"entered":{"type":"integer","minimum":0,"description":"Contacts enrolled within the window."},"unenrolled":{"type":"integer","minimum":0,"description":"Contacts unenrolled within the window."},"entered_last_30d":{"type":"integer","minimum":0,"deprecated":true,"description":"Same value as `entered`. Kept for existing callers; the name is only accurate when the window is the default 30 days."},"unenrolled_last_30d":{"type":"integer","minimum":0,"deprecated":true,"description":"Same value as `unenrolled`."}}},"Timezone":{"type":"string","description":"IANA timezone name."},"UserId":{"type":"string","pattern":"^usr_[0-9A-HJKMNP-TV-Z]{26}$"},"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}},"responses":{"NotFound":{"description":"The resource doesn't exist or isn't visible to this caller.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Conflict":{"description":"Idempotency conflict, version conflict (`If-Match`), or state conflict.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/flows/{id}/unpublish":{"post":{"tags":["Flows"],"operationId":"unpublishFlow","summary":"Unpublish a flow.","description":"Transitions `active` → `inactive`. Stops new enrollments; in-flight runs continue to completion. To stop in-flight runs too, use `DELETE /v3/flows/{id}` (archive).\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"}],"responses":{"200":{"description":"Unpublished.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Flow"}}}},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}}}}}}
```

## Duplicate a flow.

> Creates a new \`draft\` flow with the same entry, nodes, and conversion goals. Stats are NOT copied. As in the dashboard's clone, every message node gets its own fresh shadow campaign (same content, \`drafted\`), every \`yes\_no\`/\`wait\_till\_true\` condition its own hidden condition segment, and every \`sales\_automation\` node its own CRM rule (inactive until the copy is published) — nothing in the copy references the original's parts, so editing or archiving one flow never touches the other. Works on archived flows (the way to bring one back).<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Flows","description":"Multi-step automations. Enrollment is driven by segment membership. 7 node types are supported by the engine — see the Flow Engine companion doc for the full model, including the versioning and in-flight-edit caveats."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["flows:write"]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"},"OAuth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE. Use for third-party apps acting on behalf of a Gleantap user.\nAuthorization Code + PKCE is the only supported grant for interactive flows; refresh_token grant is supported and rotates on every use.\n","flows":{"authorizationCode":{"authorizationUrl":"https://api.gleantap.com/v3/oauth/authorize","tokenUrl":"https://api.gleantap.com/v3/oauth/token","refreshUrl":"https://api.gleantap.com/v3/oauth/token","scopes":{"contacts:read":"Read contact records.","contacts:write":"Create, update, delete contacts (soft delete).","contacts:delete_hard":"Hard-delete contacts (irreversible).","events:read":"Read event records.","events:write":"Record events.","segments:read":"Read segments and preview membership.","segments:write":"Create, update, delete segments.","templates:read":"Read message templates.","templates:write":"Create, update, delete templates.","campaigns:read":"Read campaigns and analytics.","campaigns:write":"Create, schedule, cancel campaigns.","flows:read":"Read flow definitions and analytics.","flows:write":"Create, edit, publish flows.","flows:publish":"Publish/unpublish flows (separately scoped for governance).","messaging:send":"Send transactional messages (SMS, email, voice).","conversations:read":"Read conversations and messages.","conversations:write":"Send messages, close/reopen conversations.","webhooks:manage":"Create, update, delete webhook endpoints.","forms:manage":"Create, update, delete, publish, duplicate forms; list submissions and rotate the submission_token.","campaigns:manage":"Create, schedule, cancel, duplicate campaigns; read recipients and analytics. (Supersedes the earlier `campaigns:read` + `campaigns:write` split; the split scopes still work.)","admin:impersonate:read":"Gleantap staff only — read any customer account named via `Gleantap-Account`. Not available through dynamic client registration.","admin:impersonate:write":"Gleantap staff only — required for any state-changing method while impersonating. Not available through dynamic client registration."}}}}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"WorkroomQuery":{"name":"workroom","in":"query","required":false,"description":"Same semantics as the `Gleantap-Workroom` header, including that a write should never be sent without a workroom the user actually chose, and that an omitted workroom scopes a read to the account default rather than spanning the account. Prefer this on GETs so proxies and caches can key on it. Accepts name, prefixed ID, raw hex, or `all`.\n","schema":{"type":"string"}}},"schemas":{"Flow":{"type":"object","required":["id","object","name","status","entry","nodes","created_at","updated_at"],"properties":{"id":{"$ref":"#/components/schemas/FlowId"},"object":{"type":"string","const":"flow"},"name":{"type":"string","maxLength":200},"description":{"type":"string","nullable":true,"maxLength":2000},"status":{"$ref":"#/components/schemas/FlowStatus"},"workroom_id":{"$ref":"#/components/schemas/WorkroomId","nullable":true,"description":"The workroom this flow lives in. Its `entry.segment_ids` must all belong to the same workroom."},"entry":{"$ref":"#/components/schemas/FlowEntry"},"nodes":{"type":"array","items":{"$ref":"#/components/schemas/FlowNode"}},"stats":{"$ref":"#/components/schemas/FlowStats"},"conversion_config":{"type":"object","nullable":true,"description":"Optional conversion goal(s) tracked per contact per run.","properties":{"conversion_ids":{"type":"array","items":{"type":"string"}},"attribution_window_days":{"type":"integer","minimum":1,"nullable":true}}},"timezone":{"$ref":"#/components/schemas/Timezone","nullable":true,"description":"Timezone used to interpret `delay` node \"Specific Date & Time\" values. Defaults to the account timezone."},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"published_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"archived_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"created_by_user_id":{"$ref":"#/components/schemas/UserId","nullable":true},"metadata":{"$ref":"#/components/schemas/Metadata"}}},"FlowId":{"type":"string","pattern":"^flw_[0-9A-HJKMNP-TV-Z]{26}$"},"FlowStatus":{"type":"string","enum":["draft","active","inactive","paused","completed","archived"],"description":"`draft` — never published. `active` — published and enrolling. `inactive` — unpublished; in-flight runs continue but no new entries. `paused` — enrollment and step execution both halted; can be resumed. `completed` — `end_date_time` passed. `archived` — soft-deleted.\n"},"WorkroomId":{"type":"string","pattern":"^wrm_[0-9a-f]{24}$"},"FlowEntry":{"type":"object","description":"Flow enrollment configuration. Enrollment is driven by segment membership — contacts entering `segment_ids` are enrolled on the next cron pass. Rich trigger vocab (`event`, `form_submission`, `appointment_booked`, etc.) is not first-class in the engine; model those via a segment that captures the trigger criteria.\n\n**Set a trigger.** Publishing requires `segment_ids`. A flow without them is created with a `no_entry_trigger` warning and publishing is refused with `no_entry_segment`: the send worker enrolls every contact in the entry segment, so a flow with none would enroll the whole workroom. `segment_criteria` and `manual_only` are not read by the worker; save criteria as a segment and use its id.\n\n**Workroom matching.** A flow lives in exactly one workroom and can only be triggered by segments from that same workroom. Compare `Segment.workroom_id` with `Flow.workroom_id`. On create you don't need to pass `workroom`: the flow is placed in the workroom that owns `segment_ids`. Segments spanning two workrooms are rejected — build one flow per workroom. On PATCH the workroom is already fixed, so a sibling-workroom segment is rejected with `422 invalid_segment_ids`.\n","properties":{"segment_ids":{"type":"array","items":{"$ref":"#/components/schemas/SegmentId"},"description":"Contacts entering ANY of these segments enter the flow. Must all belong to one workroom."},"segments":{"type":"array","items":{"$ref":"#/components/schemas/Segment"},"description":"Inlined Segment objects when `?expand=entry.segments` is requested."},"unenroll_segment_ids":{"type":"array","items":{"$ref":"#/components/schemas/SegmentId"},"description":"Contacts entering ANY of these segments are unenrolled from in-flight runs. Must belong to the flow's workroom."},"unenroll_segments":{"type":"array","items":{"$ref":"#/components/schemas/Segment"},"description":"Inlined unenroll Segment objects when `?expand=entry.segments` is requested."},"manual_only":{"type":"boolean","default":false,"description":"Marks a flow meant for `POST /v3/flows/{id}/enroll`. It does not remove the need for `segment_ids` to publish: the send worker enrolls the entry segment regardless, so use a segment that matches nobody until you enroll contacts."},"reenroll":{"type":"boolean","default":false,"description":"Allow contacts who completed the flow to enter again. Stored as the dashboard's `reenroll_status`, which is the only field the flow worker reads. The worker re-enrolls a contact who still matches the entry segment once their finished run started before today (account timezone); the old run moves to history and the new run has `reenroll: true`. Manual enroll (`POST /enroll`) follows the same rule.\n\nReads report what the worker will do: flows saved by older API versions with only `reenroll` set read `false` until re-saved.\n"},"reentry_cooldown_days":{"type":"integer","nullable":true,"deprecated":true,"description":"Not supported, and ignored. The flow worker has no re-entry cooldown. Sending a value returns a `reentry_cooldown_days_unsupported` warning and nothing is stored. To space re-entries, build the gap into the entry segment."},"end_date_time":{"$ref":"#/components/schemas/Timestamp","nullable":true,"description":"Flow auto-completes past this time. New enrollments halted; in-flight runs continue."},"segment_criteria":{"$ref":"#/components/schemas/SegmentQuery","nullable":true,"description":"Stored and echoed back only. The enrollment worker never reads it: who enters is decided by `segment_ids` alone, and it does not narrow them. To enroll on criteria, save them as a segment (`POST /v3/segments`) and put its id in `segment_ids`."}}},"SegmentId":{"type":"string","pattern":"^seg_[0-9A-HJKMNP-TV-Z]{26}$"},"Segment":{"type":"object","description":"A named collection of contacts. Either static (hand-managed list) or dynamic (query-defined). Discriminated by the `type` field, which is immutable after creation.\n","required":["id","object","type","name","size","created_at","updated_at"],"properties":{"id":{"$ref":"#/components/schemas/SegmentId"},"object":{"type":"string","const":"segment"},"workroom_id":{"$ref":"#/components/schemas/WorkroomId","nullable":true,"description":"The workroom that owns this segment. A flow can only be triggered by segments in its own workroom — compare against `Flow.workroom_id`."},"type":{"$ref":"#/components/schemas/SegmentType"},"name":{"type":"string","maxLength":200},"description":{"type":"string","nullable":true,"maxLength":2000},"query":{"$ref":"#/components/schemas/SegmentQuery","nullable":true,"description":"The segment's criteria. **Present on BOTH static and dynamic segments** — a \"static\" segment only means the engine doesn't auto-refresh membership; the criteria that defined the initial membership list is still stored and returned. When diagnosing \"why did this contact match this segment?\", read `query.segment_users` (+ `with_or_segment_users` and `exclude_segment_users`). May be `null` only on segments imported without criteria or created empty.\n"},"size":{"type":"integer","minimum":0,"description":"Current member count. Eventually consistent — up to minutes of lag on dynamic segments."},"email_count":{"type":"integer","minimum":0,"description":"Members with a non-empty, non-invalid email."},"phone_count":{"type":"integer","minimum":0,"description":"Members with a non-empty, non-invalid phone."},"last_evaluated_at":{"$ref":"#/components/schemas/Timestamp","nullable":true,"description":"When this dynamic segment was last recomputed. Null on static."},"folder_id":{"$ref":"#/components/schemas/SegmentFolderId","nullable":true,"description":"The segment folder this segment currently belongs to, or `null` if unfoldered."},"segment_summary":{"type":"string","nullable":true,"description":"AI-generated narrative summary of the segment's criteria. Populated on demand via `POST /v3/segments/{id}/summary`."},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"metadata":{"$ref":"#/components/schemas/Metadata"}}},"SegmentType":{"type":"string","enum":["static","dynamic"],"description":"`static` — hand-managed member list. Contacts are added/removed explicitly.\n`dynamic` — query-defined membership. Auto-evaluated; membership changes as contact data changes.\nImmutable after creation.\n"},"SegmentQuery":{"type":"object","description":"The segment criteria. **Present on BOTH `static` and `dynamic` segments** — \"static\" only means the engine doesn't auto-refresh membership; the criteria that defined the segment is still on the doc, and diagnostic tools (like \"why did this contact match this segment?\") MUST read it here.\n\nFull match logic:\n\n  (all `segment_users` ANDed together)\n  OR (all conditions in `with_or_segment_users[0]` ANDed)\n  OR (all conditions in `with_or_segment_users[1]` ANDed)\n  OR ...\n  MINUS contacts removed by `exclude_segment_users` (all ANDed) — self-match or shared-copy match per the account setting below\n\nHow `exclude_segment_users` matches depends on the account's `shared_contact_status` (surfaced as `shared_contacts_enabled` on `GET /segments/schema`). When shared contacts are ENABLED it is the dashboard's \"exclude shared contacts\" rule: a contact is removed when one of its linked copies in another workroom (`shared_contacts[]`) matches these conditions, NOT when the contact itself matches. When shared contacts are OFF it is a plain self-subtraction: the contact is removed when its OWN fields match. The exclusion can be any condition (attribute match, event done, tag, form filled — just the positive form of what to exclude). Either way the segment must keep at least one primary condition in `segment_users`; an exclude-only (or `with_or`-only) query is rejected. To exclude by a contact's own attributes regardless of the account setting, you can also use a negative condition in `segment_users` (e.g. `Is Not One Of`, `Has not Filled a Form`, `Does Not Contain`).\n\nConditions are stored in the exact tokens the dashboard's segment engine evaluates: friendly category names are rewritten on write (`Custom`/`attributes` → `Attributes`, `email_engagement` → `EmailCampaigns`, `salesattributes` → `sales`, …), and an absolute-date `<`/`>` on a Date field is stored as `Before`/`After` with an `MM-DD-YYYY` value. A retrieved segment therefore shows the stored (engine) form.\n\nThere is no additional `all/any/none` grouping. Express further OR via multi-value operators (`Is One Of`, `Segments` with an array).\n","properties":{"segment_users":{"type":"array","items":{"$ref":"#/components/schemas/SegmentCondition"},"description":"Base inclusion conditions. All ANDed. A contact must satisfy every one to be included via this group."},"with_or_segment_users":{"type":"array","description":"Alternate inclusion groups. Each inner array is a set of conditions that are ANDed together; the outer array is OR-joined with `segment_users` and each other inner array. Use this to build \"criteria A OR criteria B\" queries without touching the top-level `segment_users`.\n","items":{"type":"array","items":{"$ref":"#/components/schemas/SegmentCondition"}}},"exclude_segment_users":{"type":"array","items":{"$ref":"#/components/schemas/SegmentCondition"},"description":"Exclusion conditions, ANDed. How they match depends on the account's `shared_contact_status` — shared-copy match when shared contacts are ON (a contact is removed when a linked copy in another workroom, `shared_contacts[]`, matches all of them), self-match when OFF (removed when the contact's own fields match all of them). Same condition shape as `segment_users`. Cannot stand alone — `segment_users` must be non-empty. See the match logic above."}}},"SegmentCondition":{"type":"object","description":"A single condition in a dynamic segment query. Shape and operator vocabulary are documented in the Segment Query DSL companion doc — the query language supports 28 segment types (Attributes, Tags, Event Trigger, External Events, Segments, SalesAttributes, Forms, Flows, Optin, and more) and 60+ operators. This schema is intentionally loose to accommodate that surface; the server validates the concrete shape.\n","required":["segment","operator"],"additionalProperties":true,"properties":{"segment":{"type":"string","description":"Segment-type discriminator. Full inventory in the DSL doc. Common values include `Attributes`, `Tags`, `Country`, `City`, `Event Trigger`, `External Events`, `Segments`, `SalesAttributes`, `Forms`, `Flows`, `SMS Optin`, `SMS Opted Out`, `Email Topics`, `Add Date`, `Last Access`.\n"},"data":{"type":"string","description":"Field or attribute within the segment type. E.g., `first_name`, `city`, `sales.pipeline.stage`.","nullable":true},"event":{"type":"string","description":"Event name — used only when `segment` is `Event Trigger`.","nullable":true},"operator":{"type":"string","description":"Operator vocabulary. Full list in the DSL doc. Common: `=`, `!=`, `<`, `>` (numeric — on a Date field they are stored as `Before`/`After`), `Contains`, `Does Not Contain`, `Is One Of`, `Is Not One Of`, `Is Empty`, `Is Not Empty`, `Exists`, `Does Not Exist`, `Is True`, `Is False`, `InLast`, `OverDays`, `InNext`, `Before`, `After`, `IsToday`, `DayInNext`, `DayInMonth`, `Is In Segment`, `Is Not In Segment`, `Has Filled a Form`. For recurring day-of-year fields (`data_type: Day`, e.g. Birthday) use the `DayInNext`/`DayInNextXY`/`DayInMonth` family — not the absolute-date `InNext`/`=` — so \"birthday in the next N days\" recurs every year (see `describeSegmentSchema`).\n\n`Exists`/`Does Not Exist` vs `Is Not Empty`/`Is Empty`: both check for a populated value and are usually close in practice, but `Exists` is what the dashboard UI itself uses when a user says a field \"exists\" - prefer `Exists`/`Does Not Exist` for that phrasing, especially inside `with_or_segment_users`, to match what the UI would produce for the same request.\n"},"value":{"type":["string","number","boolean","array","null"],"description":"The operand. Which type applies depends on the operator: a scalar for `=` and `Contains`, an array (or comma-separated string) for `Is One Of`, a number for count comparisons, and omitted entirely for `Exists` / `Is Empty`.\n"},"value2":{"type":["string","number","null"],"description":"Secondary operand for two-parameter conditions (currently `External Events` count comparison and `SalesAttributes` pipeline-stage filter)."},"operator2":{"type":"string","description":"Secondary operator for two-parameter conditions.","nullable":true},"value2_id":{"type":"array","items":{"type":"string"},"nullable":true,"description":"Object-ID list for stage-title disambiguation on `SalesAttributes`."},"data_type":{"type":"string","enum":["String","Numeric","Date","List"],"nullable":true,"description":"Optional hint for the engine's disambiguation logic."},"dataAlias":{"type":"string","nullable":true,"description":"Human-readable alias shown in the UI. Not evaluated."}}},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"SegmentFolderId":{"type":"string","pattern":"^sfd_[0-9a-fA-F]{24}$","description":"Segment folder ID."},"Metadata":{"type":"object","description":"Free-form key/value pairs the caller stores on the resource. Not evaluated by Gleantap.\nUse for opaque identifiers, integration state, or notes you need to survive round-trips.\n","additionalProperties":true},"FlowNode":{"type":"object","required":["id","type"],"description":"A node in a flow's DAG. Polymorphic on `type` — only the fields relevant to that type should be set (unused fields ignored). See per-type notes below.\n\n**Parent/child edges:** each node has `parent_id` pointing at another node's `id`. Root nodes have `parent_id: null` and `parent_branch: \"root\"`. For `condition` nodes with `action_type: \"yes_no\"`, children set `parent_branch: \"yes\"` or `\"no\"`. For `multi_choice` conditions, children set `parent_branch: \"<matched value>\"` (slugified — spaces → underscores, lowercased). For `wait_till_true` conditions, there is no branching at all — the node re-evaluates itself until its predicate matches (see `FlowConditionMode`), and its child (if any) hangs off the ordinary linear `parent_branch: \"next\"` edge, the same as a non-condition node.\n\n**Client-supplied `id`:** you supply a string identifier per node (unique within the flow). The server uses it to resolve `parent_id` references. IDs need not survive updates — the server maps them to internal IDs at save time.\n","properties":{"id":{"type":"string","maxLength":100,"pattern":"^[a-zA-Z0-9_-]+$","description":"Client-supplied identifier, unique within this flow."},"type":{"$ref":"#/components/schemas/FlowNodeType"},"parent_id":{"type":"string","nullable":true,"description":"The `id` of this node's parent. Null for root nodes."},"parent_branch":{"type":"string","default":"root","description":"Which branch of the parent this node hangs off. `root` for the flow's entry node, `next` for a linear step, `yes`/`no` for a yes_no condition child, the slugified condition `value` for a multi_choice child, or `converge` to rejoin branches after a condition node.\n"},"action_name":{"type":"string","maxLength":200,"description":"Label shown in the UI. Optional; defaults per node type."},"campaign_id":{"$ref":"#/components/schemas/CampaignId","nullable":true,"description":"Optional. If provided, the server upgrades that existing campaign into a \"shadow\" dedicated to this flow node (adds `isAutomationCampaign=true` + `automation_id` + `automation_details_id`). The campaign is no longer a standalone after this — do not share campaign_ids across flows or reuse for one-off sends.\n"},"template_id":{"$ref":"#/components/schemas/TemplateId","nullable":true,"description":"Optional. Seeds the shadow campaign's content from a library template. For `email_campaign` the template's rendered HTML, its editor design JSON and its thumbnail are all copied onto the node, which is what makes the dashboard open it as an **HTML email** (the \"HTML Email\" toggle) rather than a plain-text one — a node given only inline `message_body` is plain text by design. An explicit `message_body` on the same node overrides the template's HTML body; `subject` is never taken from the template. Render happens at send time — merge tags interpolate per-recipient using the flow's audience data.\n"},"subject":{"type":"string","nullable":true,"description":"For `email_campaign` nodes. Email subject line. Supports merge tags (`{first_name}`, `{data.company}`). REQUIRED unless `template_id` or `campaign_id` provided.\n"},"message_body":{"type":"string","nullable":true,"description":"For both `email_campaign` (HTML body) and `sms_campaign` (plain-text body). Supports merge tags. REQUIRED unless `template_id` or `campaign_id` provided.\n`sms_campaign`: At most 10 SMS segments: 1530 plain (GSM-7) characters, or 670 if the text contains emoji or any other non-GSM character (once split, each segment holds 153 GSM / 67 unicode characters; emoji count as 2). Merge tags count as written, not expanded. A longer body (inline or from `template_id`) is rejected with 422 `validation_failed`.\n"},"preheader_text":{"type":"string","nullable":true,"description":"For `email_campaign`. Preheader shown in inbox previews after subject."},"from_name":{"type":"string","nullable":true,"description":"For `email_campaign`. Sender display name. Inherits app default when omitted."},"from_email":{"type":"string","format":"email","nullable":true,"description":"For `email_campaign`. Sender address. Inherits app default when omitted."},"from_number":{"type":"string","nullable":true,"description":"For `sms_campaign`. E.164 sender phone. Inherits app default when omitted."},"schedule":{"type":"string","enum":["Relative","Specific Date & Time"],"nullable":true,"description":"For `delay` nodes."},"delayTimeHour":{"type":"integer","nullable":true,"description":"For `delay` with `schedule: \"Relative\"`. Amount of `delayTimetype`."},"delayTimetype":{"type":"string","enum":["minutes","hours","days","weeks","months"],"nullable":true,"description":"For `delay` with `schedule: \"Relative\"`."},"selected_date":{"type":"string","format":"date","nullable":true,"description":"For `delay` with `schedule: \"Specific Date & Time\"`."},"selected_time":{"type":"string","nullable":true,"description":"For `delay` with `schedule: \"Specific Date & Time\"`. `HH:mm:ss` in the flow's timezone."},"action_type":{"$ref":"#/components/schemas/FlowConditionMode","nullable":true,"description":"For `condition` nodes."},"segment_users":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/SegmentCondition"},"description":"For `condition` with `action_type: \"yes_no\"` or `\"wait_till_true\"`. Segment DSL predicates — materialized into a hidden shadow segment for either mode (see `FlowConditionMode`) so the live cron can evaluate it.\n\n**Before constructing this**: call `describeSegmentSchema` (or `GET /v3/segments/schema`) to see available categories and copy each attribute's `condition_template` (segment/data/dataAlias/data_type) verbatim, using an `operator` from that field's `operators[]` — the same rule `createSegment`'s conditions follow. Don't guess a field key or reach for a human phrase like \"Before\" from general knowledge; the schema call is what tells you the exact tokens the engine expects.\n"},"with_or_segment_users":{"type":"array","nullable":true,"description":"For `condition` with `action_type: \"yes_no\"` or `\"wait_till_true\"` only — same OR-logic semantics as Segments' `query.with_or_segment_users`: each inner array is ANDed, and the outer array is OR-joined with `segment_users` and every other group. Materialized into the same hidden shadow segment as `segment_users` (confirmed live: `attach_condition_segment()` writes both fields identically onto the shadow segment doc, and the engine reads it from there). For `multi_choice`, use `with_or_segment_users` on the individual `FlowMultiCondition` branch instead — this top-level field is ignored for that mode.\n\nEchoed back on create/retrieve just like `segment_users` (it is persisted on the condition node itself in addition to the shadow segment), so a round-trip reflects exactly what you sent.\n","items":{"type":"array","items":{"$ref":"#/components/schemas/SegmentCondition"}}},"multi_conditions":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/FlowMultiCondition"},"description":"For `condition` with `action_type: \"multi_choice\"`."},"salesautomation_id":{"type":"string","nullable":true,"pattern":"^saut_[0-9A-HJKMNP-TV-Z]{26}$","description":"For `sales_automation` nodes. References a CRM automation created via `POST /v3/pipelines/{pipeline_id}/automations`."},"sales_automation":{"type":"object","nullable":true,"description":"For `sales_automation` nodes, instead of `salesautomation_id`: an inline CRM rule. v3 creates the rule and binds it to this node. Send `action` for one action or `actions` for several (run in order). Do not send a `trigger`; the flow decides when it runs.","properties":{"action":{"$ref":"#/components/schemas/SalesAutomationAction"},"actions":{"type":"array","items":{"$ref":"#/components/schemas/SalesAutomationAction"}}}},"webhook_url":{"type":"string","format":"uri","nullable":true,"description":"REQUIRED on `webhook` nodes — creating one without it returns 422. A webhook with no destination can never fire, and the dashboard refuses to save one for the same reason. Must be `https://` unless the account has `allow_http_webhooks: true`.\n\nGet the URL from the user. There is no sensible default and no way to infer it.\n"},"webhook_method":{"type":"string","enum":["GET","POST"],"default":"GET","description":"The flow worker only sends GET or POST; any other value is a 422 (it would silently go out as GET).","nullable":true},"webhook_payload_type":{"type":"string","enum":["json","form"],"default":"json","nullable":true},"webhook_fields":{"type":"array","nullable":true,"description":"REQUIRED on `webhook` nodes: at least one `{key, value}` pair with a non-empty `key` and `value` (`\"0\"` counts as empty). The flow worker builds the request only from such pairs and sends NOTHING when there are none — for GET (query string) as well as POST — so a node without one is a 422. Every entry must be an object with string `key` and `value`. `key` may use dot notation for nesting. Ask the user what the receiving system expects.\n","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string","description":"Supports `{placeholder}` interpolation from contact fields (e.g., `{first_name}`, `{email}`, `{data.custom_field}`)."}}}},"webhook_header_fields":{"type":"array","nullable":true,"description":"Optional request headers. Each entry needs a non-empty `key` and `value` (422 otherwise — the worker would drop it).","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}}}},"mariana_action":{"type":"object","nullable":true,"description":"Required for `mariana_action` nodes. Gives the enrolled contact something in the workroom's Mariana Tek studio. The contact is found by their Mariana id or exact email; with `if_not_found: create` a Mariana account is created from their email and name and Mariana emails them a set-password link. Each enrollment gives at most once. Amount and credit caps are the workroom's limits (default 100 and 20); values over them, or a malformed config, are rejected 422 so a saved node always runs.\n","required":["type"],"properties":{"type":{"type":"string","enum":["pack","class_credits","account_credit"]},"package_id":{"type":"string","description":"Mariana pack (package) id. `pack`: gives that pack's class credits with the pack's own expiry."},"package_name":{"type":"string","description":"Display name for the pack."},"credit_id":{"type":"string","description":"`class_credits`: Mariana credit type id."},"credit_name":{"type":"string"},"quantity":{"type":"integer","minimum":1,"description":"`class_credits`: number of credits (at most the workroom limit, default 20)."},"expiry_days":{"type":"string","description":"`class_credits`: whole days until the credits expire; empty for no expiry."},"amount":{"type":"number","description":"`account_credit`: amount to add, up to 2 decimals and the workroom limit (default 100)."},"currency":{"type":"string","description":"`account_credit`: 3-letter code, default USD."},"note":{"type":"string","maxLength":60,"description":"Shown on the credit in Mariana."},"if_not_found":{"type":"string","enum":["create","skip"],"default":"create"},"recipient":{"type":"string","enum":["contact","referrer"],"default":"contact","description":"`referrer` gives to the member who referred the contact (their `referred_by_id` in the same workroom, set by the referral intake) instead of the contact, once per enrollment. Use it in a referred friend's flow to reward the member."}}}}},"FlowNodeType":{"type":"string","enum":["email_campaign","sms_campaign","delay","condition","sales_automation","webhook","mariana_action"],"description":"The 7 node types the engine actually supports (`mariana_action` gives the contact a pack, class credits or account credit in the workroom's Mariana Tek studio). Richer vocab from the main spec (`send_message`, `tag`, `add_to_segment`, `update_contact`, `create_task`, `create_opportunity`, `wait_for_event`, `split`, `end`) is NOT implemented — express those via `sales_automation` (pointing at a CRM sub-automation) or return 501 `node_type_not_supported`. See Flow Engine companion doc §10.\n"},"CampaignId":{"type":"string","pattern":"^cam_[0-9a-f]{24}$"},"TemplateId":{"type":"string","pattern":"^tpl_[0-9a-f]{24}$"},"FlowConditionMode":{"type":"string","enum":["yes_no","multi_choice","wait_till_true"],"description":"`yes_no` — evaluates the `segment_users` predicate once, immediately, and branches: children set `parent_branch: \"yes\"` or `\"no\"` (see FlowNode's parent/child edges note). `multi_choice` — evaluates `multi_conditions` in order; the first match's slugified `value` becomes the child branch. `wait_till_true` — does NOT branch. It re-evaluates the SAME predicate, on the SAME node, on the engine's existing cron cadence, until it matches; only then does execution advance (linearly, via the ordinary `next` edge — there is no \"no\" child to fall through to). Confirmed against the dashboard/flow engine (`Cron.php`'s condition handling): while unmatched, the node is flagged `condition_repeat: true` and re-checked on the next cron pass rather than branching, and — unlike a `yes_no` match — a `wait_till_true` match never writes `operation_parent_type`/`operation_parent_id` on its action-story entry, confirming it has no yes/no children of its own.\n\n**Materialization (fixed — previously a known gap):** both `yes_no` and `wait_till_true` are evaluated by the engine against a legacy `yes_condition` field, which this API materializes from `segment_users` into a hidden shadow segment at creation time. `wait_till_true` is now included in that materialization the same way `yes_no` already was — a `wait_till_true` node created via this API is fully wired for the live cron to evaluate, not merely accepted and stored. Archiving a flow deletes these shadow segments (the node keeps `segment_users`, so duplicating the flow rebuilds them).\n"},"FlowMultiCondition":{"type":"object","required":["value"],"description":"One branch of a `multi_choice` condition. The engine evaluates each in order; the first `segment_users` match wins. Up to 6 regular branches plus one optional catch-all.\n\n**Storage.** Regular branches are stored as `Condition A`..`Condition F` in the order given, with your label kept as `name_alias` (what the dashboard shows). Children may reference a branch by your label, by `Condition A`, or by `condition_a`.\n\n**Catch-all.** Mark a branch with `is_other: true` (or `value: \"Other\"` / `\"Condition Other\"`). It is stored exactly as the dashboard stores it — `{value: \"Condition Other\", segment_users: [{segment: \"other\"}]}` — always last, and it matches every contact no earlier branch matched; any `segment_users` you give it are ignored (warning `other_branch_conditions_ignored`). Children reference it as `Other` / `condition_other`. Without a catch-all, a contact who matches no branch does not advance. More than 6 regular branches, or two catch-alls, is a 422. Reads echo `is_other: true` on the catch-all.\n","properties":{"value":{"type":"string","description":"Human-readable branch name (stored as `name_alias`; `value` becomes `Condition A`..`F`). `Other` / `Condition Other` marks the catch-all."},"is_other":{"type":"boolean","default":false,"description":"Marks this branch as the catch-all (see above)."},"name_alias":{"type":"string","description":"Display label. Set from `value` on write."},"segment_users":{"type":"array","items":{"$ref":"#/components/schemas/SegmentCondition"},"description":"Segment DSL conditions (see the Segment Query DSL doc). Ignored on the catch-all branch, which is stored with `[{segment: \"other\"}]`.\n\n**Before constructing this**: call `describeSegmentSchema` (or `GET /v3/segments/schema`) and copy each condition's `condition_template` verbatim, same as the condition node's own top-level `segment_users` — don't invent field/operator tokens here just because this is a nested branch.\n"},"with_or_segment_users":{"type":"array","description":"Alternate inclusion groups for THIS branch only, same OR-logic semantics as Segments' `query.with_or_segment_users`: each inner array is a set of conditions ANDed together, and the outer array is OR-joined with this branch's own `segment_users` and every other group here. Use this to build \"criteria A OR criteria B\" matching for one multi_choice branch without touching its `segment_users`. Optional; has no effect on the `Condition Other` fallback branch or on any other branch's matching.\n","items":{"type":"array","items":{"$ref":"#/components/schemas/SegmentCondition"}}}}},"SalesAutomationAction":{"type":"object","required":["type"],"description":"Polymorphic on `type`. 13 action types available — see `describeFlowSchema` for the full guide + params per action.\n","properties":{"type":{"type":"string","enum":["tags","remove_tags","task","add_stage","move_stage","sync_stage","remove_stage","assign","remove_assign","status","priority","add_note","enroll_in_flow"]},"tag_names":{"type":"array","items":{"type":"string"},"description":"For `tags` / `remove_tags`."},"task_name":{"type":"string","description":"For `task`."},"description":{"type":"string","description":"For `task`."},"due_at":{"$ref":"#/components/schemas/Timestamp","description":"For `task` (write only; converted to `due_in_days`)."},"due_in_days":{"type":"integer","description":"For `task`. Days from the trigger until the task is due. Default 1."},"assignee_staff_id":{"$ref":"#/components/schemas/StaffId","description":"For `task`: one responsible (\"Specific\"). Omit both assignee fields for the contact owner (\"Owner\")."},"assignee_staff_ids":{"type":"array","items":{"$ref":"#/components/schemas/StaffId"},"description":"For `task`: round-robin across these staff."},"assignee_mode":{"type":"string","readOnly":true,"enum":["Owner","Specific","Round Robin"],"description":"For `task`, read only."},"task_type":{"type":"string","description":"For `task`: task type id (`tst_…`). Defaults to the workroom's first type."},"stage_id":{"$ref":"#/components/schemas/StageId","description":"For stage actions. Required: a stage action with no valid stage is rejected (422), since the worker cannot run it."},"staff_ids":{"type":"array","items":{"$ref":"#/components/schemas/StaffId"},"description":"For `assign` / `remove_assign`. Required (non-empty)."},"distribution":{"type":"string","enum":["All","Round Robin"],"description":"For `assign`. Other values (including the dashboard's \"Round Robin By Day\", which needs a per-day roster) are stored as `All` with a warning."},"reassign":{"type":"boolean","default":false,"description":"For `assign`: true replaces a contact's existing responsible; false only fills unassigned contacts."},"value":{"type":"string","description":"For `status` / `priority`."},"note":{"type":"string","description":"For `add_note`."},"flow_id":{"type":"string","description":"For `enroll_in_flow`."},"applies_to":{"type":"string","description":"Segment scope — usually \"All\" or a segment name.","default":"All"}}},"StaffId":{"type":"string","pattern":"^usr_[0-9a-f]{24}$","description":"A staff user (from the legacy `users` collection). Used for `owner_id`, `responsible_id`, `created_by`, `assigned_to`, etc."},"StageId":{"type":"string","pattern":"^stg_[0-9a-f]{24}$"},"FlowStats":{"type":"object","description":"Run counters. `active_runs` and `completed_runs` are current state and do not move with the analytics window; `entered` and `unenrolled` are windowed.\n","properties":{"active_runs":{"type":"integer","minimum":0,"description":"Runs open right now."},"completed_runs":{"type":"integer","minimum":0,"description":"Runs finished","all time.":null},"entered":{"type":"integer","minimum":0,"description":"Contacts enrolled within the window."},"unenrolled":{"type":"integer","minimum":0,"description":"Contacts unenrolled within the window."},"entered_last_30d":{"type":"integer","minimum":0,"deprecated":true,"description":"Same value as `entered`. Kept for existing callers; the name is only accurate when the window is the default 30 days."},"unenrolled_last_30d":{"type":"integer","minimum":0,"deprecated":true,"description":"Same value as `unenrolled`."}}},"Timezone":{"type":"string","description":"IANA timezone name."},"UserId":{"type":"string","pattern":"^usr_[0-9A-HJKMNP-TV-Z]{26}$"},"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}},"responses":{"NotFound":{"description":"The resource doesn't exist or isn't visible to this caller.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/flows/{id}/duplicate":{"post":{"tags":["Flows"],"operationId":"duplicateFlow","summary":"Duplicate a flow.","description":"Creates a new `draft` flow with the same entry, nodes, and conversion goals. Stats are NOT copied. As in the dashboard's clone, every message node gets its own fresh shadow campaign (same content, `drafted`), every `yes_no`/`wait_till_true` condition its own hidden condition segment, and every `sales_automation` node its own CRM rule (inactive until the copy is published) — nothing in the copy references the original's parts, so editing or archiving one flow never touches the other. Works on archived flows (the way to bring one back).\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Name for the duplicate. Defaults to `\"<source name> (copy)\"`."}}}}}},"responses":{"201":{"description":"Duplicate created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Flow"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## Manually enroll a contact.

> Enrolls one contact into the flow, bypassing segment-based entry. Still respects \`unenroll\_segment\_ids\` — a match aborts the run at the next step. \`Idempotency-Key\` is strongly recommended.\
> \
> Matches the dashboard's "enter into flow": a contact gets a new run only if they have no run for this flow, unless (a) they were removed with \`POST /unenroll\` — that run is replaced — or (b) \`entry.reenroll\` is true and their finished run started before today (account timezone). The first step runs on the flow worker's next pass. The response may carry \`warnings\[]\`.\
> \
> \*\*Starts messaging this contact.\*\* Enrolling runs the flow's steps against a real person, including its sends.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Flows","description":"Multi-step automations. Enrollment is driven by segment membership. 7 node types are supported by the engine — see the Flow Engine companion doc for the full model, including the versioning and in-flight-edit caveats."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["flows:write"]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"},"OAuth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE. Use for third-party apps acting on behalf of a Gleantap user.\nAuthorization Code + PKCE is the only supported grant for interactive flows; refresh_token grant is supported and rotates on every use.\n","flows":{"authorizationCode":{"authorizationUrl":"https://api.gleantap.com/v3/oauth/authorize","tokenUrl":"https://api.gleantap.com/v3/oauth/token","refreshUrl":"https://api.gleantap.com/v3/oauth/token","scopes":{"contacts:read":"Read contact records.","contacts:write":"Create, update, delete contacts (soft delete).","contacts:delete_hard":"Hard-delete contacts (irreversible).","events:read":"Read event records.","events:write":"Record events.","segments:read":"Read segments and preview membership.","segments:write":"Create, update, delete segments.","templates:read":"Read message templates.","templates:write":"Create, update, delete templates.","campaigns:read":"Read campaigns and analytics.","campaigns:write":"Create, schedule, cancel campaigns.","flows:read":"Read flow definitions and analytics.","flows:write":"Create, edit, publish flows.","flows:publish":"Publish/unpublish flows (separately scoped for governance).","messaging:send":"Send transactional messages (SMS, email, voice).","conversations:read":"Read conversations and messages.","conversations:write":"Send messages, close/reopen conversations.","webhooks:manage":"Create, update, delete webhook endpoints.","forms:manage":"Create, update, delete, publish, duplicate forms; list submissions and rotate the submission_token.","campaigns:manage":"Create, schedule, cancel, duplicate campaigns; read recipients and analytics. (Supersedes the earlier `campaigns:read` + `campaigns:write` split; the split scopes still work.)","admin:impersonate:read":"Gleantap staff only — read any customer account named via `Gleantap-Account`. Not available through dynamic client registration.","admin:impersonate:write":"Gleantap staff only — required for any state-changing method while impersonating. Not available through dynamic client registration."}}}}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"WorkroomQuery":{"name":"workroom","in":"query","required":false,"description":"Same semantics as the `Gleantap-Workroom` header, including that a write should never be sent without a workroom the user actually chose, and that an omitted workroom scopes a read to the account default rather than spanning the account. Prefer this on GETs so proxies and caches can key on it. Accepts name, prefixed ID, raw hex, or `all`.\n","schema":{"type":"string"}},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"description":"A unique key (≤255 chars) chosen by the client. Replays with the same key + same body return the cached response. Replays with the same key + different body return 409 `idempotency_conflict`. Required on messaging sends and bulk operations; recommended elsewhere.\n","schema":{"type":"string","maxLength":255}}},"schemas":{"FlowEnrollRequest":{"type":"object","required":["contact_id"],"description":"Manually enroll a contact. Bypasses segment-based entry evaluation but still respects `unenroll_segment_ids` (a match will terminate the run at the next step).","properties":{"contact_id":{"$ref":"#/components/schemas/ContactId"},"execute_immediately":{"type":"boolean","default":false,"description":"When `true`, the flow worker is triggered for this contact right away, so the first step runs within seconds instead of on the worker's next pass. The response waits up to about 3 seconds for that step, so it usually shows `current_action_step` >= 1 and the step in `action_story`; if the worker is slower, the run is returned still pending and `listFlowRuns` shows its progress."}}},"ContactId":{"type":"string","pattern":"^con_[0-9a-f]{24}$|^external_id:[^/]+$","description":"A contact ID. Accepts either the native prefixed id (`con_<24-hex>`) or an external-ID reference (`external_id:<your_id>`).\n"},"FlowRun":{"type":"object","description":"A single contact's traversal of a flow (`userflowactions` in the engine). Immutable after `complete` — re-enrollment produces a new run and archives the old to history.\n","required":["id","object","flow_id","contact_id","status","current_action_step","created_at"],"properties":{"id":{"type":"string","description":"Run ID — `flr_<24-hex>`. Stable for the lifetime of the run; re-enrollment creates a new run with a new ID.","pattern":"^flr_[0-9a-f]{24}$"},"object":{"type":"string","const":"flow_run"},"flow_id":{"$ref":"#/components/schemas/FlowId"},"contact_id":{"$ref":"#/components/schemas/ContactId"},"status":{"$ref":"#/components/schemas/FlowRunStatus"},"current_action_step":{"type":"integer","minimum":0},"current_action_type":{"$ref":"#/components/schemas/FlowNodeType","nullable":true},"current_action_name":{"type":"string","nullable":true},"current_action_datetime":{"$ref":"#/components/schemas/Timestamp","nullable":true},"flow_complete_reason":{"type":"string","nullable":true,"description":"Populated on complete. Common values: `finished`, `unenrolled`, `unenroll_segment_matched`, `end_date_reached`, `node_missing` (a node was deleted while the contact was mid-flight — see FlowUpdate description).\n"},"reenroll":{"type":"boolean","description":"True if this run is a re-enrollment of a previously-completed contact."},"action_story":{"type":"array","items":{"$ref":"#/components/schemas/FlowActionStoryEntry"}},"conversion_ids":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"flow_operation_step":{"type":"integer"},"deleted":{"type":"boolean"}}}},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"}}},"FlowId":{"type":"string","pattern":"^flw_[0-9A-HJKMNP-TV-Z]{26}$"},"FlowRunStatus":{"type":"string","enum":["pending","processing","complete"]},"FlowNodeType":{"type":"string","enum":["email_campaign","sms_campaign","delay","condition","sales_automation","webhook","mariana_action"],"description":"The 7 node types the engine actually supports (`mariana_action` gives the contact a pack, class credits or account credit in the workroom's Mariana Tek studio). Richer vocab from the main spec (`send_message`, `tag`, `add_to_segment`, `update_contact`, `create_task`, `create_opportunity`, `wait_for_event`, `split`, `end`) is NOT implemented — express those via `sales_automation` (pointing at a CRM sub-automation) or return 501 `node_type_not_supported`. See Flow Engine companion doc §10.\n"},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"FlowActionStoryEntry":{"type":"object","description":"One step traversed by a contact. Present in run records.","properties":{"operation_step_id":{"type":"string"},"operation_type":{"$ref":"#/components/schemas/FlowNodeType"},"operation_step":{"type":"integer"},"action_name":{"type":"string","nullable":true},"action_datetime":{"$ref":"#/components/schemas/Timestamp"},"campaign_id":{"$ref":"#/components/schemas/CampaignId","nullable":true},"salesautomation_id":{"type":"string","nullable":true},"matched_condition":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/SegmentCondition"}},"operation_parent_type":{"type":"string","nullable":true},"webhook_url":{"type":"string","nullable":true},"webhook_status":{"type":"integer","nullable":true},"webhook_response":{"type":"string","nullable":true}}},"CampaignId":{"type":"string","pattern":"^cam_[0-9a-f]{24}$"},"SegmentCondition":{"type":"object","description":"A single condition in a dynamic segment query. Shape and operator vocabulary are documented in the Segment Query DSL companion doc — the query language supports 28 segment types (Attributes, Tags, Event Trigger, External Events, Segments, SalesAttributes, Forms, Flows, Optin, and more) and 60+ operators. This schema is intentionally loose to accommodate that surface; the server validates the concrete shape.\n","required":["segment","operator"],"additionalProperties":true,"properties":{"segment":{"type":"string","description":"Segment-type discriminator. Full inventory in the DSL doc. Common values include `Attributes`, `Tags`, `Country`, `City`, `Event Trigger`, `External Events`, `Segments`, `SalesAttributes`, `Forms`, `Flows`, `SMS Optin`, `SMS Opted Out`, `Email Topics`, `Add Date`, `Last Access`.\n"},"data":{"type":"string","description":"Field or attribute within the segment type. E.g., `first_name`, `city`, `sales.pipeline.stage`.","nullable":true},"event":{"type":"string","description":"Event name — used only when `segment` is `Event Trigger`.","nullable":true},"operator":{"type":"string","description":"Operator vocabulary. Full list in the DSL doc. Common: `=`, `!=`, `<`, `>` (numeric — on a Date field they are stored as `Before`/`After`), `Contains`, `Does Not Contain`, `Is One Of`, `Is Not One Of`, `Is Empty`, `Is Not Empty`, `Exists`, `Does Not Exist`, `Is True`, `Is False`, `InLast`, `OverDays`, `InNext`, `Before`, `After`, `IsToday`, `DayInNext`, `DayInMonth`, `Is In Segment`, `Is Not In Segment`, `Has Filled a Form`. For recurring day-of-year fields (`data_type: Day`, e.g. Birthday) use the `DayInNext`/`DayInNextXY`/`DayInMonth` family — not the absolute-date `InNext`/`=` — so \"birthday in the next N days\" recurs every year (see `describeSegmentSchema`).\n\n`Exists`/`Does Not Exist` vs `Is Not Empty`/`Is Empty`: both check for a populated value and are usually close in practice, but `Exists` is what the dashboard UI itself uses when a user says a field \"exists\" - prefer `Exists`/`Does Not Exist` for that phrasing, especially inside `with_or_segment_users`, to match what the UI would produce for the same request.\n"},"value":{"type":["string","number","boolean","array","null"],"description":"The operand. Which type applies depends on the operator: a scalar for `=` and `Contains`, an array (or comma-separated string) for `Is One Of`, a number for count comparisons, and omitted entirely for `Exists` / `Is Empty`.\n"},"value2":{"type":["string","number","null"],"description":"Secondary operand for two-parameter conditions (currently `External Events` count comparison and `SalesAttributes` pipeline-stage filter)."},"operator2":{"type":"string","description":"Secondary operator for two-parameter conditions.","nullable":true},"value2_id":{"type":"array","items":{"type":"string"},"nullable":true,"description":"Object-ID list for stage-title disambiguation on `SalesAttributes`."},"data_type":{"type":"string","enum":["String","Numeric","Date","List"],"nullable":true,"description":"Optional hint for the engine's disambiguation logic."},"dataAlias":{"type":"string","nullable":true,"description":"Human-readable alias shown in the UI. Not evaluated."}}},"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}},"responses":{"BadRequest":{"description":"Request could not be parsed or failed validation.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"NotFound":{"description":"The resource doesn't exist or isn't visible to this caller.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/flows/{id}/enroll":{"post":{"tags":["Flows"],"operationId":"enrollContactInFlow","summary":"Manually enroll a contact.","description":"Enrolls one contact into the flow, bypassing segment-based entry. Still respects `unenroll_segment_ids` — a match aborts the run at the next step. `Idempotency-Key` is strongly recommended.\n\nMatches the dashboard's \"enter into flow\": a contact gets a new run only if they have no run for this flow, unless (a) they were removed with `POST /unenroll` — that run is replaced — or (b) `entry.reenroll` is true and their finished run started before today (account timezone). The first step runs on the flow worker's next pass. The response may carry `warnings[]`.\n\n**Starts messaging this contact.** Enrolling runs the flow's steps against a real person, including its sends.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlowEnrollRequest"}}}},"responses":{"201":{"description":"Contact enrolled. Returns the new run.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlowRun"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"`already_enrolled` (a run is in flight), `already_completed` (finished and `entry.reenroll` is false), or `reenroll_same_day` (re-enroll allowed but the finished run started today).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}}}
```

## Manually unenroll a contact.

> Terminates the in-flight run for one contact with \`flow\_status: "complete"\`, \`flow\_unenrolled: true\` and \`flow\_complete\_reason: \<reason>\`, exactly as the dashboard's "remove from flow" does: the contact is also marked as manually removed (so segment entry does not put them straight back in) and their profile's flow entry is completed. Counted in analytics \`unenrolled\`. Enrolling them again with \`POST /enroll\` is allowed. Idempotent: no-op when the contact has no in-flight run.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Flows","description":"Multi-step automations. Enrollment is driven by segment membership. 7 node types are supported by the engine — see the Flow Engine companion doc for the full model, including the versioning and in-flight-edit caveats."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["flows:write"]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"},"OAuth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE. Use for third-party apps acting on behalf of a Gleantap user.\nAuthorization Code + PKCE is the only supported grant for interactive flows; refresh_token grant is supported and rotates on every use.\n","flows":{"authorizationCode":{"authorizationUrl":"https://api.gleantap.com/v3/oauth/authorize","tokenUrl":"https://api.gleantap.com/v3/oauth/token","refreshUrl":"https://api.gleantap.com/v3/oauth/token","scopes":{"contacts:read":"Read contact records.","contacts:write":"Create, update, delete contacts (soft delete).","contacts:delete_hard":"Hard-delete contacts (irreversible).","events:read":"Read event records.","events:write":"Record events.","segments:read":"Read segments and preview membership.","segments:write":"Create, update, delete segments.","templates:read":"Read message templates.","templates:write":"Create, update, delete templates.","campaigns:read":"Read campaigns and analytics.","campaigns:write":"Create, schedule, cancel campaigns.","flows:read":"Read flow definitions and analytics.","flows:write":"Create, edit, publish flows.","flows:publish":"Publish/unpublish flows (separately scoped for governance).","messaging:send":"Send transactional messages (SMS, email, voice).","conversations:read":"Read conversations and messages.","conversations:write":"Send messages, close/reopen conversations.","webhooks:manage":"Create, update, delete webhook endpoints.","forms:manage":"Create, update, delete, publish, duplicate forms; list submissions and rotate the submission_token.","campaigns:manage":"Create, schedule, cancel, duplicate campaigns; read recipients and analytics. (Supersedes the earlier `campaigns:read` + `campaigns:write` split; the split scopes still work.)","admin:impersonate:read":"Gleantap staff only — read any customer account named via `Gleantap-Account`. Not available through dynamic client registration.","admin:impersonate:write":"Gleantap staff only — required for any state-changing method while impersonating. Not available through dynamic client registration."}}}}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"WorkroomQuery":{"name":"workroom","in":"query","required":false,"description":"Same semantics as the `Gleantap-Workroom` header, including that a write should never be sent without a workroom the user actually chose, and that an omitted workroom scopes a read to the account default rather than spanning the account. Prefer this on GETs so proxies and caches can key on it. Accepts name, prefixed ID, raw hex, or `all`.\n","schema":{"type":"string"}}},"schemas":{"FlowUnenrollRequest":{"type":"object","required":["contact_id"],"description":"Manually unenroll a contact. Idempotent — no-op if the contact isn't in-flight.","properties":{"contact_id":{"$ref":"#/components/schemas/ContactId"},"reason":{"type":"string","maxLength":500,"description":"Free-form reason stored on the run's `flow_complete_reason`."}}},"ContactId":{"type":"string","pattern":"^con_[0-9a-f]{24}$|^external_id:[^/]+$","description":"A contact ID. Accepts either the native prefixed id (`con_<24-hex>`) or an external-ID reference (`external_id:<your_id>`).\n"},"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}},"responses":{"NotFound":{"description":"The resource doesn't exist or isn't visible to this caller.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/flows/{id}/unenroll":{"post":{"tags":["Flows"],"operationId":"unenrollContactFromFlow","summary":"Manually unenroll a contact.","description":"Terminates the in-flight run for one contact with `flow_status: \"complete\"`, `flow_unenrolled: true` and `flow_complete_reason: <reason>`, exactly as the dashboard's \"remove from flow\" does: the contact is also marked as manually removed (so segment entry does not put them straight back in) and their profile's flow entry is completed. Counted in analytics `unenrolled`. Enrolling them again with `POST /enroll` is allowed. Idempotent: no-op when the contact has no in-flight run.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlowUnenrollRequest"}}}},"responses":{"200":{"description":"Unenrolled (or already not in-flight)."},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## Dry-run the flow for a specific contact.

> Evaluates every node without triggering real sends, webhooks, or CRM automations. Returns the traversal that a real run would take. Useful for validating condition branches and delay math against a real contact's data.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Flows","description":"Multi-step automations. Enrollment is driven by segment membership. 7 node types are supported by the engine — see the Flow Engine companion doc for the full model, including the versioning and in-flight-edit caveats."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["flows:read"]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"},"OAuth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE. Use for third-party apps acting on behalf of a Gleantap user.\nAuthorization Code + PKCE is the only supported grant for interactive flows; refresh_token grant is supported and rotates on every use.\n","flows":{"authorizationCode":{"authorizationUrl":"https://api.gleantap.com/v3/oauth/authorize","tokenUrl":"https://api.gleantap.com/v3/oauth/token","refreshUrl":"https://api.gleantap.com/v3/oauth/token","scopes":{"contacts:read":"Read contact records.","contacts:write":"Create, update, delete contacts (soft delete).","contacts:delete_hard":"Hard-delete contacts (irreversible).","events:read":"Read event records.","events:write":"Record events.","segments:read":"Read segments and preview membership.","segments:write":"Create, update, delete segments.","templates:read":"Read message templates.","templates:write":"Create, update, delete templates.","campaigns:read":"Read campaigns and analytics.","campaigns:write":"Create, schedule, cancel campaigns.","flows:read":"Read flow definitions and analytics.","flows:write":"Create, edit, publish flows.","flows:publish":"Publish/unpublish flows (separately scoped for governance).","messaging:send":"Send transactional messages (SMS, email, voice).","conversations:read":"Read conversations and messages.","conversations:write":"Send messages, close/reopen conversations.","webhooks:manage":"Create, update, delete webhook endpoints.","forms:manage":"Create, update, delete, publish, duplicate forms; list submissions and rotate the submission_token.","campaigns:manage":"Create, schedule, cancel, duplicate campaigns; read recipients and analytics. (Supersedes the earlier `campaigns:read` + `campaigns:write` split; the split scopes still work.)","admin:impersonate:read":"Gleantap staff only — read any customer account named via `Gleantap-Account`. Not available through dynamic client registration.","admin:impersonate:write":"Gleantap staff only — required for any state-changing method while impersonating. Not available through dynamic client registration."}}}}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"WorkroomQuery":{"name":"workroom","in":"query","required":false,"description":"Same semantics as the `Gleantap-Workroom` header, including that a write should never be sent without a workroom the user actually chose, and that an omitted workroom scopes a read to the account default rather than spanning the account. Prefer this on GETs so proxies and caches can key on it. Accepts name, prefixed ID, raw hex, or `all`.\n","schema":{"type":"string"}}},"schemas":{"FlowTestRunRequest":{"type":"object","required":["contact_id"],"description":"Dry-run the flow for a specific contact. Renders and evaluates every node without triggering sends, webhooks, or CRM automations — returns the traversal that would happen.","properties":{"contact_id":{"$ref":"#/components/schemas/ContactId"},"skip_delays":{"type":"boolean","default":true,"description":"If true (default), treat every `delay` node as if its wait had elapsed. Set false to compute the actual delays."}}},"ContactId":{"type":"string","pattern":"^con_[0-9a-f]{24}$|^external_id:[^/]+$","description":"A contact ID. Accepts either the native prefixed id (`con_<24-hex>`) or an external-ID reference (`external_id:<your_id>`).\n"},"FlowTestRunResponse":{"type":"object","properties":{"object":{"type":"string","const":"flow_test_run"},"contact_id":{"$ref":"#/components/schemas/ContactId"},"traversal":{"type":"array","items":{"type":"object","properties":{"node_id":{"type":"string"},"node_type":{"$ref":"#/components/schemas/FlowNodeType"},"action_name":{"type":"string","nullable":true},"simulated_at":{"$ref":"#/components/schemas/Timestamp"},"branch_taken":{"type":"string","nullable":true,"description":"For condition nodes: which branch the contact's current data matched — `yes`/`no`, `next` for a met wait-until-true, or the multi-choice branch key (`condition_a`, …, `condition_other`). Null when the contact would wait at this step, and the traversal stops there."},"would_send":{"type":"boolean","description":"For send_message/webhook nodes: whether a real run would send."},"notes":{"type":"string","nullable":true,"description":"For condition nodes: `condition_matched`, `condition_not_matched`, `condition_met`, `no_condition_matched_took_other`, `condition_not_met_contact_would_wait`, `no_condition_matched_contact_would_wait`, `condition_has_no_rules`, or `condition_eval_failed:<reason>`."},"warnings":{"type":"array","items":{"type":"string"},"description":"Condition evaluation caveats, e.g. external-event count thresholds that are approximated."}}}}}},"FlowNodeType":{"type":"string","enum":["email_campaign","sms_campaign","delay","condition","sales_automation","webhook","mariana_action"],"description":"The 7 node types the engine actually supports (`mariana_action` gives the contact a pack, class credits or account credit in the workroom's Mariana Tek studio). Richer vocab from the main spec (`send_message`, `tag`, `add_to_segment`, `update_contact`, `create_task`, `create_opportunity`, `wait_for_event`, `split`, `end`) is NOT implemented — express those via `sales_automation` (pointing at a CRM sub-automation) or return 501 `node_type_not_supported`. See Flow Engine companion doc §10.\n"},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}},"responses":{"BadRequest":{"description":"Request could not be parsed or failed validation.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"NotFound":{"description":"The resource doesn't exist or isn't visible to this caller.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/flows/{id}/test_run":{"post":{"tags":["Flows"],"operationId":"testRunFlow","summary":"Dry-run the flow for a specific contact.","description":"Evaluates every node without triggering real sends, webhooks, or CRM automations. Returns the traversal that a real run would take. Useful for validating condition branches and delay math against a real contact's data.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlowTestRunRequest"}}}},"responses":{"200":{"description":"Simulated traversal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlowTestRunResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## List runs (per-contact traversals) for a flow.

> Paginated list of \`userflowactions\` rows for this flow. Common filters: \`?filter\[status]=processing\` (in-flight), \`?filter\[status]=complete\`, \`?filter\[contact\_id]=\`, \`?filter\[flow\_complete\_reason]=unenrolled\`. Use \`?include\_history=true\` to also include archived runs from previous re-enrollments.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Flows","description":"Multi-step automations. Enrollment is driven by segment membership. 7 node types are supported by the engine — see the Flow Engine companion doc for the full model, including the versioning and in-flight-edit caveats."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["flows:read"]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"},"OAuth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE. Use for third-party apps acting on behalf of a Gleantap user.\nAuthorization Code + PKCE is the only supported grant for interactive flows; refresh_token grant is supported and rotates on every use.\n","flows":{"authorizationCode":{"authorizationUrl":"https://api.gleantap.com/v3/oauth/authorize","tokenUrl":"https://api.gleantap.com/v3/oauth/token","refreshUrl":"https://api.gleantap.com/v3/oauth/token","scopes":{"contacts:read":"Read contact records.","contacts:write":"Create, update, delete contacts (soft delete).","contacts:delete_hard":"Hard-delete contacts (irreversible).","events:read":"Read event records.","events:write":"Record events.","segments:read":"Read segments and preview membership.","segments:write":"Create, update, delete segments.","templates:read":"Read message templates.","templates:write":"Create, update, delete templates.","campaigns:read":"Read campaigns and analytics.","campaigns:write":"Create, schedule, cancel campaigns.","flows:read":"Read flow definitions and analytics.","flows:write":"Create, edit, publish flows.","flows:publish":"Publish/unpublish flows (separately scoped for governance).","messaging:send":"Send transactional messages (SMS, email, voice).","conversations:read":"Read conversations and messages.","conversations:write":"Send messages, close/reopen conversations.","webhooks:manage":"Create, update, delete webhook endpoints.","forms:manage":"Create, update, delete, publish, duplicate forms; list submissions and rotate the submission_token.","campaigns:manage":"Create, schedule, cancel, duplicate campaigns; read recipients and analytics. (Supersedes the earlier `campaigns:read` + `campaigns:write` split; the split scopes still work.)","admin:impersonate:read":"Gleantap staff only — read any customer account named via `Gleantap-Account`. Not available through dynamic client registration.","admin:impersonate:write":"Gleantap staff only — required for any state-changing method while impersonating. Not available through dynamic client registration."}}}}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"WorkroomQuery":{"name":"workroom","in":"query","required":false,"description":"Same semantics as the `Gleantap-Workroom` header, including that a write should never be sent without a workroom the user actually chose, and that an omitted workroom scopes a read to the account default rather than spanning the account. Prefer this on GETs so proxies and caches can key on it. Accepts name, prefixed ID, raw hex, or `all`.\n","schema":{"type":"string"}},"LimitParam":{"name":"limit","in":"query","required":false,"description":"Page size. Default 25, max 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},"CursorParam":{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from a prior response's `next_cursor`, to fetch the NEXT page (alias - `after`). On listContacts and listSegmentContacts, use `before` with a `prev_cursor` to page backward; other list endpoints are forward-only.","schema":{"type":"string"}}},"schemas":{"ListEnvelope":{"type":"object","required":["object","data","has_more","next_cursor","prev_cursor"],"properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"type":"object"},"description":"The page of results. Item type varies per endpoint — see the specific response schema."},"has_more":{"type":"boolean","description":"True if additional records exist beyond this page."},"next_cursor":{"type":"string","nullable":true,"description":"Opaque cursor for the next page. Null on the last page."},"prev_cursor":{"type":"string","nullable":true,"description":"Cursor for the previous page. Supported on `listContacts` and `listSegmentContacts`: pass it back as `?before=...` to page backward; `null` on the first page. On every other list endpoint paging is forward-only and this is always `null`."}}},"FlowRun":{"type":"object","description":"A single contact's traversal of a flow (`userflowactions` in the engine). Immutable after `complete` — re-enrollment produces a new run and archives the old to history.\n","required":["id","object","flow_id","contact_id","status","current_action_step","created_at"],"properties":{"id":{"type":"string","description":"Run ID — `flr_<24-hex>`. Stable for the lifetime of the run; re-enrollment creates a new run with a new ID.","pattern":"^flr_[0-9a-f]{24}$"},"object":{"type":"string","const":"flow_run"},"flow_id":{"$ref":"#/components/schemas/FlowId"},"contact_id":{"$ref":"#/components/schemas/ContactId"},"status":{"$ref":"#/components/schemas/FlowRunStatus"},"current_action_step":{"type":"integer","minimum":0},"current_action_type":{"$ref":"#/components/schemas/FlowNodeType","nullable":true},"current_action_name":{"type":"string","nullable":true},"current_action_datetime":{"$ref":"#/components/schemas/Timestamp","nullable":true},"flow_complete_reason":{"type":"string","nullable":true,"description":"Populated on complete. Common values: `finished`, `unenrolled`, `unenroll_segment_matched`, `end_date_reached`, `node_missing` (a node was deleted while the contact was mid-flight — see FlowUpdate description).\n"},"reenroll":{"type":"boolean","description":"True if this run is a re-enrollment of a previously-completed contact."},"action_story":{"type":"array","items":{"$ref":"#/components/schemas/FlowActionStoryEntry"}},"conversion_ids":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"flow_operation_step":{"type":"integer"},"deleted":{"type":"boolean"}}}},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"}}},"FlowId":{"type":"string","pattern":"^flw_[0-9A-HJKMNP-TV-Z]{26}$"},"ContactId":{"type":"string","pattern":"^con_[0-9a-f]{24}$|^external_id:[^/]+$","description":"A contact ID. Accepts either the native prefixed id (`con_<24-hex>`) or an external-ID reference (`external_id:<your_id>`).\n"},"FlowRunStatus":{"type":"string","enum":["pending","processing","complete"]},"FlowNodeType":{"type":"string","enum":["email_campaign","sms_campaign","delay","condition","sales_automation","webhook","mariana_action"],"description":"The 7 node types the engine actually supports (`mariana_action` gives the contact a pack, class credits or account credit in the workroom's Mariana Tek studio). Richer vocab from the main spec (`send_message`, `tag`, `add_to_segment`, `update_contact`, `create_task`, `create_opportunity`, `wait_for_event`, `split`, `end`) is NOT implemented — express those via `sales_automation` (pointing at a CRM sub-automation) or return 501 `node_type_not_supported`. See Flow Engine companion doc §10.\n"},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"FlowActionStoryEntry":{"type":"object","description":"One step traversed by a contact. Present in run records.","properties":{"operation_step_id":{"type":"string"},"operation_type":{"$ref":"#/components/schemas/FlowNodeType"},"operation_step":{"type":"integer"},"action_name":{"type":"string","nullable":true},"action_datetime":{"$ref":"#/components/schemas/Timestamp"},"campaign_id":{"$ref":"#/components/schemas/CampaignId","nullable":true},"salesautomation_id":{"type":"string","nullable":true},"matched_condition":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/SegmentCondition"}},"operation_parent_type":{"type":"string","nullable":true},"webhook_url":{"type":"string","nullable":true},"webhook_status":{"type":"integer","nullable":true},"webhook_response":{"type":"string","nullable":true}}},"CampaignId":{"type":"string","pattern":"^cam_[0-9a-f]{24}$"},"SegmentCondition":{"type":"object","description":"A single condition in a dynamic segment query. Shape and operator vocabulary are documented in the Segment Query DSL companion doc — the query language supports 28 segment types (Attributes, Tags, Event Trigger, External Events, Segments, SalesAttributes, Forms, Flows, Optin, and more) and 60+ operators. This schema is intentionally loose to accommodate that surface; the server validates the concrete shape.\n","required":["segment","operator"],"additionalProperties":true,"properties":{"segment":{"type":"string","description":"Segment-type discriminator. Full inventory in the DSL doc. Common values include `Attributes`, `Tags`, `Country`, `City`, `Event Trigger`, `External Events`, `Segments`, `SalesAttributes`, `Forms`, `Flows`, `SMS Optin`, `SMS Opted Out`, `Email Topics`, `Add Date`, `Last Access`.\n"},"data":{"type":"string","description":"Field or attribute within the segment type. E.g., `first_name`, `city`, `sales.pipeline.stage`.","nullable":true},"event":{"type":"string","description":"Event name — used only when `segment` is `Event Trigger`.","nullable":true},"operator":{"type":"string","description":"Operator vocabulary. Full list in the DSL doc. Common: `=`, `!=`, `<`, `>` (numeric — on a Date field they are stored as `Before`/`After`), `Contains`, `Does Not Contain`, `Is One Of`, `Is Not One Of`, `Is Empty`, `Is Not Empty`, `Exists`, `Does Not Exist`, `Is True`, `Is False`, `InLast`, `OverDays`, `InNext`, `Before`, `After`, `IsToday`, `DayInNext`, `DayInMonth`, `Is In Segment`, `Is Not In Segment`, `Has Filled a Form`. For recurring day-of-year fields (`data_type: Day`, e.g. Birthday) use the `DayInNext`/`DayInNextXY`/`DayInMonth` family — not the absolute-date `InNext`/`=` — so \"birthday in the next N days\" recurs every year (see `describeSegmentSchema`).\n\n`Exists`/`Does Not Exist` vs `Is Not Empty`/`Is Empty`: both check for a populated value and are usually close in practice, but `Exists` is what the dashboard UI itself uses when a user says a field \"exists\" - prefer `Exists`/`Does Not Exist` for that phrasing, especially inside `with_or_segment_users`, to match what the UI would produce for the same request.\n"},"value":{"type":["string","number","boolean","array","null"],"description":"The operand. Which type applies depends on the operator: a scalar for `=` and `Contains`, an array (or comma-separated string) for `Is One Of`, a number for count comparisons, and omitted entirely for `Exists` / `Is Empty`.\n"},"value2":{"type":["string","number","null"],"description":"Secondary operand for two-parameter conditions (currently `External Events` count comparison and `SalesAttributes` pipeline-stage filter)."},"operator2":{"type":"string","description":"Secondary operator for two-parameter conditions.","nullable":true},"value2_id":{"type":"array","items":{"type":"string"},"nullable":true,"description":"Object-ID list for stage-title disambiguation on `SalesAttributes`."},"data_type":{"type":"string","enum":["String","Numeric","Date","List"],"nullable":true,"description":"Optional hint for the engine's disambiguation logic."},"dataAlias":{"type":"string","nullable":true,"description":"Human-readable alias shown in the UI. Not evaluated."}}},"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}},"responses":{"NotFound":{"description":"The resource doesn't exist or isn't visible to this caller.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/flows/{id}/runs":{"get":{"tags":["Flows"],"operationId":"listFlowRuns","summary":"List runs (per-contact traversals) for a flow.","description":"Paginated list of `userflowactions` rows for this flow. Common filters: `?filter[status]=processing` (in-flight), `?filter[status]=complete`, `?filter[contact_id]=`, `?filter[flow_complete_reason]=unenrolled`. Use `?include_history=true` to also include archived runs from previous re-enrollments.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"},{"$ref":"#/components/parameters/LimitParam"},{"$ref":"#/components/parameters/CursorParam"},{"name":"include_history","in":"query","required":false,"schema":{"type":"boolean","default":false}},{"name":"filter","in":"query","style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":{"type":"string"}}}],"responses":{"200":{"description":"A page of runs.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ListEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FlowRun"}}}}]}}}},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## Aggregate + per-node analytics for a flow.

> How a flow is performing: run counters, what its message nodes sent, and per-node reached counts.\
> \
> \`messages\` carries the flow's sends, deliveries, opens and clicks for the window — the same figures \`/messages/report?flow\_id=…\` returns. A flow's message nodes send through shadow campaigns, so its sends live alongside every other send and are found by that link.\
> \
> \`entered\` and \`unenrolled\` are windowed; \`active\_runs\` and \`completed\_runs\` are current state and do not move with the window. Default window is the last 30 days; override with \`?start=\`/\`?end=\`. Bare dates are read as UTC.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Flows","description":"Multi-step automations. Enrollment is driven by segment membership. 7 node types are supported by the engine — see the Flow Engine companion doc for the full model, including the versioning and in-flight-edit caveats."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["flows:read"]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"},"OAuth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE. Use for third-party apps acting on behalf of a Gleantap user.\nAuthorization Code + PKCE is the only supported grant for interactive flows; refresh_token grant is supported and rotates on every use.\n","flows":{"authorizationCode":{"authorizationUrl":"https://api.gleantap.com/v3/oauth/authorize","tokenUrl":"https://api.gleantap.com/v3/oauth/token","refreshUrl":"https://api.gleantap.com/v3/oauth/token","scopes":{"contacts:read":"Read contact records.","contacts:write":"Create, update, delete contacts (soft delete).","contacts:delete_hard":"Hard-delete contacts (irreversible).","events:read":"Read event records.","events:write":"Record events.","segments:read":"Read segments and preview membership.","segments:write":"Create, update, delete segments.","templates:read":"Read message templates.","templates:write":"Create, update, delete templates.","campaigns:read":"Read campaigns and analytics.","campaigns:write":"Create, schedule, cancel campaigns.","flows:read":"Read flow definitions and analytics.","flows:write":"Create, edit, publish flows.","flows:publish":"Publish/unpublish flows (separately scoped for governance).","messaging:send":"Send transactional messages (SMS, email, voice).","conversations:read":"Read conversations and messages.","conversations:write":"Send messages, close/reopen conversations.","webhooks:manage":"Create, update, delete webhook endpoints.","forms:manage":"Create, update, delete, publish, duplicate forms; list submissions and rotate the submission_token.","campaigns:manage":"Create, schedule, cancel, duplicate campaigns; read recipients and analytics. (Supersedes the earlier `campaigns:read` + `campaigns:write` split; the split scopes still work.)","admin:impersonate:read":"Gleantap staff only — read any customer account named via `Gleantap-Account`. Not available through dynamic client registration.","admin:impersonate:write":"Gleantap staff only — required for any state-changing method while impersonating. Not available through dynamic client registration."}}}}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"WorkroomQuery":{"name":"workroom","in":"query","required":false,"description":"Same semantics as the `Gleantap-Workroom` header, including that a write should never be sent without a workroom the user actually chose, and that an omitted workroom scopes a read to the account default rather than spanning the account. Prefer this on GETs so proxies and caches can key on it. Accepts name, prefixed ID, raw hex, or `all`.\n","schema":{"type":"string"}}},"schemas":{"FlowAnalyticsResponse":{"type":"object","properties":{"object":{"type":"string","const":"flow_analytics"},"flow_id":{"$ref":"#/components/schemas/FlowId"},"window":{"type":"object","properties":{"start":{"$ref":"#/components/schemas/Timestamp"},"end":{"$ref":"#/components/schemas/Timestamp"},"applies_to":{"type":"string","description":"Which figures the window governs."}}},"totals":{"$ref":"#/components/schemas/FlowStats"},"messages":{"allOf":[{"$ref":"#/components/schemas/MessageMetrics"}],"nullable":true,"description":"What the flow's message nodes sent in the window, and how it performed — the same figures `/messages/report?flow_id=…` returns for this flow. Null if the rollup could not be computed; the run counters above are still valid when that happens.\n"},"per_node":{"type":"array","items":{"$ref":"#/components/schemas/FlowNodeAnalytics"}},"computed_at":{"$ref":"#/components/schemas/Timestamp"}}},"FlowId":{"type":"string","pattern":"^flw_[0-9A-HJKMNP-TV-Z]{26}$"},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"FlowStats":{"type":"object","description":"Run counters. `active_runs` and `completed_runs` are current state and do not move with the analytics window; `entered` and `unenrolled` are windowed.\n","properties":{"active_runs":{"type":"integer","minimum":0,"description":"Runs open right now."},"completed_runs":{"type":"integer","minimum":0,"description":"Runs finished","all time.":null},"entered":{"type":"integer","minimum":0,"description":"Contacts enrolled within the window."},"unenrolled":{"type":"integer","minimum":0,"description":"Contacts unenrolled within the window."},"entered_last_30d":{"type":"integer","minimum":0,"deprecated":true,"description":"Same value as `entered`. Kept for existing callers; the name is only accurate when the window is the default 30 days."},"unenrolled_last_30d":{"type":"integer","minimum":0,"deprecated":true,"description":"Same value as `unenrolled`."}}},"MessageMetrics":{"type":"object","description":"Delivery and engagement counters, plus the rates derived from them. Every rate is a percentage and names its own denominator, because there is no single convention and callers otherwise disagree quietly.\n","properties":{"attempted":{"type":"integer","description":"Every message dispatched in the window","whatever happened to it (queued-but-unsent records are not counted). The outcomes below add up to this.":null},"sent":{"type":"integer","description":"Same definition as the dashboard's \"Emails Sent\" / \"SMS Sent\": status `success` or `delivered`. Excludes bounced/failed/dropped and spam-complaint rows."},"delivered":{"type":"integer","description":"Email: status `success` or `delivered` (equal to `sent`; a spam complaint is counted under `complaints`, as the dashboard does). SMS: the carrier outcome `messagestatus` is `delivered`/`delivery_unconfirmed` — `status: success` only means handed off to the provider."},"bounced":{"type":"integer","description":"Email: hard bounce reported by the provider. SMS: `messagestatus` undelivered / delivery_failed / sending_failed."},"dropped":{"type":"integer"},"undelivered":{"type":"integer","description":"Returned out of band."},"delayed":{"type":"integer","description":"Transient failure","still being retried.":null},"failed":{"type":"integer","description":"Email: refused on policy. SMS: `messagestatus` failed, or failed at send time."},"unaccounted":{"type":"integer","description":"Sends whose outcome is none of the above (nor a spam complaint). The outcomes add up to `attempted` and this is the remainder — for SMS mostly messages handed off with no carrier result yet; for email a provider status this report does not yet know about.\n"},"complaints":{"type":"integer","description":"Spam complaints. Two webhook paths record one; both are counted."},"unsubscribed":{"type":"integer","description":"Unsubscribes attributed to this message."},"campaigns":{"type":"integer","description":"Distinct campaigns that sent into this bucket."},"flows":{"type":"integer","description":"Distinct flows that sent into this bucket."},"opened":{"type":"integer","description":"Distinct contacts who opened. Unique-only — see the resource description. Always 0 for SMS."},"clicked":{"type":"integer","description":"Distinct contacts who clicked. Unique-only."},"contacts":{"type":"integer","description":"Distinct contacts reached. A contact sent two messages counts once here and twice in `sent`."},"delivery_rate":{"type":"number","description":"delivered / sent."},"bounce_rate":{"type":"number","description":"bounced / attempted."},"drop_rate":{"type":"number","description":"dropped / attempted."},"open_rate":{"type":"number","description":"opened / delivered."},"click_rate":{"type":"number","description":"clicked / delivered."},"click_to_open_rate":{"type":"number","description":"clicked / opened."},"spam_rate":{"type":"number","description":"complaints / delivered — nobody can complain about a message that bounced."},"unsubscribe_rate":{"type":"number","description":"unsubscribed / delivered."}}},"FlowNodeAnalytics":{"type":"object","properties":{"node_id":{"type":"string"},"node_type":{"$ref":"#/components/schemas/FlowNodeType"},"reached":{"type":"integer","minimum":0},"completed":{"type":"integer","minimum":0},"dropped":{"type":"integer","minimum":0},"avg_dwell_seconds":{"type":"number","nullable":true}}},"FlowNodeType":{"type":"string","enum":["email_campaign","sms_campaign","delay","condition","sales_automation","webhook","mariana_action"],"description":"The 7 node types the engine actually supports (`mariana_action` gives the contact a pack, class credits or account credit in the workroom's Mariana Tek studio). Richer vocab from the main spec (`send_message`, `tag`, `add_to_segment`, `update_contact`, `create_task`, `create_opportunity`, `wait_for_event`, `split`, `end`) is NOT implemented — express those via `sales_automation` (pointing at a CRM sub-automation) or return 501 `node_type_not_supported`. See Flow Engine companion doc §10.\n"},"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}},"responses":{"NotFound":{"description":"The resource doesn't exist or isn't visible to this caller.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/flows/{id}/analytics":{"get":{"tags":["Flows"],"operationId":"getFlowAnalytics","summary":"Aggregate + per-node analytics for a flow.","description":"How a flow is performing: run counters, what its message nodes sent, and per-node reached counts.\n\n`messages` carries the flow's sends, deliveries, opens and clicks for the window — the same figures `/messages/report?flow_id=…` returns. A flow's message nodes send through shadow campaigns, so its sends live alongside every other send and are found by that link.\n\n`entered` and `unenrolled` are windowed; `active_runs` and `completed_runs` are current state and do not move with the window. Default window is the last 30 days; override with `?start=`/`?end=`. Bare dates are read as UTC.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"},{"name":"start","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"end","in":"query","required":false,"schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Analytics payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlowAnalyticsResponse"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## GET /flows/{id}/sharing

> Read a flow's sharing configuration.

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Flows","description":"Multi-step automations. Enrollment is driven by segment membership. 7 node types are supported by the engine — see the Flow Engine companion doc for the full model, including the versioning and in-flight-edit caveats."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["flows:read"]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"},"OAuth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE. Use for third-party apps acting on behalf of a Gleantap user.\nAuthorization Code + PKCE is the only supported grant for interactive flows; refresh_token grant is supported and rotates on every use.\n","flows":{"authorizationCode":{"authorizationUrl":"https://api.gleantap.com/v3/oauth/authorize","tokenUrl":"https://api.gleantap.com/v3/oauth/token","refreshUrl":"https://api.gleantap.com/v3/oauth/token","scopes":{"contacts:read":"Read contact records.","contacts:write":"Create, update, delete contacts (soft delete).","contacts:delete_hard":"Hard-delete contacts (irreversible).","events:read":"Read event records.","events:write":"Record events.","segments:read":"Read segments and preview membership.","segments:write":"Create, update, delete segments.","templates:read":"Read message templates.","templates:write":"Create, update, delete templates.","campaigns:read":"Read campaigns and analytics.","campaigns:write":"Create, schedule, cancel campaigns.","flows:read":"Read flow definitions and analytics.","flows:write":"Create, edit, publish flows.","flows:publish":"Publish/unpublish flows (separately scoped for governance).","messaging:send":"Send transactional messages (SMS, email, voice).","conversations:read":"Read conversations and messages.","conversations:write":"Send messages, close/reopen conversations.","webhooks:manage":"Create, update, delete webhook endpoints.","forms:manage":"Create, update, delete, publish, duplicate forms; list submissions and rotate the submission_token.","campaigns:manage":"Create, schedule, cancel, duplicate campaigns; read recipients and analytics. (Supersedes the earlier `campaigns:read` + `campaigns:write` split; the split scopes still work.)","admin:impersonate:read":"Gleantap staff only — read any customer account named via `Gleantap-Account`. Not available through dynamic client registration.","admin:impersonate:write":"Gleantap staff only — required for any state-changing method while impersonating. Not available through dynamic client registration."}}}}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"WorkroomQuery":{"name":"workroom","in":"query","required":false,"description":"Same semantics as the `Gleantap-Workroom` header, including that a write should never be sent without a workroom the user actually chose, and that an omitted workroom scopes a read to the account default rather than spanning the account. Prefer this on GETs so proxies and caches can key on it. Accepts name, prefixed ID, raw hex, or `all`.\n","schema":{"type":"string"}}},"schemas":{"FlowSharing":{"type":"object","properties":{"object":{"type":"string","const":"flow_sharing"},"flow_id":{"$ref":"#/components/schemas/FlowId"},"allowed_roles":{"type":"object","description":"Boolean map keyed by role. Accepted keys: `me`, `Admin`, `WorkroomAdmin`, `Marketing`, `Sales`, `Analyst`, `Other`. Unknown keys are dropped on write. Missing keys read as false.\n","additionalProperties":{"type":"boolean"}},"other_allowed_user_ids":{"type":"array","items":{"$ref":"#/components/schemas/StaffId"}},"role_updated_on":{"type":"string","format":"date-time","nullable":true}}},"FlowId":{"type":"string","pattern":"^flw_[0-9A-HJKMNP-TV-Z]{26}$"},"StaffId":{"type":"string","pattern":"^usr_[0-9a-f]{24}$","description":"A staff user (from the legacy `users` collection). Used for `owner_id`, `responsible_id`, `created_by`, `assigned_to`, etc."},"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}},"responses":{"NotFound":{"description":"The resource doesn't exist or isn't visible to this caller.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/flows/{id}/sharing":{"get":{"tags":["Flows"],"operationId":"retrieveFlowSharing","summary":"Read a flow's sharing configuration.","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"}],"responses":{"200":{"description":"Sharing config.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlowSharing"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## Replace a flow's sharing configuration.

> Full-replace (matches the dashboard's checkbox POST — unchecked boxes just don't appear). Accepted role keys: \`me\`, \`Admin\`, \`WorkroomAdmin\`, \`Marketing\`, \`Sales\`, \`Analyst\`, \`Other\`. When \`Other\` is true, \`other\_allowed\_user\_ids\[]\` must contain at least one valid staff ID or 400 is returned.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Flows","description":"Multi-step automations. Enrollment is driven by segment membership. 7 node types are supported by the engine — see the Flow Engine companion doc for the full model, including the versioning and in-flight-edit caveats."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["flows:write"]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"},"OAuth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE. Use for third-party apps acting on behalf of a Gleantap user.\nAuthorization Code + PKCE is the only supported grant for interactive flows; refresh_token grant is supported and rotates on every use.\n","flows":{"authorizationCode":{"authorizationUrl":"https://api.gleantap.com/v3/oauth/authorize","tokenUrl":"https://api.gleantap.com/v3/oauth/token","refreshUrl":"https://api.gleantap.com/v3/oauth/token","scopes":{"contacts:read":"Read contact records.","contacts:write":"Create, update, delete contacts (soft delete).","contacts:delete_hard":"Hard-delete contacts (irreversible).","events:read":"Read event records.","events:write":"Record events.","segments:read":"Read segments and preview membership.","segments:write":"Create, update, delete segments.","templates:read":"Read message templates.","templates:write":"Create, update, delete templates.","campaigns:read":"Read campaigns and analytics.","campaigns:write":"Create, schedule, cancel campaigns.","flows:read":"Read flow definitions and analytics.","flows:write":"Create, edit, publish flows.","flows:publish":"Publish/unpublish flows (separately scoped for governance).","messaging:send":"Send transactional messages (SMS, email, voice).","conversations:read":"Read conversations and messages.","conversations:write":"Send messages, close/reopen conversations.","webhooks:manage":"Create, update, delete webhook endpoints.","forms:manage":"Create, update, delete, publish, duplicate forms; list submissions and rotate the submission_token.","campaigns:manage":"Create, schedule, cancel, duplicate campaigns; read recipients and analytics. (Supersedes the earlier `campaigns:read` + `campaigns:write` split; the split scopes still work.)","admin:impersonate:read":"Gleantap staff only — read any customer account named via `Gleantap-Account`. Not available through dynamic client registration.","admin:impersonate:write":"Gleantap staff only — required for any state-changing method while impersonating. Not available through dynamic client registration."}}}}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"WorkroomQuery":{"name":"workroom","in":"query","required":false,"description":"Same semantics as the `Gleantap-Workroom` header, including that a write should never be sent without a workroom the user actually chose, and that an omitted workroom scopes a read to the account default rather than spanning the account. Prefer this on GETs so proxies and caches can key on it. Accepts name, prefixed ID, raw hex, or `all`.\n","schema":{"type":"string"}}},"schemas":{"FlowSharingUpdate":{"type":"object","properties":{"allowed_roles":{"type":"object","additionalProperties":{"type":"boolean"}},"other_allowed_user_ids":{"type":"array","items":{"$ref":"#/components/schemas/StaffId"},"description":"Required (non-empty) when `allowed_roles.Other` is true; otherwise ignored."}}},"StaffId":{"type":"string","pattern":"^usr_[0-9a-f]{24}$","description":"A staff user (from the legacy `users` collection). Used for `owner_id`, `responsible_id`, `created_by`, `assigned_to`, etc."},"FlowSharing":{"type":"object","properties":{"object":{"type":"string","const":"flow_sharing"},"flow_id":{"$ref":"#/components/schemas/FlowId"},"allowed_roles":{"type":"object","description":"Boolean map keyed by role. Accepted keys: `me`, `Admin`, `WorkroomAdmin`, `Marketing`, `Sales`, `Analyst`, `Other`. Unknown keys are dropped on write. Missing keys read as false.\n","additionalProperties":{"type":"boolean"}},"other_allowed_user_ids":{"type":"array","items":{"$ref":"#/components/schemas/StaffId"}},"role_updated_on":{"type":"string","format":"date-time","nullable":true}}},"FlowId":{"type":"string","pattern":"^flw_[0-9A-HJKMNP-TV-Z]{26}$"},"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}},"responses":{"BadRequest":{"description":"Request could not be parsed or failed validation.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"NotFound":{"description":"The resource doesn't exist or isn't visible to this caller.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/flows/{id}/sharing":{"put":{"tags":["Flows"],"operationId":"updateFlowSharing","summary":"Replace a flow's sharing configuration.","description":"Full-replace (matches the dashboard's checkbox POST — unchecked boxes just don't appear). Accepted role keys: `me`, `Admin`, `WorkroomAdmin`, `Marketing`, `Sales`, `Analyst`, `Other`. When `Other` is true, `other_allowed_user_ids[]` must contain at least one valid staff ID or 400 is returned.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlowSharingUpdate"}}}},"responses":{"200":{"description":"Updated sharing config.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlowSharing"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## Enumerate flow node types + entry-trigger types + sales\_automation action library + recipes.

> Catalog for authoring a flow. Returns the 7 node types (email\_campaign, sms\_campaign, delay, condition, sales\_automation, webhook, mariana\_action) with per-type field requirements, the 2 entry-trigger types (segment\_membership, manual), the 13 sales\_automation action types with example payloads, the 6 trigger types, and a small library of common flow recipes (lead nurture, appointment reminder, win-back).<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Flows","description":"Multi-step automations. Enrollment is driven by segment membership. 7 node types are supported by the engine — see the Flow Engine companion doc for the full model, including the versioning and in-flight-edit caveats."}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"WorkroomQuery":{"name":"workroom","in":"query","required":false,"description":"Same semantics as the `Gleantap-Workroom` header, including that a write should never be sent without a workroom the user actually chose, and that an omitted workroom scopes a read to the account default rather than spanning the account. Prefer this on GETs so proxies and caches can key on it. Accepts name, prefixed ID, raw hex, or `all`.\n","schema":{"type":"string"}}}},"paths":{"/flows/schema":{"get":{"tags":["Flows"],"operationId":"describeFlowSchema","summary":"Enumerate flow node types + entry-trigger types + sales_automation action library + recipes.","description":"Catalog for authoring a flow. Returns the 7 node types (email_campaign, sms_campaign, delay, condition, sales_automation, webhook, mariana_action) with per-type field requirements, the 2 entry-trigger types (segment_membership, manual), the 13 sales_automation action types with example payloads, the 6 trigger types, and a small library of common flow recipes (lead nurture, appointment reminder, win-back).\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}}}}
```
