openapi: 3.1.0 info: title: Boom CDP Custom Objects Journeys API version: 1.0.0 description: 'Boom''s public REST API — one uniform surface over every platform capability. CDP: upsert people and custom objects, define object and relationship types, link and unlink relationships, and record behavioral events — one record per request or up to 1000 per request via the `/batch` endpoints. Segments: read (list, read, membership) and full authoring — discover the filterable catalog, validate a filter, create and update segments, preview match counts, and trigger evaluation. Initiatives: create and configure outreach initiatives, link WhatsApp templates, drive the lifecycle (launch, cancel, archive), and read collected-data summaries. Participants: enroll people into an active initiative, track their status, read conversation transcripts, and stop outreach. Journeys: read-only access to always-on message flows and their metrics. WhatsApp templates: list your WhatsApp numbers and list, read, and create message templates. The same capabilities are exposed as MCP tools with identical schemas.' servers: - url: https://www.useboom.ai description: Production - url: https://dev.useboom.ai description: Development (sandbox — use a development organization API key) security: - bearerAuth: [] tags: - name: Journeys paths: /api/v1/journeys: get: operationId: journeys_list summary: List journeys description: List the organization's journeys, newest first. A journey is the step sequence people move through, attached to an initiative. Read-only. tags: - Journeys parameters: - name: initiativeId in: query required: false schema: $schema: https://json-schema.org/draft/2020-12/schema description: Only the journey attached to this initiative. type: string minLength: 1 - name: status in: query required: false schema: $schema: https://json-schema.org/draft/2020-12/schema description: Only journeys with this status. type: string enum: - DRAFT - ACTIVE - ARCHIVED - name: limit in: query required: false schema: $schema: https://json-schema.org/draft/2020-12/schema description: Page size (default 100, max 1000). type: integer minimum: 1 maximum: 1000 - name: cursor in: query required: false schema: $schema: https://json-schema.org/draft/2020-12/schema description: Opaque pagination token from a previous response's next_cursor. type: string responses: '200': description: Success content: application/json: schema: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: data: type: array items: type: object properties: id: type: string description: Journey id. initiativeId: type: string description: The initiative this journey belongs to. name: type: string description: Journey name (from its initiative). status: type: string enum: - DRAFT - ACTIVE - ARCHIVED description: DRAFT (still being configured), ACTIVE (live — people can move through it), or ARCHIVED (no longer running). version: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Version number of the journey's current setup. Each time the steps are edited and re-activated, the version increases. createdAt: type: string description: ISO 8601 timestamp. updatedAt: type: string description: ISO 8601 timestamp. required: - id - initiativeId - name - status - version - createdAt - updatedAt additionalProperties: false next_cursor: anyOf: - type: string - type: 'null' description: Pass as `cursor` to fetch the next page; null on the last. required: - data - next_cursor additionalProperties: false '400': description: Validation failed or the request cannot proceed. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '401': description: Missing, malformed, or revoked API key. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '404': description: The resource does not exist in this organization. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '409': description: Conflicts with the current state (duplicates, wrong lifecycle state). content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '422': description: The request is well-formed but semantically invalid. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '429': description: Rate limit exceeded — retry after `Retry-After`. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '500': description: Internal server error. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '503': description: Transient error — retry with a narrower request. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error post: operationId: journeys_create_draft summary: Create draft description: Create a new draft journey on an initiative from a full graph. The draft is editable and does not run until published (which is done in the app). Omit node positions and the server lays the graph out automatically. tags: - Journeys requestBody: required: true content: application/json: schema: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: initiativeId: type: string minLength: 1 description: The initiative to attach the new draft journey to. definition: type: object properties: id: description: Journey id; carried for round-trip ergonomics. Optional on create. type: string name: type: string minLength: 1 description: Journey name. metadata: type: object properties: initiativeType: type: string version: type: integer minimum: -9007199254740991 maximum: 9007199254740991 cancelOnEvents: description: Cancel an in-flight run when any of these events arrive. type: object properties: eventNames: type: array items: type: string required: - eventNames description: Optional journey-level metadata. actions: minItems: 1 type: array items: oneOf: - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: ENTRY name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: description: type: string triggerType: description: 'How people enter: manual (added by an operator or API call), segment (on entering a segment), or cdp_event (when an event is received). Defaults to manual.' type: string enum: - manual - segment - cdp_event segmentId: description: Segment id — required when triggerType is segment. type: string segmentName: description: Cached segment display name (optional). type: string eventName: description: CDP event name — required when triggerType is cdp_event. type: string maxEnrollments: description: 'Frequency cap: max enrollments per person within enrollmentWindow. Both-or-neither with enrollmentWindow.' type: integer minimum: 1 maximum: 9007199254740991 enrollmentWindow: description: Rolling window for the frequency cap. type: string description: Trigger node config. Exactly one ENTRY node per journey. required: - id - kind - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: SEND_MESSAGE name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: templateId: description: Approved WhatsApp template id. Resolve ids from the catalog. type: string templateName: type: string channel: description: Send channel. Only whatsapp is live today. type: string enum: - whatsapp - sms - email templateBindings: description: Map of template placeholder → variable reference. type: object propertyNames: type: string additionalProperties: type: string channelId: description: Sending WhatsApp channel (WABA) id. Required before publishing. type: string sendImmediately: description: Deprecated business-hours gate; prefer a preceding DELAY. type: boolean description: Sends a WhatsApp template. required: - id - kind - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: CONVERSATION_BLOCK name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: goal: type: string maxTimeout: description: How long to wait for a reply before timing out. type: string mode: type: string enum: - AGENT - ESCALATE outputs: type: array items: type: object properties: id: type: string label: type: string type: type: string enum: - string - number - date - boolean - json description: type: string builtin: type: boolean required: - id - label - type - builtin description: Legacy combined wait + AI conversation block. required: - id - kind - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: WAIT_FOR_REPLY name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: maxTimeout: description: How long to wait for the first reply before timing out. type: string description: Waits for the person to reply. required: - id - kind - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: MANAGE_CONVERSATION name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: mode: description: AGENT (AI-led) or ESCALATE (human handoff). Defaults to AGENT. type: string enum: - AGENT - ESCALATE inactivityTimeout: description: Rolling idle window (e.g. '12h'), resets on each inbound message. After this much silence the node routes INACTIVE (extracts, does not close). Range 1h–24h; requires the journey-inactivity-timeout flag. type: string description: Runs the AI-led conversation. required: - id - kind - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: DISPATCH_EVENT name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: eventName: type: string minLength: 1 description: CDP event name to record. Must match the CDP name pattern. properties: description: 'Literal string values, or { var: path } bindings resolved to typed values at dispatch time.' type: object propertyNames: type: string additionalProperties: anyOf: - type: string - type: object properties: var: type: string required: - var description: type: string required: - eventName description: Records a CDP event for the person. required: - id - kind - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: DELAY name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: mode: description: How the wait is measured. Defaults to duration. type: string enum: - duration - until_date - until_weekday duration: description: For mode duration. type: string targetAt: description: ISO 8601 instant, for mode until_date. type: string weekdays: description: ISO weekdays 1=Mon..7=Sun, for mode until_weekday. type: array items: type: integer minimum: 1 maximum: 7 windowStartMinutes: type: integer minimum: 0 maximum: 1439 windowEndMinutes: type: integer minimum: 0 maximum: 1439 timezone: description: IANA timezone. Load-bearing for until_weekday. type: string description: type: string description: Pauses the run. required: - id - kind - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: DECISION name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: logic: type: string enum: - AND - OR conditions: type: array items: oneOf: - type: object properties: kind: type: string const: value selectionPath: type: string description: Dot-path into the run, e.g. workflowState.totalPrice. operator: type: string enum: - eq - neq - gt - lt - contains - isSet value: type: string required: - kind - selectionPath - operator - value - type: object properties: kind: type: string const: event eventName: type: string subjectSelectionPath: type: string occurred: type: boolean required: - kind - eventName - subjectSelectionPath - occurred - type: object properties: kind: type: string const: cdp_predicate term: type: object propertyNames: type: string additionalProperties: {} description: A single live person/computed predicate term. See journeys_authoring_catalog for its shape. required: - kind - term - type: object properties: kind: type: string const: cdp_object objectType: type: string matchAttr: type: string matchSelectionPath: type: string exists: type: boolean required: - kind - objectType - matchAttr - matchSelectionPath - exists description: One decision condition. description: type: string required: - logic - conditions description: Two-way branch. Emits YES / NO. required: - id - kind - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: CASE name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: selectionPath: type: string description: Person attribute (attributes.*) or extracted field (engagement.extracted.*) to switch on. branches: type: array items: type: object properties: id: type: string description: Stable branch id; edge handle is case:. value: type: string description: Value matched. Unique within the node. label: type: string required: - id - value description: Up to 10 branches. A case:default handle is always required. description: type: string required: - selectionPath - branches description: N-way switch on a person attribute. required: - id - kind - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: HTTP_REQUEST name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: method: type: string enum: - GET - POST - PUT - PATCH - DELETE description: HTTP method. url: type: string minLength: 1 description: Target URL. Supports {{variable}} placeholders. headers: description: Request headers as key/value pairs. type: array items: type: object properties: key: type: string value: type: string required: - key - value body: description: Request body. mode none sends no body. type: object properties: mode: type: string enum: - none - json - raw content: type: string contentType: type: string required: - mode credentialId: description: HttpCredential id used to authenticate the request. type: string timeoutMs: description: Request timeout in milliseconds. Max 30000 (30s). type: integer exclusiveMinimum: 0 maximum: 30000 maxAttempts: description: Max attempts including the first. Max 5. type: integer exclusiveMinimum: 0 maximum: 5 documentUrlTtlSeconds: description: TTL (seconds, ≤86400) for presigned engagement.documents URLs this node emits. Default 86400. type: integer exclusiveMinimum: 0 maximum: 86400 required: - method - url description: Calls an external HTTP endpoint. Emits SUCCESS or FAILED. required: - id - kind - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: EXIT name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: outcome: type: string nextInitiativeId: description: Chain into another initiative on exit. type: string description: Terminal node. required: - id - kind description: The nodes. Exactly one ENTRY and at least one EXIT are required to publish. edges: type: array items: type: object properties: from: type: string description: Source node id. to: type: string description: Target node id. sourceHandle: type: string description: The emitted signal that activates this edge (e.g. SENT, REPLIED, YES, case:). A handle may wire to at most one node. metadata: type: object properties: signalCategory: type: string enum: - lifecycle - system signalDescription: type: string required: - from - to - sourceHandle description: 'A connection: node `from` routes to `to` when it emits `sourceHandle`.' description: The connections between node handles. required: - name - actions - edges description: The full journey graph. Drafts may be incomplete; run journeys_validate before publishing. required: - initiativeId - definition responses: '201': description: Success content: application/json: schema: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: id: type: string description: Journey (workflow version) id. initiativeId: type: string description: The initiative this journey belongs to. status: type: string enum: - DRAFT - PUBLISHED - STOPPED description: DRAFT (editable), PUBLISHED (live, frozen), or STOPPED (retired). version: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Version number within the initiative. definition: type: object properties: id: description: Journey id; carried for round-trip ergonomics. Optional on create. type: string name: type: string minLength: 1 description: Journey name. metadata: type: object properties: initiativeType: type: string version: type: integer minimum: -9007199254740991 maximum: 9007199254740991 cancelOnEvents: description: Cancel an in-flight run when any of these events arrive. type: object properties: eventNames: type: array items: type: string required: - eventNames additionalProperties: false additionalProperties: false description: Optional journey-level metadata. actions: minItems: 1 type: array items: oneOf: - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: ENTRY name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: description: type: string triggerType: description: 'How people enter: manual (added by an operator or API call), segment (on entering a segment), or cdp_event (when an event is received). Defaults to manual.' type: string enum: - manual - segment - cdp_event segmentId: description: Segment id — required when triggerType is segment. type: string segmentName: description: Cached segment display name (optional). type: string eventName: description: CDP event name — required when triggerType is cdp_event. type: string maxEnrollments: description: 'Frequency cap: max enrollments per person within enrollmentWindow. Both-or-neither with enrollmentWindow.' type: integer minimum: 1 maximum: 9007199254740991 enrollmentWindow: description: Rolling window for the frequency cap. type: string additionalProperties: false description: Trigger node config. Exactly one ENTRY node per journey. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: SEND_MESSAGE name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: templateId: description: Approved WhatsApp template id. Resolve ids from the catalog. type: string templateName: type: string channel: description: Send channel. Only whatsapp is live today. type: string enum: - whatsapp - sms - email templateBindings: description: Map of template placeholder → variable reference. type: object propertyNames: type: string additionalProperties: type: string channelId: description: Sending WhatsApp channel (WABA) id. Required before publishing. type: string sendImmediately: description: Deprecated business-hours gate; prefer a preceding DELAY. type: boolean additionalProperties: false description: Sends a WhatsApp template. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: CONVERSATION_BLOCK name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: goal: type: string maxTimeout: description: How long to wait for a reply before timing out. type: string mode: type: string enum: - AGENT - ESCALATE outputs: type: array items: type: object properties: id: type: string label: type: string type: type: string enum: - string - number - date - boolean - json description: type: string builtin: type: boolean required: - id - label - type - builtin additionalProperties: false additionalProperties: false description: Legacy combined wait + AI conversation block. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: WAIT_FOR_REPLY name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: maxTimeout: description: How long to wait for the first reply before timing out. type: string additionalProperties: false description: Waits for the person to reply. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: MANAGE_CONVERSATION name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: mode: description: AGENT (AI-led) or ESCALATE (human handoff). Defaults to AGENT. type: string enum: - AGENT - ESCALATE inactivityTimeout: description: Rolling idle window (e.g. '12h'), resets on each inbound message. After this much silence the node routes INACTIVE (extracts, does not close). Range 1h–24h; requires the journey-inactivity-timeout flag. type: string additionalProperties: false description: Runs the AI-led conversation. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: DISPATCH_EVENT name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: eventName: type: string minLength: 1 description: CDP event name to record. Must match the CDP name pattern. properties: description: 'Literal string values, or { var: path } bindings resolved to typed values at dispatch time.' type: object propertyNames: type: string additionalProperties: anyOf: - type: string - type: object properties: var: type: string required: - var additionalProperties: false description: type: string required: - eventName additionalProperties: false description: Records a CDP event for the person. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: DELAY name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: mode: description: How the wait is measured. Defaults to duration. type: string enum: - duration - until_date - until_weekday duration: description: For mode duration. type: string targetAt: description: ISO 8601 instant, for mode until_date. type: string weekdays: description: ISO weekdays 1=Mon..7=Sun, for mode until_weekday. type: array items: type: integer minimum: 1 maximum: 7 windowStartMinutes: type: integer minimum: 0 maximum: 1439 windowEndMinutes: type: integer minimum: 0 maximum: 1439 timezone: description: IANA timezone. Load-bearing for until_weekday. type: string description: type: string additionalProperties: false description: Pauses the run. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: DECISION name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: logic: type: string enum: - AND - OR conditions: type: array items: oneOf: - type: object properties: kind: type: string const: value selectionPath: type: string description: Dot-path into the run, e.g. workflowState.totalPrice. operator: type: string enum: - eq - neq - gt - lt - contains - isSet value: type: string required: - kind - selectionPath - operator - value additionalProperties: false - type: object properties: kind: type: string const: event eventName: type: string subjectSelectionPath: type: string occurred: type: boolean required: - kind - eventName - subjectSelectionPath - occurred additionalProperties: false - type: object properties: kind: type: string const: cdp_predicate term: type: object propertyNames: type: string additionalProperties: {} description: A single live person/computed predicate term. See journeys_authoring_catalog for its shape. required: - kind - term additionalProperties: false - type: object properties: kind: type: string const: cdp_object objectType: type: string matchAttr: type: string matchSelectionPath: type: string exists: type: boolean required: - kind - objectType - matchAttr - matchSelectionPath - exists additionalProperties: false description: One decision condition. description: type: string required: - logic - conditions additionalProperties: false description: Two-way branch. Emits YES / NO. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: CASE name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: selectionPath: type: string description: Person attribute (attributes.*) or extracted field (engagement.extracted.*) to switch on. branches: type: array items: type: object properties: id: type: string description: Stable branch id; edge handle is case:. value: type: string description: Value matched. Unique within the node. label: type: string required: - id - value additionalProperties: false description: Up to 10 branches. A case:default handle is always required. description: type: string required: - selectionPath - branches additionalProperties: false description: N-way switch on a person attribute. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: HTTP_REQUEST name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: method: type: string enum: - GET - POST - PUT - PATCH - DELETE description: HTTP method. url: type: string minLength: 1 description: Target URL. Supports {{variable}} placeholders. headers: description: Request headers as key/value pairs. type: array items: type: object properties: key: type: string value: type: string required: - key - value additionalProperties: false body: description: Request body. mode none sends no body. type: object properties: mode: type: string enum: - none - json - raw content: type: string contentType: type: string required: - mode additionalProperties: false credentialId: description: HttpCredential id used to authenticate the request. type: string timeoutMs: description: Request timeout in milliseconds. Max 30000 (30s). type: integer exclusiveMinimum: 0 maximum: 30000 maxAttempts: description: Max attempts including the first. Max 5. type: integer exclusiveMinimum: 0 maximum: 5 documentUrlTtlSeconds: description: TTL (seconds, ≤86400) for presigned engagement.documents URLs this node emits. Default 86400. type: integer exclusiveMinimum: 0 maximum: 86400 required: - method - url additionalProperties: false description: Calls an external HTTP endpoint. Emits SUCCESS or FAILED. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: EXIT name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: outcome: type: string nextInitiativeId: description: Chain into another initiative on exit. type: string additionalProperties: false description: Terminal node. required: - id - kind additionalProperties: false description: The nodes. Exactly one ENTRY and at least one EXIT are required to publish. edges: type: array items: type: object properties: from: type: string description: Source node id. to: type: string description: Target node id. sourceHandle: type: string description: The emitted signal that activates this edge (e.g. SENT, REPLIED, YES, case:). A handle may wire to at most one node. metadata: type: object properties: signalCategory: type: string enum: - lifecycle - system signalDescription: type: string additionalProperties: false required: - from - to - sourceHandle additionalProperties: false description: 'A connection: node `from` routes to `to` when it emits `sourceHandle`.' description: The connections between node handles. required: - name - actions - edges additionalProperties: false description: The full journey graph. required: - id - initiativeId - status - version - definition additionalProperties: false '400': description: Validation failed or the request cannot proceed. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '401': description: Missing, malformed, or revoked API key. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '404': description: The resource does not exist in this organization. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '409': description: Conflicts with the current state (duplicates, wrong lifecycle state). content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '422': description: The request is well-formed but semantically invalid. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '429': description: Rate limit exceeded — retry after `Retry-After`. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '500': description: Internal server error. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '503': description: Transient error — retry with a narrower request. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error /api/v1/journeys/{journeyId}: get: operationId: journeys_get summary: Get journey description: Get one journey by id — its trigger and the ordered steps people move through. Read-only, for inspecting setup. tags: - Journeys parameters: - name: journeyId in: path required: true schema: $schema: https://json-schema.org/draft/2020-12/schema type: string minLength: 1 description: Journey id. responses: '200': description: Success content: application/json: schema: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: id: type: string description: Journey id. initiativeId: type: string description: The initiative this journey belongs to. name: type: string description: Journey name (from its initiative). status: type: string enum: - DRAFT - ACTIVE - ARCHIVED description: DRAFT (still being configured), ACTIVE (live — people can move through it), or ARCHIVED (no longer running). version: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Version number of the journey's current setup. Each time the steps are edited and re-activated, the version increases. createdAt: type: string description: ISO 8601 timestamp. updatedAt: type: string description: ISO 8601 timestamp. trigger: type: object properties: type: type: string enum: - manual - segment - event description: 'How people enter the journey: manual (added by an operator or API call), segment (added when they enter a segment), or event (added when an event is received for them).' segment: anyOf: - type: string - type: 'null' description: Segment name, when type is segment. event: anyOf: - type: string - type: 'null' description: Event name, when type is event. required: - type - segment - event additionalProperties: false steps: type: array items: type: object properties: id: type: string description: Step id, unique within the journey. type: type: string enum: - entry - message - conversation - wait - branch - split - event - end - step description: 'What the step does: entry (where people start), message (sends a message template), conversation (an AI-led conversation), wait (pauses before continuing), branch (routes down a yes or no path), split (routes across several cases), event (records an event), end (finishes the journey), or step (a step of another kind).' title: description: The name the journey author gave this step. type: string description: description: Plain-language summary of what the step is configured to do. type: string required: - id - type additionalProperties: false description: The steps that make up the journey, in the order a person moves through them. required: - id - initiativeId - name - status - version - createdAt - updatedAt - trigger - steps additionalProperties: false '400': description: Validation failed or the request cannot proceed. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '401': description: Missing, malformed, or revoked API key. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '404': description: The resource does not exist in this organization. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '409': description: Conflicts with the current state (duplicates, wrong lifecycle state). content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '422': description: The request is well-formed but semantically invalid. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '429': description: Rate limit exceeded — retry after `Retry-After`. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '500': description: Internal server error. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '503': description: Transient error — retry with a narrower request. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error patch: operationId: journeys_update_draft summary: Update draft description: Replace a draft journey's whole graph. Only drafts can be edited; published versions are frozen (edit a live journey in the app to fork a new draft). Omit node positions and the server lays the graph out automatically. tags: - Journeys requestBody: required: true content: application/json: schema: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: definition: type: object properties: id: description: Journey id; carried for round-trip ergonomics. Optional on create. type: string name: type: string minLength: 1 description: Journey name. metadata: type: object properties: initiativeType: type: string version: type: integer minimum: -9007199254740991 maximum: 9007199254740991 cancelOnEvents: description: Cancel an in-flight run when any of these events arrive. type: object properties: eventNames: type: array items: type: string required: - eventNames description: Optional journey-level metadata. actions: minItems: 1 type: array items: oneOf: - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: ENTRY name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: description: type: string triggerType: description: 'How people enter: manual (added by an operator or API call), segment (on entering a segment), or cdp_event (when an event is received). Defaults to manual.' type: string enum: - manual - segment - cdp_event segmentId: description: Segment id — required when triggerType is segment. type: string segmentName: description: Cached segment display name (optional). type: string eventName: description: CDP event name — required when triggerType is cdp_event. type: string maxEnrollments: description: 'Frequency cap: max enrollments per person within enrollmentWindow. Both-or-neither with enrollmentWindow.' type: integer minimum: 1 maximum: 9007199254740991 enrollmentWindow: description: Rolling window for the frequency cap. type: string description: Trigger node config. Exactly one ENTRY node per journey. required: - id - kind - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: SEND_MESSAGE name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: templateId: description: Approved WhatsApp template id. Resolve ids from the catalog. type: string templateName: type: string channel: description: Send channel. Only whatsapp is live today. type: string enum: - whatsapp - sms - email templateBindings: description: Map of template placeholder → variable reference. type: object propertyNames: type: string additionalProperties: type: string channelId: description: Sending WhatsApp channel (WABA) id. Required before publishing. type: string sendImmediately: description: Deprecated business-hours gate; prefer a preceding DELAY. type: boolean description: Sends a WhatsApp template. required: - id - kind - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: CONVERSATION_BLOCK name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: goal: type: string maxTimeout: description: How long to wait for a reply before timing out. type: string mode: type: string enum: - AGENT - ESCALATE outputs: type: array items: type: object properties: id: type: string label: type: string type: type: string enum: - string - number - date - boolean - json description: type: string builtin: type: boolean required: - id - label - type - builtin description: Legacy combined wait + AI conversation block. required: - id - kind - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: WAIT_FOR_REPLY name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: maxTimeout: description: How long to wait for the first reply before timing out. type: string description: Waits for the person to reply. required: - id - kind - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: MANAGE_CONVERSATION name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: mode: description: AGENT (AI-led) or ESCALATE (human handoff). Defaults to AGENT. type: string enum: - AGENT - ESCALATE inactivityTimeout: description: Rolling idle window (e.g. '12h'), resets on each inbound message. After this much silence the node routes INACTIVE (extracts, does not close). Range 1h–24h; requires the journey-inactivity-timeout flag. type: string description: Runs the AI-led conversation. required: - id - kind - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: DISPATCH_EVENT name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: eventName: type: string minLength: 1 description: CDP event name to record. Must match the CDP name pattern. properties: description: 'Literal string values, or { var: path } bindings resolved to typed values at dispatch time.' type: object propertyNames: type: string additionalProperties: anyOf: - type: string - type: object properties: var: type: string required: - var description: type: string required: - eventName description: Records a CDP event for the person. required: - id - kind - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: DELAY name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: mode: description: How the wait is measured. Defaults to duration. type: string enum: - duration - until_date - until_weekday duration: description: For mode duration. type: string targetAt: description: ISO 8601 instant, for mode until_date. type: string weekdays: description: ISO weekdays 1=Mon..7=Sun, for mode until_weekday. type: array items: type: integer minimum: 1 maximum: 7 windowStartMinutes: type: integer minimum: 0 maximum: 1439 windowEndMinutes: type: integer minimum: 0 maximum: 1439 timezone: description: IANA timezone. Load-bearing for until_weekday. type: string description: type: string description: Pauses the run. required: - id - kind - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: DECISION name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: logic: type: string enum: - AND - OR conditions: type: array items: oneOf: - type: object properties: kind: type: string const: value selectionPath: type: string description: Dot-path into the run, e.g. workflowState.totalPrice. operator: type: string enum: - eq - neq - gt - lt - contains - isSet value: type: string required: - kind - selectionPath - operator - value - type: object properties: kind: type: string const: event eventName: type: string subjectSelectionPath: type: string occurred: type: boolean required: - kind - eventName - subjectSelectionPath - occurred - type: object properties: kind: type: string const: cdp_predicate term: type: object propertyNames: type: string additionalProperties: {} description: A single live person/computed predicate term. See journeys_authoring_catalog for its shape. required: - kind - term - type: object properties: kind: type: string const: cdp_object objectType: type: string matchAttr: type: string matchSelectionPath: type: string exists: type: boolean required: - kind - objectType - matchAttr - matchSelectionPath - exists description: One decision condition. description: type: string required: - logic - conditions description: Two-way branch. Emits YES / NO. required: - id - kind - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: CASE name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: selectionPath: type: string description: Person attribute (attributes.*) or extracted field (engagement.extracted.*) to switch on. branches: type: array items: type: object properties: id: type: string description: Stable branch id; edge handle is case:. value: type: string description: Value matched. Unique within the node. label: type: string required: - id - value description: Up to 10 branches. A case:default handle is always required. description: type: string required: - selectionPath - branches description: N-way switch on a person attribute. required: - id - kind - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: HTTP_REQUEST name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: method: type: string enum: - GET - POST - PUT - PATCH - DELETE description: HTTP method. url: type: string minLength: 1 description: Target URL. Supports {{variable}} placeholders. headers: description: Request headers as key/value pairs. type: array items: type: object properties: key: type: string value: type: string required: - key - value body: description: Request body. mode none sends no body. type: object properties: mode: type: string enum: - none - json - raw content: type: string contentType: type: string required: - mode credentialId: description: HttpCredential id used to authenticate the request. type: string timeoutMs: description: Request timeout in milliseconds. Max 30000 (30s). type: integer exclusiveMinimum: 0 maximum: 30000 maxAttempts: description: Max attempts including the first. Max 5. type: integer exclusiveMinimum: 0 maximum: 5 documentUrlTtlSeconds: description: TTL (seconds, ≤86400) for presigned engagement.documents URLs this node emits. Default 86400. type: integer exclusiveMinimum: 0 maximum: 86400 required: - method - url description: Calls an external HTTP endpoint. Emits SUCCESS or FAILED. required: - id - kind - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: EXIT name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: outcome: type: string nextInitiativeId: description: Chain into another initiative on exit. type: string description: Terminal node. required: - id - kind description: The nodes. Exactly one ENTRY and at least one EXIT are required to publish. edges: type: array items: type: object properties: from: type: string description: Source node id. to: type: string description: Target node id. sourceHandle: type: string description: The emitted signal that activates this edge (e.g. SENT, REPLIED, YES, case:). A handle may wire to at most one node. metadata: type: object properties: signalCategory: type: string enum: - lifecycle - system signalDescription: type: string required: - from - to - sourceHandle description: 'A connection: node `from` routes to `to` when it emits `sourceHandle`.' description: The connections between node handles. required: - name - actions - edges description: The full journey graph. Drafts may be incomplete; run journeys_validate before publishing. required: - definition parameters: - name: journeyId in: path required: true schema: $schema: https://json-schema.org/draft/2020-12/schema type: string minLength: 1 description: A draft journey id, or the initiative id (resolves to its current draft). responses: '200': description: Success content: application/json: schema: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: id: type: string description: Journey (workflow version) id. initiativeId: type: string description: The initiative this journey belongs to. status: type: string enum: - DRAFT - PUBLISHED - STOPPED description: DRAFT (editable), PUBLISHED (live, frozen), or STOPPED (retired). version: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Version number within the initiative. definition: type: object properties: id: description: Journey id; carried for round-trip ergonomics. Optional on create. type: string name: type: string minLength: 1 description: Journey name. metadata: type: object properties: initiativeType: type: string version: type: integer minimum: -9007199254740991 maximum: 9007199254740991 cancelOnEvents: description: Cancel an in-flight run when any of these events arrive. type: object properties: eventNames: type: array items: type: string required: - eventNames additionalProperties: false additionalProperties: false description: Optional journey-level metadata. actions: minItems: 1 type: array items: oneOf: - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: ENTRY name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: description: type: string triggerType: description: 'How people enter: manual (added by an operator or API call), segment (on entering a segment), or cdp_event (when an event is received). Defaults to manual.' type: string enum: - manual - segment - cdp_event segmentId: description: Segment id — required when triggerType is segment. type: string segmentName: description: Cached segment display name (optional). type: string eventName: description: CDP event name — required when triggerType is cdp_event. type: string maxEnrollments: description: 'Frequency cap: max enrollments per person within enrollmentWindow. Both-or-neither with enrollmentWindow.' type: integer minimum: 1 maximum: 9007199254740991 enrollmentWindow: description: Rolling window for the frequency cap. type: string additionalProperties: false description: Trigger node config. Exactly one ENTRY node per journey. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: SEND_MESSAGE name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: templateId: description: Approved WhatsApp template id. Resolve ids from the catalog. type: string templateName: type: string channel: description: Send channel. Only whatsapp is live today. type: string enum: - whatsapp - sms - email templateBindings: description: Map of template placeholder → variable reference. type: object propertyNames: type: string additionalProperties: type: string channelId: description: Sending WhatsApp channel (WABA) id. Required before publishing. type: string sendImmediately: description: Deprecated business-hours gate; prefer a preceding DELAY. type: boolean additionalProperties: false description: Sends a WhatsApp template. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: CONVERSATION_BLOCK name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: goal: type: string maxTimeout: description: How long to wait for a reply before timing out. type: string mode: type: string enum: - AGENT - ESCALATE outputs: type: array items: type: object properties: id: type: string label: type: string type: type: string enum: - string - number - date - boolean - json description: type: string builtin: type: boolean required: - id - label - type - builtin additionalProperties: false additionalProperties: false description: Legacy combined wait + AI conversation block. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: WAIT_FOR_REPLY name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: maxTimeout: description: How long to wait for the first reply before timing out. type: string additionalProperties: false description: Waits for the person to reply. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: MANAGE_CONVERSATION name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: mode: description: AGENT (AI-led) or ESCALATE (human handoff). Defaults to AGENT. type: string enum: - AGENT - ESCALATE inactivityTimeout: description: Rolling idle window (e.g. '12h'), resets on each inbound message. After this much silence the node routes INACTIVE (extracts, does not close). Range 1h–24h; requires the journey-inactivity-timeout flag. type: string additionalProperties: false description: Runs the AI-led conversation. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: DISPATCH_EVENT name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: eventName: type: string minLength: 1 description: CDP event name to record. Must match the CDP name pattern. properties: description: 'Literal string values, or { var: path } bindings resolved to typed values at dispatch time.' type: object propertyNames: type: string additionalProperties: anyOf: - type: string - type: object properties: var: type: string required: - var additionalProperties: false description: type: string required: - eventName additionalProperties: false description: Records a CDP event for the person. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: DELAY name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: mode: description: How the wait is measured. Defaults to duration. type: string enum: - duration - until_date - until_weekday duration: description: For mode duration. type: string targetAt: description: ISO 8601 instant, for mode until_date. type: string weekdays: description: ISO weekdays 1=Mon..7=Sun, for mode until_weekday. type: array items: type: integer minimum: 1 maximum: 7 windowStartMinutes: type: integer minimum: 0 maximum: 1439 windowEndMinutes: type: integer minimum: 0 maximum: 1439 timezone: description: IANA timezone. Load-bearing for until_weekday. type: string description: type: string additionalProperties: false description: Pauses the run. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: DECISION name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: logic: type: string enum: - AND - OR conditions: type: array items: oneOf: - type: object properties: kind: type: string const: value selectionPath: type: string description: Dot-path into the run, e.g. workflowState.totalPrice. operator: type: string enum: - eq - neq - gt - lt - contains - isSet value: type: string required: - kind - selectionPath - operator - value additionalProperties: false - type: object properties: kind: type: string const: event eventName: type: string subjectSelectionPath: type: string occurred: type: boolean required: - kind - eventName - subjectSelectionPath - occurred additionalProperties: false - type: object properties: kind: type: string const: cdp_predicate term: type: object propertyNames: type: string additionalProperties: {} description: A single live person/computed predicate term. See journeys_authoring_catalog for its shape. required: - kind - term additionalProperties: false - type: object properties: kind: type: string const: cdp_object objectType: type: string matchAttr: type: string matchSelectionPath: type: string exists: type: boolean required: - kind - objectType - matchAttr - matchSelectionPath - exists additionalProperties: false description: One decision condition. description: type: string required: - logic - conditions additionalProperties: false description: Two-way branch. Emits YES / NO. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: CASE name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: selectionPath: type: string description: Person attribute (attributes.*) or extracted field (engagement.extracted.*) to switch on. branches: type: array items: type: object properties: id: type: string description: Stable branch id; edge handle is case:. value: type: string description: Value matched. Unique within the node. label: type: string required: - id - value additionalProperties: false description: Up to 10 branches. A case:default handle is always required. description: type: string required: - selectionPath - branches additionalProperties: false description: N-way switch on a person attribute. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: HTTP_REQUEST name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: method: type: string enum: - GET - POST - PUT - PATCH - DELETE description: HTTP method. url: type: string minLength: 1 description: Target URL. Supports {{variable}} placeholders. headers: description: Request headers as key/value pairs. type: array items: type: object properties: key: type: string value: type: string required: - key - value additionalProperties: false body: description: Request body. mode none sends no body. type: object properties: mode: type: string enum: - none - json - raw content: type: string contentType: type: string required: - mode additionalProperties: false credentialId: description: HttpCredential id used to authenticate the request. type: string timeoutMs: description: Request timeout in milliseconds. Max 30000 (30s). type: integer exclusiveMinimum: 0 maximum: 30000 maxAttempts: description: Max attempts including the first. Max 5. type: integer exclusiveMinimum: 0 maximum: 5 documentUrlTtlSeconds: description: TTL (seconds, ≤86400) for presigned engagement.documents URLs this node emits. Default 86400. type: integer exclusiveMinimum: 0 maximum: 86400 required: - method - url additionalProperties: false description: Calls an external HTTP endpoint. Emits SUCCESS or FAILED. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: EXIT name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: outcome: type: string nextInitiativeId: description: Chain into another initiative on exit. type: string additionalProperties: false description: Terminal node. required: - id - kind additionalProperties: false description: The nodes. Exactly one ENTRY and at least one EXIT are required to publish. edges: type: array items: type: object properties: from: type: string description: Source node id. to: type: string description: Target node id. sourceHandle: type: string description: The emitted signal that activates this edge (e.g. SENT, REPLIED, YES, case:). A handle may wire to at most one node. metadata: type: object properties: signalCategory: type: string enum: - lifecycle - system signalDescription: type: string additionalProperties: false required: - from - to - sourceHandle additionalProperties: false description: 'A connection: node `from` routes to `to` when it emits `sourceHandle`.' description: The connections between node handles. required: - name - actions - edges additionalProperties: false description: The full journey graph. required: - id - initiativeId - status - version - definition additionalProperties: false '400': description: Validation failed or the request cannot proceed. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '401': description: Missing, malformed, or revoked API key. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '404': description: The resource does not exist in this organization. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '409': description: Conflicts with the current state (duplicates, wrong lifecycle state). content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '422': description: The request is well-formed but semantically invalid. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '429': description: Rate limit exceeded — retry after `Retry-After`. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '500': description: Internal server error. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '503': description: Transient error — retry with a narrower request. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error /api/v1/journeys/{journeyId}/definition: get: operationId: journeys_get_definition summary: Get journey definition description: Get a journey's full editable graph (all nodes, their config, and connections) so it can be modified and saved back. Unlike journeys_get, this is the complete authoring shape, not the sanitized public summary. tags: - Journeys parameters: - name: journeyId in: path required: true schema: $schema: https://json-schema.org/draft/2020-12/schema type: string minLength: 1 description: A draft journey id, or the initiative id (resolves to its current draft). responses: '200': description: Success content: application/json: schema: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: id: type: string description: Journey (workflow version) id. initiativeId: type: string description: The initiative this journey belongs to. status: type: string enum: - DRAFT - PUBLISHED - STOPPED description: DRAFT (editable), PUBLISHED (live, frozen), or STOPPED (retired). version: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Version number within the initiative. definition: type: object properties: id: description: Journey id; carried for round-trip ergonomics. Optional on create. type: string name: type: string minLength: 1 description: Journey name. metadata: type: object properties: initiativeType: type: string version: type: integer minimum: -9007199254740991 maximum: 9007199254740991 cancelOnEvents: description: Cancel an in-flight run when any of these events arrive. type: object properties: eventNames: type: array items: type: string required: - eventNames additionalProperties: false additionalProperties: false description: Optional journey-level metadata. actions: minItems: 1 type: array items: oneOf: - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: ENTRY name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: description: type: string triggerType: description: 'How people enter: manual (added by an operator or API call), segment (on entering a segment), or cdp_event (when an event is received). Defaults to manual.' type: string enum: - manual - segment - cdp_event segmentId: description: Segment id — required when triggerType is segment. type: string segmentName: description: Cached segment display name (optional). type: string eventName: description: CDP event name — required when triggerType is cdp_event. type: string maxEnrollments: description: 'Frequency cap: max enrollments per person within enrollmentWindow. Both-or-neither with enrollmentWindow.' type: integer minimum: 1 maximum: 9007199254740991 enrollmentWindow: description: Rolling window for the frequency cap. type: string additionalProperties: false description: Trigger node config. Exactly one ENTRY node per journey. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: SEND_MESSAGE name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: templateId: description: Approved WhatsApp template id. Resolve ids from the catalog. type: string templateName: type: string channel: description: Send channel. Only whatsapp is live today. type: string enum: - whatsapp - sms - email templateBindings: description: Map of template placeholder → variable reference. type: object propertyNames: type: string additionalProperties: type: string channelId: description: Sending WhatsApp channel (WABA) id. Required before publishing. type: string sendImmediately: description: Deprecated business-hours gate; prefer a preceding DELAY. type: boolean additionalProperties: false description: Sends a WhatsApp template. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: CONVERSATION_BLOCK name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: goal: type: string maxTimeout: description: How long to wait for a reply before timing out. type: string mode: type: string enum: - AGENT - ESCALATE outputs: type: array items: type: object properties: id: type: string label: type: string type: type: string enum: - string - number - date - boolean - json description: type: string builtin: type: boolean required: - id - label - type - builtin additionalProperties: false additionalProperties: false description: Legacy combined wait + AI conversation block. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: WAIT_FOR_REPLY name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: maxTimeout: description: How long to wait for the first reply before timing out. type: string additionalProperties: false description: Waits for the person to reply. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: MANAGE_CONVERSATION name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: mode: description: AGENT (AI-led) or ESCALATE (human handoff). Defaults to AGENT. type: string enum: - AGENT - ESCALATE inactivityTimeout: description: Rolling idle window (e.g. '12h'), resets on each inbound message. After this much silence the node routes INACTIVE (extracts, does not close). Range 1h–24h; requires the journey-inactivity-timeout flag. type: string additionalProperties: false description: Runs the AI-led conversation. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: DISPATCH_EVENT name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: eventName: type: string minLength: 1 description: CDP event name to record. Must match the CDP name pattern. properties: description: 'Literal string values, or { var: path } bindings resolved to typed values at dispatch time.' type: object propertyNames: type: string additionalProperties: anyOf: - type: string - type: object properties: var: type: string required: - var additionalProperties: false description: type: string required: - eventName additionalProperties: false description: Records a CDP event for the person. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: DELAY name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: mode: description: How the wait is measured. Defaults to duration. type: string enum: - duration - until_date - until_weekday duration: description: For mode duration. type: string targetAt: description: ISO 8601 instant, for mode until_date. type: string weekdays: description: ISO weekdays 1=Mon..7=Sun, for mode until_weekday. type: array items: type: integer minimum: 1 maximum: 7 windowStartMinutes: type: integer minimum: 0 maximum: 1439 windowEndMinutes: type: integer minimum: 0 maximum: 1439 timezone: description: IANA timezone. Load-bearing for until_weekday. type: string description: type: string additionalProperties: false description: Pauses the run. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: DECISION name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: logic: type: string enum: - AND - OR conditions: type: array items: oneOf: - type: object properties: kind: type: string const: value selectionPath: type: string description: Dot-path into the run, e.g. workflowState.totalPrice. operator: type: string enum: - eq - neq - gt - lt - contains - isSet value: type: string required: - kind - selectionPath - operator - value additionalProperties: false - type: object properties: kind: type: string const: event eventName: type: string subjectSelectionPath: type: string occurred: type: boolean required: - kind - eventName - subjectSelectionPath - occurred additionalProperties: false - type: object properties: kind: type: string const: cdp_predicate term: type: object propertyNames: type: string additionalProperties: {} description: A single live person/computed predicate term. See journeys_authoring_catalog for its shape. required: - kind - term additionalProperties: false - type: object properties: kind: type: string const: cdp_object objectType: type: string matchAttr: type: string matchSelectionPath: type: string exists: type: boolean required: - kind - objectType - matchAttr - matchSelectionPath - exists additionalProperties: false description: One decision condition. description: type: string required: - logic - conditions additionalProperties: false description: Two-way branch. Emits YES / NO. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: CASE name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: selectionPath: type: string description: Person attribute (attributes.*) or extracted field (engagement.extracted.*) to switch on. branches: type: array items: type: object properties: id: type: string description: Stable branch id; edge handle is case:. value: type: string description: Value matched. Unique within the node. label: type: string required: - id - value additionalProperties: false description: Up to 10 branches. A case:default handle is always required. description: type: string required: - selectionPath - branches additionalProperties: false description: N-way switch on a person attribute. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: HTTP_REQUEST name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: method: type: string enum: - GET - POST - PUT - PATCH - DELETE description: HTTP method. url: type: string minLength: 1 description: Target URL. Supports {{variable}} placeholders. headers: description: Request headers as key/value pairs. type: array items: type: object properties: key: type: string value: type: string required: - key - value additionalProperties: false body: description: Request body. mode none sends no body. type: object properties: mode: type: string enum: - none - json - raw content: type: string contentType: type: string required: - mode additionalProperties: false credentialId: description: HttpCredential id used to authenticate the request. type: string timeoutMs: description: Request timeout in milliseconds. Max 30000 (30s). type: integer exclusiveMinimum: 0 maximum: 30000 maxAttempts: description: Max attempts including the first. Max 5. type: integer exclusiveMinimum: 0 maximum: 5 documentUrlTtlSeconds: description: TTL (seconds, ≤86400) for presigned engagement.documents URLs this node emits. Default 86400. type: integer exclusiveMinimum: 0 maximum: 86400 required: - method - url additionalProperties: false description: Calls an external HTTP endpoint. Emits SUCCESS or FAILED. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: EXIT name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: outcome: type: string nextInitiativeId: description: Chain into another initiative on exit. type: string additionalProperties: false description: Terminal node. required: - id - kind additionalProperties: false description: The nodes. Exactly one ENTRY and at least one EXIT are required to publish. edges: type: array items: type: object properties: from: type: string description: Source node id. to: type: string description: Target node id. sourceHandle: type: string description: The emitted signal that activates this edge (e.g. SENT, REPLIED, YES, case:). A handle may wire to at most one node. metadata: type: object properties: signalCategory: type: string enum: - lifecycle - system signalDescription: type: string additionalProperties: false required: - from - to - sourceHandle additionalProperties: false description: 'A connection: node `from` routes to `to` when it emits `sourceHandle`.' description: The connections between node handles. required: - name - actions - edges additionalProperties: false description: The full journey graph. required: - id - initiativeId - status - version - definition additionalProperties: false '400': description: Validation failed or the request cannot proceed. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '401': description: Missing, malformed, or revoked API key. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '404': description: The resource does not exist in this organization. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '409': description: Conflicts with the current state (duplicates, wrong lifecycle state). content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '422': description: The request is well-formed but semantically invalid. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '429': description: Rate limit exceeded — retry after `Retry-After`. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '500': description: Internal server error. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '503': description: Transient error — retry with a narrower request. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error /api/v1/journeys/{journeyId}/edges: delete: operationId: journeys_disconnect_nodes summary: Disconnect nodes description: Remove edges leaving a node. Narrow by target and/or handle; with neither, all outgoing edges from the node are removed. tags: - Journeys parameters: - name: journeyId in: path required: true schema: $schema: https://json-schema.org/draft/2020-12/schema type: string minLength: 1 description: A draft journey id, or the initiative id (resolves to its current draft). - name: from in: query required: true schema: $schema: https://json-schema.org/draft/2020-12/schema type: string minLength: 1 description: Source node id whose edges to remove. - name: to in: query required: false schema: $schema: https://json-schema.org/draft/2020-12/schema description: Only edges to this target. type: string minLength: 1 - name: sourceHandle in: query required: false schema: $schema: https://json-schema.org/draft/2020-12/schema description: Only edges on this handle. type: string minLength: 1 responses: '200': description: Success content: application/json: schema: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: id: type: string description: Journey (workflow version) id. initiativeId: type: string description: The initiative this journey belongs to. status: type: string enum: - DRAFT - PUBLISHED - STOPPED description: DRAFT (editable), PUBLISHED (live, frozen), or STOPPED (retired). version: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Version number within the initiative. definition: type: object properties: id: description: Journey id; carried for round-trip ergonomics. Optional on create. type: string name: type: string minLength: 1 description: Journey name. metadata: type: object properties: initiativeType: type: string version: type: integer minimum: -9007199254740991 maximum: 9007199254740991 cancelOnEvents: description: Cancel an in-flight run when any of these events arrive. type: object properties: eventNames: type: array items: type: string required: - eventNames additionalProperties: false additionalProperties: false description: Optional journey-level metadata. actions: minItems: 1 type: array items: oneOf: - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: ENTRY name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: description: type: string triggerType: description: 'How people enter: manual (added by an operator or API call), segment (on entering a segment), or cdp_event (when an event is received). Defaults to manual.' type: string enum: - manual - segment - cdp_event segmentId: description: Segment id — required when triggerType is segment. type: string segmentName: description: Cached segment display name (optional). type: string eventName: description: CDP event name — required when triggerType is cdp_event. type: string maxEnrollments: description: 'Frequency cap: max enrollments per person within enrollmentWindow. Both-or-neither with enrollmentWindow.' type: integer minimum: 1 maximum: 9007199254740991 enrollmentWindow: description: Rolling window for the frequency cap. type: string additionalProperties: false description: Trigger node config. Exactly one ENTRY node per journey. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: SEND_MESSAGE name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: templateId: description: Approved WhatsApp template id. Resolve ids from the catalog. type: string templateName: type: string channel: description: Send channel. Only whatsapp is live today. type: string enum: - whatsapp - sms - email templateBindings: description: Map of template placeholder → variable reference. type: object propertyNames: type: string additionalProperties: type: string channelId: description: Sending WhatsApp channel (WABA) id. Required before publishing. type: string sendImmediately: description: Deprecated business-hours gate; prefer a preceding DELAY. type: boolean additionalProperties: false description: Sends a WhatsApp template. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: CONVERSATION_BLOCK name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: goal: type: string maxTimeout: description: How long to wait for a reply before timing out. type: string mode: type: string enum: - AGENT - ESCALATE outputs: type: array items: type: object properties: id: type: string label: type: string type: type: string enum: - string - number - date - boolean - json description: type: string builtin: type: boolean required: - id - label - type - builtin additionalProperties: false additionalProperties: false description: Legacy combined wait + AI conversation block. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: WAIT_FOR_REPLY name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: maxTimeout: description: How long to wait for the first reply before timing out. type: string additionalProperties: false description: Waits for the person to reply. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: MANAGE_CONVERSATION name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: mode: description: AGENT (AI-led) or ESCALATE (human handoff). Defaults to AGENT. type: string enum: - AGENT - ESCALATE inactivityTimeout: description: Rolling idle window (e.g. '12h'), resets on each inbound message. After this much silence the node routes INACTIVE (extracts, does not close). Range 1h–24h; requires the journey-inactivity-timeout flag. type: string additionalProperties: false description: Runs the AI-led conversation. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: DISPATCH_EVENT name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: eventName: type: string minLength: 1 description: CDP event name to record. Must match the CDP name pattern. properties: description: 'Literal string values, or { var: path } bindings resolved to typed values at dispatch time.' type: object propertyNames: type: string additionalProperties: anyOf: - type: string - type: object properties: var: type: string required: - var additionalProperties: false description: type: string required: - eventName additionalProperties: false description: Records a CDP event for the person. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: DELAY name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: mode: description: How the wait is measured. Defaults to duration. type: string enum: - duration - until_date - until_weekday duration: description: For mode duration. type: string targetAt: description: ISO 8601 instant, for mode until_date. type: string weekdays: description: ISO weekdays 1=Mon..7=Sun, for mode until_weekday. type: array items: type: integer minimum: 1 maximum: 7 windowStartMinutes: type: integer minimum: 0 maximum: 1439 windowEndMinutes: type: integer minimum: 0 maximum: 1439 timezone: description: IANA timezone. Load-bearing for until_weekday. type: string description: type: string additionalProperties: false description: Pauses the run. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: DECISION name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: logic: type: string enum: - AND - OR conditions: type: array items: oneOf: - type: object properties: kind: type: string const: value selectionPath: type: string description: Dot-path into the run, e.g. workflowState.totalPrice. operator: type: string enum: - eq - neq - gt - lt - contains - isSet value: type: string required: - kind - selectionPath - operator - value additionalProperties: false - type: object properties: kind: type: string const: event eventName: type: string subjectSelectionPath: type: string occurred: type: boolean required: - kind - eventName - subjectSelectionPath - occurred additionalProperties: false - type: object properties: kind: type: string const: cdp_predicate term: type: object propertyNames: type: string additionalProperties: {} description: A single live person/computed predicate term. See journeys_authoring_catalog for its shape. required: - kind - term additionalProperties: false - type: object properties: kind: type: string const: cdp_object objectType: type: string matchAttr: type: string matchSelectionPath: type: string exists: type: boolean required: - kind - objectType - matchAttr - matchSelectionPath - exists additionalProperties: false description: One decision condition. description: type: string required: - logic - conditions additionalProperties: false description: Two-way branch. Emits YES / NO. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: CASE name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: selectionPath: type: string description: Person attribute (attributes.*) or extracted field (engagement.extracted.*) to switch on. branches: type: array items: type: object properties: id: type: string description: Stable branch id; edge handle is case:. value: type: string description: Value matched. Unique within the node. label: type: string required: - id - value additionalProperties: false description: Up to 10 branches. A case:default handle is always required. description: type: string required: - selectionPath - branches additionalProperties: false description: N-way switch on a person attribute. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: HTTP_REQUEST name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: method: type: string enum: - GET - POST - PUT - PATCH - DELETE description: HTTP method. url: type: string minLength: 1 description: Target URL. Supports {{variable}} placeholders. headers: description: Request headers as key/value pairs. type: array items: type: object properties: key: type: string value: type: string required: - key - value additionalProperties: false body: description: Request body. mode none sends no body. type: object properties: mode: type: string enum: - none - json - raw content: type: string contentType: type: string required: - mode additionalProperties: false credentialId: description: HttpCredential id used to authenticate the request. type: string timeoutMs: description: Request timeout in milliseconds. Max 30000 (30s). type: integer exclusiveMinimum: 0 maximum: 30000 maxAttempts: description: Max attempts including the first. Max 5. type: integer exclusiveMinimum: 0 maximum: 5 documentUrlTtlSeconds: description: TTL (seconds, ≤86400) for presigned engagement.documents URLs this node emits. Default 86400. type: integer exclusiveMinimum: 0 maximum: 86400 required: - method - url additionalProperties: false description: Calls an external HTTP endpoint. Emits SUCCESS or FAILED. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: EXIT name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: outcome: type: string nextInitiativeId: description: Chain into another initiative on exit. type: string additionalProperties: false description: Terminal node. required: - id - kind additionalProperties: false description: The nodes. Exactly one ENTRY and at least one EXIT are required to publish. edges: type: array items: type: object properties: from: type: string description: Source node id. to: type: string description: Target node id. sourceHandle: type: string description: The emitted signal that activates this edge (e.g. SENT, REPLIED, YES, case:). A handle may wire to at most one node. metadata: type: object properties: signalCategory: type: string enum: - lifecycle - system signalDescription: type: string additionalProperties: false required: - from - to - sourceHandle additionalProperties: false description: 'A connection: node `from` routes to `to` when it emits `sourceHandle`.' description: The connections between node handles. required: - name - actions - edges additionalProperties: false description: The full journey graph. required: - id - initiativeId - status - version - definition additionalProperties: false '400': description: Validation failed or the request cannot proceed. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '401': description: Missing, malformed, or revoked API key. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '404': description: The resource does not exist in this organization. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '409': description: Conflicts with the current state (duplicates, wrong lifecycle state). content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '422': description: The request is well-formed but semantically invalid. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '429': description: Rate limit exceeded — retry after `Retry-After`. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '500': description: Internal server error. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '503': description: Transient error — retry with a narrower request. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error post: operationId: journeys_connect_nodes summary: Connect nodes description: Wire an edge from one node to another on a given output handle (the emitted signal, e.g. SENT, REPLIED, YES, case:). A handle can wire to only one node. tags: - Journeys requestBody: required: true content: application/json: schema: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: from: type: string minLength: 1 description: Source node id. to: type: string minLength: 1 description: Target node id. sourceHandle: type: string minLength: 1 description: The source node output handle this edge fires on. required: - from - to - sourceHandle parameters: - name: journeyId in: path required: true schema: $schema: https://json-schema.org/draft/2020-12/schema type: string minLength: 1 description: A draft journey id, or the initiative id (resolves to its current draft). responses: '201': description: Success content: application/json: schema: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: id: type: string description: Journey (workflow version) id. initiativeId: type: string description: The initiative this journey belongs to. status: type: string enum: - DRAFT - PUBLISHED - STOPPED description: DRAFT (editable), PUBLISHED (live, frozen), or STOPPED (retired). version: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Version number within the initiative. definition: type: object properties: id: description: Journey id; carried for round-trip ergonomics. Optional on create. type: string name: type: string minLength: 1 description: Journey name. metadata: type: object properties: initiativeType: type: string version: type: integer minimum: -9007199254740991 maximum: 9007199254740991 cancelOnEvents: description: Cancel an in-flight run when any of these events arrive. type: object properties: eventNames: type: array items: type: string required: - eventNames additionalProperties: false additionalProperties: false description: Optional journey-level metadata. actions: minItems: 1 type: array items: oneOf: - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: ENTRY name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: description: type: string triggerType: description: 'How people enter: manual (added by an operator or API call), segment (on entering a segment), or cdp_event (when an event is received). Defaults to manual.' type: string enum: - manual - segment - cdp_event segmentId: description: Segment id — required when triggerType is segment. type: string segmentName: description: Cached segment display name (optional). type: string eventName: description: CDP event name — required when triggerType is cdp_event. type: string maxEnrollments: description: 'Frequency cap: max enrollments per person within enrollmentWindow. Both-or-neither with enrollmentWindow.' type: integer minimum: 1 maximum: 9007199254740991 enrollmentWindow: description: Rolling window for the frequency cap. type: string additionalProperties: false description: Trigger node config. Exactly one ENTRY node per journey. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: SEND_MESSAGE name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: templateId: description: Approved WhatsApp template id. Resolve ids from the catalog. type: string templateName: type: string channel: description: Send channel. Only whatsapp is live today. type: string enum: - whatsapp - sms - email templateBindings: description: Map of template placeholder → variable reference. type: object propertyNames: type: string additionalProperties: type: string channelId: description: Sending WhatsApp channel (WABA) id. Required before publishing. type: string sendImmediately: description: Deprecated business-hours gate; prefer a preceding DELAY. type: boolean additionalProperties: false description: Sends a WhatsApp template. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: CONVERSATION_BLOCK name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: goal: type: string maxTimeout: description: How long to wait for a reply before timing out. type: string mode: type: string enum: - AGENT - ESCALATE outputs: type: array items: type: object properties: id: type: string label: type: string type: type: string enum: - string - number - date - boolean - json description: type: string builtin: type: boolean required: - id - label - type - builtin additionalProperties: false additionalProperties: false description: Legacy combined wait + AI conversation block. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: WAIT_FOR_REPLY name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: maxTimeout: description: How long to wait for the first reply before timing out. type: string additionalProperties: false description: Waits for the person to reply. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: MANAGE_CONVERSATION name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: mode: description: AGENT (AI-led) or ESCALATE (human handoff). Defaults to AGENT. type: string enum: - AGENT - ESCALATE inactivityTimeout: description: Rolling idle window (e.g. '12h'), resets on each inbound message. After this much silence the node routes INACTIVE (extracts, does not close). Range 1h–24h; requires the journey-inactivity-timeout flag. type: string additionalProperties: false description: Runs the AI-led conversation. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: DISPATCH_EVENT name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: eventName: type: string minLength: 1 description: CDP event name to record. Must match the CDP name pattern. properties: description: 'Literal string values, or { var: path } bindings resolved to typed values at dispatch time.' type: object propertyNames: type: string additionalProperties: anyOf: - type: string - type: object properties: var: type: string required: - var additionalProperties: false description: type: string required: - eventName additionalProperties: false description: Records a CDP event for the person. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: DELAY name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: mode: description: How the wait is measured. Defaults to duration. type: string enum: - duration - until_date - until_weekday duration: description: For mode duration. type: string targetAt: description: ISO 8601 instant, for mode until_date. type: string weekdays: description: ISO weekdays 1=Mon..7=Sun, for mode until_weekday. type: array items: type: integer minimum: 1 maximum: 7 windowStartMinutes: type: integer minimum: 0 maximum: 1439 windowEndMinutes: type: integer minimum: 0 maximum: 1439 timezone: description: IANA timezone. Load-bearing for until_weekday. type: string description: type: string additionalProperties: false description: Pauses the run. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: DECISION name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: logic: type: string enum: - AND - OR conditions: type: array items: oneOf: - type: object properties: kind: type: string const: value selectionPath: type: string description: Dot-path into the run, e.g. workflowState.totalPrice. operator: type: string enum: - eq - neq - gt - lt - contains - isSet value: type: string required: - kind - selectionPath - operator - value additionalProperties: false - type: object properties: kind: type: string const: event eventName: type: string subjectSelectionPath: type: string occurred: type: boolean required: - kind - eventName - subjectSelectionPath - occurred additionalProperties: false - type: object properties: kind: type: string const: cdp_predicate term: type: object propertyNames: type: string additionalProperties: {} description: A single live person/computed predicate term. See journeys_authoring_catalog for its shape. required: - kind - term additionalProperties: false - type: object properties: kind: type: string const: cdp_object objectType: type: string matchAttr: type: string matchSelectionPath: type: string exists: type: boolean required: - kind - objectType - matchAttr - matchSelectionPath - exists additionalProperties: false description: One decision condition. description: type: string required: - logic - conditions additionalProperties: false description: Two-way branch. Emits YES / NO. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: CASE name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: selectionPath: type: string description: Person attribute (attributes.*) or extracted field (engagement.extracted.*) to switch on. branches: type: array items: type: object properties: id: type: string description: Stable branch id; edge handle is case:. value: type: string description: Value matched. Unique within the node. label: type: string required: - id - value additionalProperties: false description: Up to 10 branches. A case:default handle is always required. description: type: string required: - selectionPath - branches additionalProperties: false description: N-way switch on a person attribute. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: HTTP_REQUEST name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: method: type: string enum: - GET - POST - PUT - PATCH - DELETE description: HTTP method. url: type: string minLength: 1 description: Target URL. Supports {{variable}} placeholders. headers: description: Request headers as key/value pairs. type: array items: type: object properties: key: type: string value: type: string required: - key - value additionalProperties: false body: description: Request body. mode none sends no body. type: object properties: mode: type: string enum: - none - json - raw content: type: string contentType: type: string required: - mode additionalProperties: false credentialId: description: HttpCredential id used to authenticate the request. type: string timeoutMs: description: Request timeout in milliseconds. Max 30000 (30s). type: integer exclusiveMinimum: 0 maximum: 30000 maxAttempts: description: Max attempts including the first. Max 5. type: integer exclusiveMinimum: 0 maximum: 5 documentUrlTtlSeconds: description: TTL (seconds, ≤86400) for presigned engagement.documents URLs this node emits. Default 86400. type: integer exclusiveMinimum: 0 maximum: 86400 required: - method - url additionalProperties: false description: Calls an external HTTP endpoint. Emits SUCCESS or FAILED. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: EXIT name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: outcome: type: string nextInitiativeId: description: Chain into another initiative on exit. type: string additionalProperties: false description: Terminal node. required: - id - kind additionalProperties: false description: The nodes. Exactly one ENTRY and at least one EXIT are required to publish. edges: type: array items: type: object properties: from: type: string description: Source node id. to: type: string description: Target node id. sourceHandle: type: string description: The emitted signal that activates this edge (e.g. SENT, REPLIED, YES, case:). A handle may wire to at most one node. metadata: type: object properties: signalCategory: type: string enum: - lifecycle - system signalDescription: type: string additionalProperties: false required: - from - to - sourceHandle additionalProperties: false description: 'A connection: node `from` routes to `to` when it emits `sourceHandle`.' description: The connections between node handles. required: - name - actions - edges additionalProperties: false description: The full journey graph. required: - id - initiativeId - status - version - definition additionalProperties: false '400': description: Validation failed or the request cannot proceed. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '401': description: Missing, malformed, or revoked API key. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '404': description: The resource does not exist in this organization. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '409': description: Conflicts with the current state (duplicates, wrong lifecycle state). content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '422': description: The request is well-formed but semantically invalid. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '429': description: Rate limit exceeded — retry after `Retry-After`. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '500': description: Internal server error. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '503': description: Transient error — retry with a narrower request. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error /api/v1/journeys/{journeyId}/fork: post: operationId: journeys_create_draft_from_published summary: Fork journey description: Copy a PUBLISHED journey into a fresh editable draft. The live version keeps running until the new draft is published. Use this to edit a live journey safely. tags: - Journeys parameters: - name: journeyId in: path required: true schema: $schema: https://json-schema.org/draft/2020-12/schema type: string minLength: 1 description: A published journey id, or the initiative id (resolves to its live journey). responses: '201': description: Success content: application/json: schema: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: id: type: string description: Journey (workflow version) id. initiativeId: type: string description: The initiative this journey belongs to. status: type: string enum: - DRAFT - PUBLISHED - STOPPED description: DRAFT (editable), PUBLISHED (live, frozen), or STOPPED (retired). version: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Version number within the initiative. definition: type: object properties: id: description: Journey id; carried for round-trip ergonomics. Optional on create. type: string name: type: string minLength: 1 description: Journey name. metadata: type: object properties: initiativeType: type: string version: type: integer minimum: -9007199254740991 maximum: 9007199254740991 cancelOnEvents: description: Cancel an in-flight run when any of these events arrive. type: object properties: eventNames: type: array items: type: string required: - eventNames additionalProperties: false additionalProperties: false description: Optional journey-level metadata. actions: minItems: 1 type: array items: oneOf: - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: ENTRY name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: description: type: string triggerType: description: 'How people enter: manual (added by an operator or API call), segment (on entering a segment), or cdp_event (when an event is received). Defaults to manual.' type: string enum: - manual - segment - cdp_event segmentId: description: Segment id — required when triggerType is segment. type: string segmentName: description: Cached segment display name (optional). type: string eventName: description: CDP event name — required when triggerType is cdp_event. type: string maxEnrollments: description: 'Frequency cap: max enrollments per person within enrollmentWindow. Both-or-neither with enrollmentWindow.' type: integer minimum: 1 maximum: 9007199254740991 enrollmentWindow: description: Rolling window for the frequency cap. type: string additionalProperties: false description: Trigger node config. Exactly one ENTRY node per journey. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: SEND_MESSAGE name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: templateId: description: Approved WhatsApp template id. Resolve ids from the catalog. type: string templateName: type: string channel: description: Send channel. Only whatsapp is live today. type: string enum: - whatsapp - sms - email templateBindings: description: Map of template placeholder → variable reference. type: object propertyNames: type: string additionalProperties: type: string channelId: description: Sending WhatsApp channel (WABA) id. Required before publishing. type: string sendImmediately: description: Deprecated business-hours gate; prefer a preceding DELAY. type: boolean additionalProperties: false description: Sends a WhatsApp template. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: CONVERSATION_BLOCK name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: goal: type: string maxTimeout: description: How long to wait for a reply before timing out. type: string mode: type: string enum: - AGENT - ESCALATE outputs: type: array items: type: object properties: id: type: string label: type: string type: type: string enum: - string - number - date - boolean - json description: type: string builtin: type: boolean required: - id - label - type - builtin additionalProperties: false additionalProperties: false description: Legacy combined wait + AI conversation block. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: WAIT_FOR_REPLY name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: maxTimeout: description: How long to wait for the first reply before timing out. type: string additionalProperties: false description: Waits for the person to reply. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: MANAGE_CONVERSATION name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: mode: description: AGENT (AI-led) or ESCALATE (human handoff). Defaults to AGENT. type: string enum: - AGENT - ESCALATE inactivityTimeout: description: Rolling idle window (e.g. '12h'), resets on each inbound message. After this much silence the node routes INACTIVE (extracts, does not close). Range 1h–24h; requires the journey-inactivity-timeout flag. type: string additionalProperties: false description: Runs the AI-led conversation. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: DISPATCH_EVENT name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: eventName: type: string minLength: 1 description: CDP event name to record. Must match the CDP name pattern. properties: description: 'Literal string values, or { var: path } bindings resolved to typed values at dispatch time.' type: object propertyNames: type: string additionalProperties: anyOf: - type: string - type: object properties: var: type: string required: - var additionalProperties: false description: type: string required: - eventName additionalProperties: false description: Records a CDP event for the person. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: DELAY name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: mode: description: How the wait is measured. Defaults to duration. type: string enum: - duration - until_date - until_weekday duration: description: For mode duration. type: string targetAt: description: ISO 8601 instant, for mode until_date. type: string weekdays: description: ISO weekdays 1=Mon..7=Sun, for mode until_weekday. type: array items: type: integer minimum: 1 maximum: 7 windowStartMinutes: type: integer minimum: 0 maximum: 1439 windowEndMinutes: type: integer minimum: 0 maximum: 1439 timezone: description: IANA timezone. Load-bearing for until_weekday. type: string description: type: string additionalProperties: false description: Pauses the run. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: DECISION name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: logic: type: string enum: - AND - OR conditions: type: array items: oneOf: - type: object properties: kind: type: string const: value selectionPath: type: string description: Dot-path into the run, e.g. workflowState.totalPrice. operator: type: string enum: - eq - neq - gt - lt - contains - isSet value: type: string required: - kind - selectionPath - operator - value additionalProperties: false - type: object properties: kind: type: string const: event eventName: type: string subjectSelectionPath: type: string occurred: type: boolean required: - kind - eventName - subjectSelectionPath - occurred additionalProperties: false - type: object properties: kind: type: string const: cdp_predicate term: type: object propertyNames: type: string additionalProperties: {} description: A single live person/computed predicate term. See journeys_authoring_catalog for its shape. required: - kind - term additionalProperties: false - type: object properties: kind: type: string const: cdp_object objectType: type: string matchAttr: type: string matchSelectionPath: type: string exists: type: boolean required: - kind - objectType - matchAttr - matchSelectionPath - exists additionalProperties: false description: One decision condition. description: type: string required: - logic - conditions additionalProperties: false description: Two-way branch. Emits YES / NO. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: CASE name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: selectionPath: type: string description: Person attribute (attributes.*) or extracted field (engagement.extracted.*) to switch on. branches: type: array items: type: object properties: id: type: string description: Stable branch id; edge handle is case:. value: type: string description: Value matched. Unique within the node. label: type: string required: - id - value additionalProperties: false description: Up to 10 branches. A case:default handle is always required. description: type: string required: - selectionPath - branches additionalProperties: false description: N-way switch on a person attribute. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: HTTP_REQUEST name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: method: type: string enum: - GET - POST - PUT - PATCH - DELETE description: HTTP method. url: type: string minLength: 1 description: Target URL. Supports {{variable}} placeholders. headers: description: Request headers as key/value pairs. type: array items: type: object properties: key: type: string value: type: string required: - key - value additionalProperties: false body: description: Request body. mode none sends no body. type: object properties: mode: type: string enum: - none - json - raw content: type: string contentType: type: string required: - mode additionalProperties: false credentialId: description: HttpCredential id used to authenticate the request. type: string timeoutMs: description: Request timeout in milliseconds. Max 30000 (30s). type: integer exclusiveMinimum: 0 maximum: 30000 maxAttempts: description: Max attempts including the first. Max 5. type: integer exclusiveMinimum: 0 maximum: 5 documentUrlTtlSeconds: description: TTL (seconds, ≤86400) for presigned engagement.documents URLs this node emits. Default 86400. type: integer exclusiveMinimum: 0 maximum: 86400 required: - method - url additionalProperties: false description: Calls an external HTTP endpoint. Emits SUCCESS or FAILED. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: EXIT name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: outcome: type: string nextInitiativeId: description: Chain into another initiative on exit. type: string additionalProperties: false description: Terminal node. required: - id - kind additionalProperties: false description: The nodes. Exactly one ENTRY and at least one EXIT are required to publish. edges: type: array items: type: object properties: from: type: string description: Source node id. to: type: string description: Target node id. sourceHandle: type: string description: The emitted signal that activates this edge (e.g. SENT, REPLIED, YES, case:). A handle may wire to at most one node. metadata: type: object properties: signalCategory: type: string enum: - lifecycle - system signalDescription: type: string additionalProperties: false required: - from - to - sourceHandle additionalProperties: false description: 'A connection: node `from` routes to `to` when it emits `sourceHandle`.' description: The connections between node handles. required: - name - actions - edges additionalProperties: false description: The full journey graph. required: - id - initiativeId - status - version - definition additionalProperties: false '400': description: Validation failed or the request cannot proceed. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '401': description: Missing, malformed, or revoked API key. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '404': description: The resource does not exist in this organization. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '409': description: Conflicts with the current state (duplicates, wrong lifecycle state). content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '422': description: The request is well-formed but semantically invalid. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '429': description: Rate limit exceeded — retry after `Retry-After`. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '500': description: Internal server error. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '503': description: Transient error — retry with a narrower request. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error /api/v1/journeys/{journeyId}/message-variables: get: operationId: journeys_message_variables summary: Message variable catalog description: List the variables a SEND_MESSAGE template binding can reference for a journey — the same set the builder offers. Bind a template placeholder to one of the returned `path` values (custom person attributes are `person.`, NOT `attributes.` — that is the DECISION/CASE condition syntax). Pass a journey id or its initiative id. tags: - Journeys parameters: - name: journeyId in: path required: true schema: $schema: https://json-schema.org/draft/2020-12/schema type: string minLength: 1 description: A journey id, or the initiative id (resolves to its current draft). responses: '200': description: Success content: application/json: schema: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: groups: type: array items: type: object properties: id: type: string label: type: string description: type: string variables: type: array items: type: object properties: key: type: string label: type: string path: type: string description: Bind a placeholder to this exact value, e.g. person.bank. description: type: string required: - key - label - path additionalProperties: false required: - id - label - variables additionalProperties: false required: - groups additionalProperties: false '400': description: Validation failed or the request cannot proceed. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '401': description: Missing, malformed, or revoked API key. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '404': description: The resource does not exist in this organization. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '409': description: Conflicts with the current state (duplicates, wrong lifecycle state). content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '422': description: The request is well-formed but semantically invalid. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '429': description: Rate limit exceeded — retry after `Retry-After`. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '500': description: Internal server error. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '503': description: Transient error — retry with a narrower request. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error /api/v1/journeys/{journeyId}/nodes: post: operationId: journeys_add_node summary: Add node description: Add one node to a draft journey. Positions are optional (auto-laid-out). Wire it up separately with journeys_connect_nodes. tags: - Journeys requestBody: required: true content: application/json: schema: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: node: oneOf: - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: ENTRY name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: description: type: string triggerType: description: 'How people enter: manual (added by an operator or API call), segment (on entering a segment), or cdp_event (when an event is received). Defaults to manual.' type: string enum: - manual - segment - cdp_event segmentId: description: Segment id — required when triggerType is segment. type: string segmentName: description: Cached segment display name (optional). type: string eventName: description: CDP event name — required when triggerType is cdp_event. type: string maxEnrollments: description: 'Frequency cap: max enrollments per person within enrollmentWindow. Both-or-neither with enrollmentWindow.' type: integer minimum: 1 maximum: 9007199254740991 enrollmentWindow: description: Rolling window for the frequency cap. type: string description: Trigger node config. Exactly one ENTRY node per journey. required: - id - kind - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: SEND_MESSAGE name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: templateId: description: Approved WhatsApp template id. Resolve ids from the catalog. type: string templateName: type: string channel: description: Send channel. Only whatsapp is live today. type: string enum: - whatsapp - sms - email templateBindings: description: Map of template placeholder → variable reference. type: object propertyNames: type: string additionalProperties: type: string channelId: description: Sending WhatsApp channel (WABA) id. Required before publishing. type: string sendImmediately: description: Deprecated business-hours gate; prefer a preceding DELAY. type: boolean description: Sends a WhatsApp template. required: - id - kind - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: CONVERSATION_BLOCK name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: goal: type: string maxTimeout: description: How long to wait for a reply before timing out. type: string mode: type: string enum: - AGENT - ESCALATE outputs: type: array items: type: object properties: id: type: string label: type: string type: type: string enum: - string - number - date - boolean - json description: type: string builtin: type: boolean required: - id - label - type - builtin description: Legacy combined wait + AI conversation block. required: - id - kind - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: WAIT_FOR_REPLY name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: maxTimeout: description: How long to wait for the first reply before timing out. type: string description: Waits for the person to reply. required: - id - kind - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: MANAGE_CONVERSATION name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: mode: description: AGENT (AI-led) or ESCALATE (human handoff). Defaults to AGENT. type: string enum: - AGENT - ESCALATE inactivityTimeout: description: Rolling idle window (e.g. '12h'), resets on each inbound message. After this much silence the node routes INACTIVE (extracts, does not close). Range 1h–24h; requires the journey-inactivity-timeout flag. type: string description: Runs the AI-led conversation. required: - id - kind - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: DISPATCH_EVENT name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: eventName: type: string minLength: 1 description: CDP event name to record. Must match the CDP name pattern. properties: description: 'Literal string values, or { var: path } bindings resolved to typed values at dispatch time.' type: object propertyNames: type: string additionalProperties: anyOf: - type: string - type: object properties: var: type: string required: - var description: type: string required: - eventName description: Records a CDP event for the person. required: - id - kind - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: DELAY name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: mode: description: How the wait is measured. Defaults to duration. type: string enum: - duration - until_date - until_weekday duration: description: For mode duration. type: string targetAt: description: ISO 8601 instant, for mode until_date. type: string weekdays: description: ISO weekdays 1=Mon..7=Sun, for mode until_weekday. type: array items: type: integer minimum: 1 maximum: 7 windowStartMinutes: type: integer minimum: 0 maximum: 1439 windowEndMinutes: type: integer minimum: 0 maximum: 1439 timezone: description: IANA timezone. Load-bearing for until_weekday. type: string description: type: string description: Pauses the run. required: - id - kind - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: DECISION name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: logic: type: string enum: - AND - OR conditions: type: array items: oneOf: - type: object properties: kind: type: string const: value selectionPath: type: string description: Dot-path into the run, e.g. workflowState.totalPrice. operator: type: string enum: - eq - neq - gt - lt - contains - isSet value: type: string required: - kind - selectionPath - operator - value - type: object properties: kind: type: string const: event eventName: type: string subjectSelectionPath: type: string occurred: type: boolean required: - kind - eventName - subjectSelectionPath - occurred - type: object properties: kind: type: string const: cdp_predicate term: type: object propertyNames: type: string additionalProperties: {} description: A single live person/computed predicate term. See journeys_authoring_catalog for its shape. required: - kind - term - type: object properties: kind: type: string const: cdp_object objectType: type: string matchAttr: type: string matchSelectionPath: type: string exists: type: boolean required: - kind - objectType - matchAttr - matchSelectionPath - exists description: One decision condition. description: type: string required: - logic - conditions description: Two-way branch. Emits YES / NO. required: - id - kind - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: CASE name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: selectionPath: type: string description: Person attribute (attributes.*) or extracted field (engagement.extracted.*) to switch on. branches: type: array items: type: object properties: id: type: string description: Stable branch id; edge handle is case:. value: type: string description: Value matched. Unique within the node. label: type: string required: - id - value description: Up to 10 branches. A case:default handle is always required. description: type: string required: - selectionPath - branches description: N-way switch on a person attribute. required: - id - kind - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: HTTP_REQUEST name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: method: type: string enum: - GET - POST - PUT - PATCH - DELETE description: HTTP method. url: type: string minLength: 1 description: Target URL. Supports {{variable}} placeholders. headers: description: Request headers as key/value pairs. type: array items: type: object properties: key: type: string value: type: string required: - key - value body: description: Request body. mode none sends no body. type: object properties: mode: type: string enum: - none - json - raw content: type: string contentType: type: string required: - mode credentialId: description: HttpCredential id used to authenticate the request. type: string timeoutMs: description: Request timeout in milliseconds. Max 30000 (30s). type: integer exclusiveMinimum: 0 maximum: 30000 maxAttempts: description: Max attempts including the first. Max 5. type: integer exclusiveMinimum: 0 maximum: 5 documentUrlTtlSeconds: description: TTL (seconds, ≤86400) for presigned engagement.documents URLs this node emits. Default 86400. type: integer exclusiveMinimum: 0 maximum: 86400 required: - method - url description: Calls an external HTTP endpoint. Emits SUCCESS or FAILED. required: - id - kind - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: EXIT name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: outcome: type: string nextInitiativeId: description: Chain into another initiative on exit. type: string description: Terminal node. required: - id - kind required: - node parameters: - name: journeyId in: path required: true schema: $schema: https://json-schema.org/draft/2020-12/schema type: string minLength: 1 description: A draft journey id, or the initiative id (resolves to its current draft). responses: '201': description: Success content: application/json: schema: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: id: type: string description: Journey (workflow version) id. initiativeId: type: string description: The initiative this journey belongs to. status: type: string enum: - DRAFT - PUBLISHED - STOPPED description: DRAFT (editable), PUBLISHED (live, frozen), or STOPPED (retired). version: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Version number within the initiative. definition: type: object properties: id: description: Journey id; carried for round-trip ergonomics. Optional on create. type: string name: type: string minLength: 1 description: Journey name. metadata: type: object properties: initiativeType: type: string version: type: integer minimum: -9007199254740991 maximum: 9007199254740991 cancelOnEvents: description: Cancel an in-flight run when any of these events arrive. type: object properties: eventNames: type: array items: type: string required: - eventNames additionalProperties: false additionalProperties: false description: Optional journey-level metadata. actions: minItems: 1 type: array items: oneOf: - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: ENTRY name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: description: type: string triggerType: description: 'How people enter: manual (added by an operator or API call), segment (on entering a segment), or cdp_event (when an event is received). Defaults to manual.' type: string enum: - manual - segment - cdp_event segmentId: description: Segment id — required when triggerType is segment. type: string segmentName: description: Cached segment display name (optional). type: string eventName: description: CDP event name — required when triggerType is cdp_event. type: string maxEnrollments: description: 'Frequency cap: max enrollments per person within enrollmentWindow. Both-or-neither with enrollmentWindow.' type: integer minimum: 1 maximum: 9007199254740991 enrollmentWindow: description: Rolling window for the frequency cap. type: string additionalProperties: false description: Trigger node config. Exactly one ENTRY node per journey. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: SEND_MESSAGE name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: templateId: description: Approved WhatsApp template id. Resolve ids from the catalog. type: string templateName: type: string channel: description: Send channel. Only whatsapp is live today. type: string enum: - whatsapp - sms - email templateBindings: description: Map of template placeholder → variable reference. type: object propertyNames: type: string additionalProperties: type: string channelId: description: Sending WhatsApp channel (WABA) id. Required before publishing. type: string sendImmediately: description: Deprecated business-hours gate; prefer a preceding DELAY. type: boolean additionalProperties: false description: Sends a WhatsApp template. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: CONVERSATION_BLOCK name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: goal: type: string maxTimeout: description: How long to wait for a reply before timing out. type: string mode: type: string enum: - AGENT - ESCALATE outputs: type: array items: type: object properties: id: type: string label: type: string type: type: string enum: - string - number - date - boolean - json description: type: string builtin: type: boolean required: - id - label - type - builtin additionalProperties: false additionalProperties: false description: Legacy combined wait + AI conversation block. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: WAIT_FOR_REPLY name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: maxTimeout: description: How long to wait for the first reply before timing out. type: string additionalProperties: false description: Waits for the person to reply. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: MANAGE_CONVERSATION name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: mode: description: AGENT (AI-led) or ESCALATE (human handoff). Defaults to AGENT. type: string enum: - AGENT - ESCALATE inactivityTimeout: description: Rolling idle window (e.g. '12h'), resets on each inbound message. After this much silence the node routes INACTIVE (extracts, does not close). Range 1h–24h; requires the journey-inactivity-timeout flag. type: string additionalProperties: false description: Runs the AI-led conversation. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: DISPATCH_EVENT name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: eventName: type: string minLength: 1 description: CDP event name to record. Must match the CDP name pattern. properties: description: 'Literal string values, or { var: path } bindings resolved to typed values at dispatch time.' type: object propertyNames: type: string additionalProperties: anyOf: - type: string - type: object properties: var: type: string required: - var additionalProperties: false description: type: string required: - eventName additionalProperties: false description: Records a CDP event for the person. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: DELAY name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: mode: description: How the wait is measured. Defaults to duration. type: string enum: - duration - until_date - until_weekday duration: description: For mode duration. type: string targetAt: description: ISO 8601 instant, for mode until_date. type: string weekdays: description: ISO weekdays 1=Mon..7=Sun, for mode until_weekday. type: array items: type: integer minimum: 1 maximum: 7 windowStartMinutes: type: integer minimum: 0 maximum: 1439 windowEndMinutes: type: integer minimum: 0 maximum: 1439 timezone: description: IANA timezone. Load-bearing for until_weekday. type: string description: type: string additionalProperties: false description: Pauses the run. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: DECISION name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: logic: type: string enum: - AND - OR conditions: type: array items: oneOf: - type: object properties: kind: type: string const: value selectionPath: type: string description: Dot-path into the run, e.g. workflowState.totalPrice. operator: type: string enum: - eq - neq - gt - lt - contains - isSet value: type: string required: - kind - selectionPath - operator - value additionalProperties: false - type: object properties: kind: type: string const: event eventName: type: string subjectSelectionPath: type: string occurred: type: boolean required: - kind - eventName - subjectSelectionPath - occurred additionalProperties: false - type: object properties: kind: type: string const: cdp_predicate term: type: object propertyNames: type: string additionalProperties: {} description: A single live person/computed predicate term. See journeys_authoring_catalog for its shape. required: - kind - term additionalProperties: false - type: object properties: kind: type: string const: cdp_object objectType: type: string matchAttr: type: string matchSelectionPath: type: string exists: type: boolean required: - kind - objectType - matchAttr - matchSelectionPath - exists additionalProperties: false description: One decision condition. description: type: string required: - logic - conditions additionalProperties: false description: Two-way branch. Emits YES / NO. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: CASE name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: selectionPath: type: string description: Person attribute (attributes.*) or extracted field (engagement.extracted.*) to switch on. branches: type: array items: type: object properties: id: type: string description: Stable branch id; edge handle is case:. value: type: string description: Value matched. Unique within the node. label: type: string required: - id - value additionalProperties: false description: Up to 10 branches. A case:default handle is always required. description: type: string required: - selectionPath - branches additionalProperties: false description: N-way switch on a person attribute. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: HTTP_REQUEST name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: method: type: string enum: - GET - POST - PUT - PATCH - DELETE description: HTTP method. url: type: string minLength: 1 description: Target URL. Supports {{variable}} placeholders. headers: description: Request headers as key/value pairs. type: array items: type: object properties: key: type: string value: type: string required: - key - value additionalProperties: false body: description: Request body. mode none sends no body. type: object properties: mode: type: string enum: - none - json - raw content: type: string contentType: type: string required: - mode additionalProperties: false credentialId: description: HttpCredential id used to authenticate the request. type: string timeoutMs: description: Request timeout in milliseconds. Max 30000 (30s). type: integer exclusiveMinimum: 0 maximum: 30000 maxAttempts: description: Max attempts including the first. Max 5. type: integer exclusiveMinimum: 0 maximum: 5 documentUrlTtlSeconds: description: TTL (seconds, ≤86400) for presigned engagement.documents URLs this node emits. Default 86400. type: integer exclusiveMinimum: 0 maximum: 86400 required: - method - url additionalProperties: false description: Calls an external HTTP endpoint. Emits SUCCESS or FAILED. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: EXIT name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: outcome: type: string nextInitiativeId: description: Chain into another initiative on exit. type: string additionalProperties: false description: Terminal node. required: - id - kind additionalProperties: false description: The nodes. Exactly one ENTRY and at least one EXIT are required to publish. edges: type: array items: type: object properties: from: type: string description: Source node id. to: type: string description: Target node id. sourceHandle: type: string description: The emitted signal that activates this edge (e.g. SENT, REPLIED, YES, case:). A handle may wire to at most one node. metadata: type: object properties: signalCategory: type: string enum: - lifecycle - system signalDescription: type: string additionalProperties: false required: - from - to - sourceHandle additionalProperties: false description: 'A connection: node `from` routes to `to` when it emits `sourceHandle`.' description: The connections between node handles. required: - name - actions - edges additionalProperties: false description: The full journey graph. required: - id - initiativeId - status - version - definition additionalProperties: false '400': description: Validation failed or the request cannot proceed. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '401': description: Missing, malformed, or revoked API key. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '404': description: The resource does not exist in this organization. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '409': description: Conflicts with the current state (duplicates, wrong lifecycle state). content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '422': description: The request is well-formed but semantically invalid. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '429': description: Rate limit exceeded — retry after `Retry-After`. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '500': description: Internal server error. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '503': description: Transient error — retry with a narrower request. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error /api/v1/journeys/{journeyId}/nodes/{nodeId}: delete: operationId: journeys_delete_node summary: Delete node description: Remove one node and every edge connected to it from a draft journey. tags: - Journeys parameters: - name: journeyId in: path required: true schema: $schema: https://json-schema.org/draft/2020-12/schema type: string minLength: 1 description: A draft journey id, or the initiative id (resolves to its current draft). - name: nodeId in: path required: true schema: $schema: https://json-schema.org/draft/2020-12/schema type: string minLength: 1 description: Node id within the journey. responses: '200': description: Success content: application/json: schema: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: id: type: string description: Journey (workflow version) id. initiativeId: type: string description: The initiative this journey belongs to. status: type: string enum: - DRAFT - PUBLISHED - STOPPED description: DRAFT (editable), PUBLISHED (live, frozen), or STOPPED (retired). version: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Version number within the initiative. definition: type: object properties: id: description: Journey id; carried for round-trip ergonomics. Optional on create. type: string name: type: string minLength: 1 description: Journey name. metadata: type: object properties: initiativeType: type: string version: type: integer minimum: -9007199254740991 maximum: 9007199254740991 cancelOnEvents: description: Cancel an in-flight run when any of these events arrive. type: object properties: eventNames: type: array items: type: string required: - eventNames additionalProperties: false additionalProperties: false description: Optional journey-level metadata. actions: minItems: 1 type: array items: oneOf: - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: ENTRY name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: description: type: string triggerType: description: 'How people enter: manual (added by an operator or API call), segment (on entering a segment), or cdp_event (when an event is received). Defaults to manual.' type: string enum: - manual - segment - cdp_event segmentId: description: Segment id — required when triggerType is segment. type: string segmentName: description: Cached segment display name (optional). type: string eventName: description: CDP event name — required when triggerType is cdp_event. type: string maxEnrollments: description: 'Frequency cap: max enrollments per person within enrollmentWindow. Both-or-neither with enrollmentWindow.' type: integer minimum: 1 maximum: 9007199254740991 enrollmentWindow: description: Rolling window for the frequency cap. type: string additionalProperties: false description: Trigger node config. Exactly one ENTRY node per journey. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: SEND_MESSAGE name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: templateId: description: Approved WhatsApp template id. Resolve ids from the catalog. type: string templateName: type: string channel: description: Send channel. Only whatsapp is live today. type: string enum: - whatsapp - sms - email templateBindings: description: Map of template placeholder → variable reference. type: object propertyNames: type: string additionalProperties: type: string channelId: description: Sending WhatsApp channel (WABA) id. Required before publishing. type: string sendImmediately: description: Deprecated business-hours gate; prefer a preceding DELAY. type: boolean additionalProperties: false description: Sends a WhatsApp template. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: CONVERSATION_BLOCK name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: goal: type: string maxTimeout: description: How long to wait for a reply before timing out. type: string mode: type: string enum: - AGENT - ESCALATE outputs: type: array items: type: object properties: id: type: string label: type: string type: type: string enum: - string - number - date - boolean - json description: type: string builtin: type: boolean required: - id - label - type - builtin additionalProperties: false additionalProperties: false description: Legacy combined wait + AI conversation block. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: WAIT_FOR_REPLY name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: maxTimeout: description: How long to wait for the first reply before timing out. type: string additionalProperties: false description: Waits for the person to reply. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: MANAGE_CONVERSATION name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: mode: description: AGENT (AI-led) or ESCALATE (human handoff). Defaults to AGENT. type: string enum: - AGENT - ESCALATE inactivityTimeout: description: Rolling idle window (e.g. '12h'), resets on each inbound message. After this much silence the node routes INACTIVE (extracts, does not close). Range 1h–24h; requires the journey-inactivity-timeout flag. type: string additionalProperties: false description: Runs the AI-led conversation. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: DISPATCH_EVENT name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: eventName: type: string minLength: 1 description: CDP event name to record. Must match the CDP name pattern. properties: description: 'Literal string values, or { var: path } bindings resolved to typed values at dispatch time.' type: object propertyNames: type: string additionalProperties: anyOf: - type: string - type: object properties: var: type: string required: - var additionalProperties: false description: type: string required: - eventName additionalProperties: false description: Records a CDP event for the person. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: DELAY name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: mode: description: How the wait is measured. Defaults to duration. type: string enum: - duration - until_date - until_weekday duration: description: For mode duration. type: string targetAt: description: ISO 8601 instant, for mode until_date. type: string weekdays: description: ISO weekdays 1=Mon..7=Sun, for mode until_weekday. type: array items: type: integer minimum: 1 maximum: 7 windowStartMinutes: type: integer minimum: 0 maximum: 1439 windowEndMinutes: type: integer minimum: 0 maximum: 1439 timezone: description: IANA timezone. Load-bearing for until_weekday. type: string description: type: string additionalProperties: false description: Pauses the run. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: DECISION name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: logic: type: string enum: - AND - OR conditions: type: array items: oneOf: - type: object properties: kind: type: string const: value selectionPath: type: string description: Dot-path into the run, e.g. workflowState.totalPrice. operator: type: string enum: - eq - neq - gt - lt - contains - isSet value: type: string required: - kind - selectionPath - operator - value additionalProperties: false - type: object properties: kind: type: string const: event eventName: type: string subjectSelectionPath: type: string occurred: type: boolean required: - kind - eventName - subjectSelectionPath - occurred additionalProperties: false - type: object properties: kind: type: string const: cdp_predicate term: type: object propertyNames: type: string additionalProperties: {} description: A single live person/computed predicate term. See journeys_authoring_catalog for its shape. required: - kind - term additionalProperties: false - type: object properties: kind: type: string const: cdp_object objectType: type: string matchAttr: type: string matchSelectionPath: type: string exists: type: boolean required: - kind - objectType - matchAttr - matchSelectionPath - exists additionalProperties: false description: One decision condition. description: type: string required: - logic - conditions additionalProperties: false description: Two-way branch. Emits YES / NO. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: CASE name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: selectionPath: type: string description: Person attribute (attributes.*) or extracted field (engagement.extracted.*) to switch on. branches: type: array items: type: object properties: id: type: string description: Stable branch id; edge handle is case:. value: type: string description: Value matched. Unique within the node. label: type: string required: - id - value additionalProperties: false description: Up to 10 branches. A case:default handle is always required. description: type: string required: - selectionPath - branches additionalProperties: false description: N-way switch on a person attribute. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: HTTP_REQUEST name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: method: type: string enum: - GET - POST - PUT - PATCH - DELETE description: HTTP method. url: type: string minLength: 1 description: Target URL. Supports {{variable}} placeholders. headers: description: Request headers as key/value pairs. type: array items: type: object properties: key: type: string value: type: string required: - key - value additionalProperties: false body: description: Request body. mode none sends no body. type: object properties: mode: type: string enum: - none - json - raw content: type: string contentType: type: string required: - mode additionalProperties: false credentialId: description: HttpCredential id used to authenticate the request. type: string timeoutMs: description: Request timeout in milliseconds. Max 30000 (30s). type: integer exclusiveMinimum: 0 maximum: 30000 maxAttempts: description: Max attempts including the first. Max 5. type: integer exclusiveMinimum: 0 maximum: 5 documentUrlTtlSeconds: description: TTL (seconds, ≤86400) for presigned engagement.documents URLs this node emits. Default 86400. type: integer exclusiveMinimum: 0 maximum: 86400 required: - method - url additionalProperties: false description: Calls an external HTTP endpoint. Emits SUCCESS or FAILED. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: EXIT name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: outcome: type: string nextInitiativeId: description: Chain into another initiative on exit. type: string additionalProperties: false description: Terminal node. required: - id - kind additionalProperties: false description: The nodes. Exactly one ENTRY and at least one EXIT are required to publish. edges: type: array items: type: object properties: from: type: string description: Source node id. to: type: string description: Target node id. sourceHandle: type: string description: The emitted signal that activates this edge (e.g. SENT, REPLIED, YES, case:). A handle may wire to at most one node. metadata: type: object properties: signalCategory: type: string enum: - lifecycle - system signalDescription: type: string additionalProperties: false required: - from - to - sourceHandle additionalProperties: false description: 'A connection: node `from` routes to `to` when it emits `sourceHandle`.' description: The connections between node handles. required: - name - actions - edges additionalProperties: false description: The full journey graph. required: - id - initiativeId - status - version - definition additionalProperties: false '400': description: Validation failed or the request cannot proceed. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '401': description: Missing, malformed, or revoked API key. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '404': description: The resource does not exist in this organization. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '409': description: Conflicts with the current state (duplicates, wrong lifecycle state). content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '422': description: The request is well-formed but semantically invalid. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '429': description: Rate limit exceeded — retry after `Retry-After`. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '500': description: Internal server error. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '503': description: Transient error — retry with a narrower request. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error patch: operationId: journeys_update_node summary: Update node description: Update one node's name, position, and/or config (inputs shallow-merge). Use journeys_authoring_catalog for a node kind's input fields. tags: - Journeys requestBody: required: true content: application/json: schema: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: name: description: New node label. type: string minLength: 1 position: type: object properties: x: type: number y: type: number required: - x - y inputs: description: Config fields to merge into the node's inputs. type: object propertyNames: type: string additionalProperties: {} parameters: - name: journeyId in: path required: true schema: $schema: https://json-schema.org/draft/2020-12/schema type: string minLength: 1 description: A draft journey id, or the initiative id (resolves to its current draft). - name: nodeId in: path required: true schema: $schema: https://json-schema.org/draft/2020-12/schema type: string minLength: 1 description: Node id within the journey. responses: '200': description: Success content: application/json: schema: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: id: type: string description: Journey (workflow version) id. initiativeId: type: string description: The initiative this journey belongs to. status: type: string enum: - DRAFT - PUBLISHED - STOPPED description: DRAFT (editable), PUBLISHED (live, frozen), or STOPPED (retired). version: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Version number within the initiative. definition: type: object properties: id: description: Journey id; carried for round-trip ergonomics. Optional on create. type: string name: type: string minLength: 1 description: Journey name. metadata: type: object properties: initiativeType: type: string version: type: integer minimum: -9007199254740991 maximum: 9007199254740991 cancelOnEvents: description: Cancel an in-flight run when any of these events arrive. type: object properties: eventNames: type: array items: type: string required: - eventNames additionalProperties: false additionalProperties: false description: Optional journey-level metadata. actions: minItems: 1 type: array items: oneOf: - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: ENTRY name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: description: type: string triggerType: description: 'How people enter: manual (added by an operator or API call), segment (on entering a segment), or cdp_event (when an event is received). Defaults to manual.' type: string enum: - manual - segment - cdp_event segmentId: description: Segment id — required when triggerType is segment. type: string segmentName: description: Cached segment display name (optional). type: string eventName: description: CDP event name — required when triggerType is cdp_event. type: string maxEnrollments: description: 'Frequency cap: max enrollments per person within enrollmentWindow. Both-or-neither with enrollmentWindow.' type: integer minimum: 1 maximum: 9007199254740991 enrollmentWindow: description: Rolling window for the frequency cap. type: string additionalProperties: false description: Trigger node config. Exactly one ENTRY node per journey. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: SEND_MESSAGE name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: templateId: description: Approved WhatsApp template id. Resolve ids from the catalog. type: string templateName: type: string channel: description: Send channel. Only whatsapp is live today. type: string enum: - whatsapp - sms - email templateBindings: description: Map of template placeholder → variable reference. type: object propertyNames: type: string additionalProperties: type: string channelId: description: Sending WhatsApp channel (WABA) id. Required before publishing. type: string sendImmediately: description: Deprecated business-hours gate; prefer a preceding DELAY. type: boolean additionalProperties: false description: Sends a WhatsApp template. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: CONVERSATION_BLOCK name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: goal: type: string maxTimeout: description: How long to wait for a reply before timing out. type: string mode: type: string enum: - AGENT - ESCALATE outputs: type: array items: type: object properties: id: type: string label: type: string type: type: string enum: - string - number - date - boolean - json description: type: string builtin: type: boolean required: - id - label - type - builtin additionalProperties: false additionalProperties: false description: Legacy combined wait + AI conversation block. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: WAIT_FOR_REPLY name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: maxTimeout: description: How long to wait for the first reply before timing out. type: string additionalProperties: false description: Waits for the person to reply. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: MANAGE_CONVERSATION name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: mode: description: AGENT (AI-led) or ESCALATE (human handoff). Defaults to AGENT. type: string enum: - AGENT - ESCALATE inactivityTimeout: description: Rolling idle window (e.g. '12h'), resets on each inbound message. After this much silence the node routes INACTIVE (extracts, does not close). Range 1h–24h; requires the journey-inactivity-timeout flag. type: string additionalProperties: false description: Runs the AI-led conversation. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: DISPATCH_EVENT name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: eventName: type: string minLength: 1 description: CDP event name to record. Must match the CDP name pattern. properties: description: 'Literal string values, or { var: path } bindings resolved to typed values at dispatch time.' type: object propertyNames: type: string additionalProperties: anyOf: - type: string - type: object properties: var: type: string required: - var additionalProperties: false description: type: string required: - eventName additionalProperties: false description: Records a CDP event for the person. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: DELAY name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: mode: description: How the wait is measured. Defaults to duration. type: string enum: - duration - until_date - until_weekday duration: description: For mode duration. type: string targetAt: description: ISO 8601 instant, for mode until_date. type: string weekdays: description: ISO weekdays 1=Mon..7=Sun, for mode until_weekday. type: array items: type: integer minimum: 1 maximum: 7 windowStartMinutes: type: integer minimum: 0 maximum: 1439 windowEndMinutes: type: integer minimum: 0 maximum: 1439 timezone: description: IANA timezone. Load-bearing for until_weekday. type: string description: type: string additionalProperties: false description: Pauses the run. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: DECISION name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: logic: type: string enum: - AND - OR conditions: type: array items: oneOf: - type: object properties: kind: type: string const: value selectionPath: type: string description: Dot-path into the run, e.g. workflowState.totalPrice. operator: type: string enum: - eq - neq - gt - lt - contains - isSet value: type: string required: - kind - selectionPath - operator - value additionalProperties: false - type: object properties: kind: type: string const: event eventName: type: string subjectSelectionPath: type: string occurred: type: boolean required: - kind - eventName - subjectSelectionPath - occurred additionalProperties: false - type: object properties: kind: type: string const: cdp_predicate term: type: object propertyNames: type: string additionalProperties: {} description: A single live person/computed predicate term. See journeys_authoring_catalog for its shape. required: - kind - term additionalProperties: false - type: object properties: kind: type: string const: cdp_object objectType: type: string matchAttr: type: string matchSelectionPath: type: string exists: type: boolean required: - kind - objectType - matchAttr - matchSelectionPath - exists additionalProperties: false description: One decision condition. description: type: string required: - logic - conditions additionalProperties: false description: Two-way branch. Emits YES / NO. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: CASE name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: selectionPath: type: string description: Person attribute (attributes.*) or extracted field (engagement.extracted.*) to switch on. branches: type: array items: type: object properties: id: type: string description: Stable branch id; edge handle is case:. value: type: string description: Value matched. Unique within the node. label: type: string required: - id - value additionalProperties: false description: Up to 10 branches. A case:default handle is always required. description: type: string required: - selectionPath - branches additionalProperties: false description: N-way switch on a person attribute. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: HTTP_REQUEST name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: method: type: string enum: - GET - POST - PUT - PATCH - DELETE description: HTTP method. url: type: string minLength: 1 description: Target URL. Supports {{variable}} placeholders. headers: description: Request headers as key/value pairs. type: array items: type: object properties: key: type: string value: type: string required: - key - value additionalProperties: false body: description: Request body. mode none sends no body. type: object properties: mode: type: string enum: - none - json - raw content: type: string contentType: type: string required: - mode additionalProperties: false credentialId: description: HttpCredential id used to authenticate the request. type: string timeoutMs: description: Request timeout in milliseconds. Max 30000 (30s). type: integer exclusiveMinimum: 0 maximum: 30000 maxAttempts: description: Max attempts including the first. Max 5. type: integer exclusiveMinimum: 0 maximum: 5 documentUrlTtlSeconds: description: TTL (seconds, ≤86400) for presigned engagement.documents URLs this node emits. Default 86400. type: integer exclusiveMinimum: 0 maximum: 86400 required: - method - url additionalProperties: false description: Calls an external HTTP endpoint. Emits SUCCESS or FAILED. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: EXIT name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: outcome: type: string nextInitiativeId: description: Chain into another initiative on exit. type: string additionalProperties: false description: Terminal node. required: - id - kind additionalProperties: false description: The nodes. Exactly one ENTRY and at least one EXIT are required to publish. edges: type: array items: type: object properties: from: type: string description: Source node id. to: type: string description: Target node id. sourceHandle: type: string description: The emitted signal that activates this edge (e.g. SENT, REPLIED, YES, case:). A handle may wire to at most one node. metadata: type: object properties: signalCategory: type: string enum: - lifecycle - system signalDescription: type: string additionalProperties: false required: - from - to - sourceHandle additionalProperties: false description: 'A connection: node `from` routes to `to` when it emits `sourceHandle`.' description: The connections between node handles. required: - name - actions - edges additionalProperties: false description: The full journey graph. required: - id - initiativeId - status - version - definition additionalProperties: false '400': description: Validation failed or the request cannot proceed. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '401': description: Missing, malformed, or revoked API key. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '404': description: The resource does not exist in this organization. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '409': description: Conflicts with the current state (duplicates, wrong lifecycle state). content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '422': description: The request is well-formed but semantically invalid. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '429': description: Rate limit exceeded — retry after `Retry-After`. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '500': description: Internal server error. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '503': description: Transient error — retry with a narrower request. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error /api/v1/journeys/{journeyId}/publish: post: operationId: journeys_publish summary: Publish journey description: 'Publish a draft journey so it goes live and starts enrolling people (this begins real outreach). Validates first and requires confirm: true. The trigger is taken from the ENTRY node. Any previously live version is retired.' tags: - Journeys requestBody: required: true content: application/json: schema: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: confirm: default: false description: Must be true to publish. Publishing starts real customer outreach. type: boolean includeExisting: default: false description: 'For a segment trigger: also enroll people already in the segment (a one-time backfill).' type: boolean parameters: - name: journeyId in: path required: true schema: $schema: https://json-schema.org/draft/2020-12/schema type: string minLength: 1 description: A draft journey id, or the initiative id (resolves to its current draft). responses: '201': description: Success content: application/json: schema: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: id: type: string description: Journey (workflow version) id. initiativeId: type: string description: The initiative this journey belongs to. status: type: string enum: - DRAFT - PUBLISHED - STOPPED description: DRAFT (editable), PUBLISHED (live, frozen), or STOPPED (retired). version: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Version number within the initiative. definition: type: object properties: id: description: Journey id; carried for round-trip ergonomics. Optional on create. type: string name: type: string minLength: 1 description: Journey name. metadata: type: object properties: initiativeType: type: string version: type: integer minimum: -9007199254740991 maximum: 9007199254740991 cancelOnEvents: description: Cancel an in-flight run when any of these events arrive. type: object properties: eventNames: type: array items: type: string required: - eventNames additionalProperties: false additionalProperties: false description: Optional journey-level metadata. actions: minItems: 1 type: array items: oneOf: - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: ENTRY name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: description: type: string triggerType: description: 'How people enter: manual (added by an operator or API call), segment (on entering a segment), or cdp_event (when an event is received). Defaults to manual.' type: string enum: - manual - segment - cdp_event segmentId: description: Segment id — required when triggerType is segment. type: string segmentName: description: Cached segment display name (optional). type: string eventName: description: CDP event name — required when triggerType is cdp_event. type: string maxEnrollments: description: 'Frequency cap: max enrollments per person within enrollmentWindow. Both-or-neither with enrollmentWindow.' type: integer minimum: 1 maximum: 9007199254740991 enrollmentWindow: description: Rolling window for the frequency cap. type: string additionalProperties: false description: Trigger node config. Exactly one ENTRY node per journey. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: SEND_MESSAGE name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: templateId: description: Approved WhatsApp template id. Resolve ids from the catalog. type: string templateName: type: string channel: description: Send channel. Only whatsapp is live today. type: string enum: - whatsapp - sms - email templateBindings: description: Map of template placeholder → variable reference. type: object propertyNames: type: string additionalProperties: type: string channelId: description: Sending WhatsApp channel (WABA) id. Required before publishing. type: string sendImmediately: description: Deprecated business-hours gate; prefer a preceding DELAY. type: boolean additionalProperties: false description: Sends a WhatsApp template. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: CONVERSATION_BLOCK name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: goal: type: string maxTimeout: description: How long to wait for a reply before timing out. type: string mode: type: string enum: - AGENT - ESCALATE outputs: type: array items: type: object properties: id: type: string label: type: string type: type: string enum: - string - number - date - boolean - json description: type: string builtin: type: boolean required: - id - label - type - builtin additionalProperties: false additionalProperties: false description: Legacy combined wait + AI conversation block. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: WAIT_FOR_REPLY name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: maxTimeout: description: How long to wait for the first reply before timing out. type: string additionalProperties: false description: Waits for the person to reply. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: MANAGE_CONVERSATION name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: mode: description: AGENT (AI-led) or ESCALATE (human handoff). Defaults to AGENT. type: string enum: - AGENT - ESCALATE inactivityTimeout: description: Rolling idle window (e.g. '12h'), resets on each inbound message. After this much silence the node routes INACTIVE (extracts, does not close). Range 1h–24h; requires the journey-inactivity-timeout flag. type: string additionalProperties: false description: Runs the AI-led conversation. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: DISPATCH_EVENT name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: eventName: type: string minLength: 1 description: CDP event name to record. Must match the CDP name pattern. properties: description: 'Literal string values, or { var: path } bindings resolved to typed values at dispatch time.' type: object propertyNames: type: string additionalProperties: anyOf: - type: string - type: object properties: var: type: string required: - var additionalProperties: false description: type: string required: - eventName additionalProperties: false description: Records a CDP event for the person. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: DELAY name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: mode: description: How the wait is measured. Defaults to duration. type: string enum: - duration - until_date - until_weekday duration: description: For mode duration. type: string targetAt: description: ISO 8601 instant, for mode until_date. type: string weekdays: description: ISO weekdays 1=Mon..7=Sun, for mode until_weekday. type: array items: type: integer minimum: 1 maximum: 7 windowStartMinutes: type: integer minimum: 0 maximum: 1439 windowEndMinutes: type: integer minimum: 0 maximum: 1439 timezone: description: IANA timezone. Load-bearing for until_weekday. type: string description: type: string additionalProperties: false description: Pauses the run. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: DECISION name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: logic: type: string enum: - AND - OR conditions: type: array items: oneOf: - type: object properties: kind: type: string const: value selectionPath: type: string description: Dot-path into the run, e.g. workflowState.totalPrice. operator: type: string enum: - eq - neq - gt - lt - contains - isSet value: type: string required: - kind - selectionPath - operator - value additionalProperties: false - type: object properties: kind: type: string const: event eventName: type: string subjectSelectionPath: type: string occurred: type: boolean required: - kind - eventName - subjectSelectionPath - occurred additionalProperties: false - type: object properties: kind: type: string const: cdp_predicate term: type: object propertyNames: type: string additionalProperties: {} description: A single live person/computed predicate term. See journeys_authoring_catalog for its shape. required: - kind - term additionalProperties: false - type: object properties: kind: type: string const: cdp_object objectType: type: string matchAttr: type: string matchSelectionPath: type: string exists: type: boolean required: - kind - objectType - matchAttr - matchSelectionPath - exists additionalProperties: false description: One decision condition. description: type: string required: - logic - conditions additionalProperties: false description: Two-way branch. Emits YES / NO. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: CASE name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: selectionPath: type: string description: Person attribute (attributes.*) or extracted field (engagement.extracted.*) to switch on. branches: type: array items: type: object properties: id: type: string description: Stable branch id; edge handle is case:. value: type: string description: Value matched. Unique within the node. label: type: string required: - id - value additionalProperties: false description: Up to 10 branches. A case:default handle is always required. description: type: string required: - selectionPath - branches additionalProperties: false description: N-way switch on a person attribute. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: HTTP_REQUEST name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: method: type: string enum: - GET - POST - PUT - PATCH - DELETE description: HTTP method. url: type: string minLength: 1 description: Target URL. Supports {{variable}} placeholders. headers: description: Request headers as key/value pairs. type: array items: type: object properties: key: type: string value: type: string required: - key - value additionalProperties: false body: description: Request body. mode none sends no body. type: object properties: mode: type: string enum: - none - json - raw content: type: string contentType: type: string required: - mode additionalProperties: false credentialId: description: HttpCredential id used to authenticate the request. type: string timeoutMs: description: Request timeout in milliseconds. Max 30000 (30s). type: integer exclusiveMinimum: 0 maximum: 30000 maxAttempts: description: Max attempts including the first. Max 5. type: integer exclusiveMinimum: 0 maximum: 5 documentUrlTtlSeconds: description: TTL (seconds, ≤86400) for presigned engagement.documents URLs this node emits. Default 86400. type: integer exclusiveMinimum: 0 maximum: 86400 required: - method - url additionalProperties: false description: Calls an external HTTP endpoint. Emits SUCCESS or FAILED. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: EXIT name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: outcome: type: string nextInitiativeId: description: Chain into another initiative on exit. type: string additionalProperties: false description: Terminal node. required: - id - kind additionalProperties: false description: The nodes. Exactly one ENTRY and at least one EXIT are required to publish. edges: type: array items: type: object properties: from: type: string description: Source node id. to: type: string description: Target node id. sourceHandle: type: string description: The emitted signal that activates this edge (e.g. SENT, REPLIED, YES, case:). A handle may wire to at most one node. metadata: type: object properties: signalCategory: type: string enum: - lifecycle - system signalDescription: type: string additionalProperties: false required: - from - to - sourceHandle additionalProperties: false description: 'A connection: node `from` routes to `to` when it emits `sourceHandle`.' description: The connections between node handles. required: - name - actions - edges additionalProperties: false description: The full journey graph. required: - id - initiativeId - status - version - definition additionalProperties: false '400': description: Validation failed or the request cannot proceed. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '401': description: Missing, malformed, or revoked API key. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '404': description: The resource does not exist in this organization. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '409': description: Conflicts with the current state (duplicates, wrong lifecycle state). content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '422': description: The request is well-formed but semantically invalid. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '429': description: Rate limit exceeded — retry after `Retry-After`. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '500': description: Internal server error. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '503': description: Transient error — retry with a narrower request. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error /api/v1/journeys/{journeyId}/trigger: patch: operationId: journeys_set_trigger summary: Set trigger description: 'Configure how people enter the journey by updating its ENTRY node: manual, segment (needs segmentId), or cdp_event (needs eventName), with an optional frequency cap.' tags: - Journeys requestBody: required: true content: application/json: schema: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: triggerType: type: string enum: - manual - segment - cdp_event description: How people enter the journey. segmentId: description: Required for segment triggers. type: string segmentName: type: string eventName: description: Required for cdp_event triggers. type: string maxEnrollments: description: Frequency cap; both-or-neither with enrollmentWindow. type: integer minimum: 1 maximum: 9007199254740991 enrollmentWindow: description: Frequency-cap window, e.g. '7d'. type: string required: - triggerType parameters: - name: journeyId in: path required: true schema: $schema: https://json-schema.org/draft/2020-12/schema type: string minLength: 1 description: A draft journey id, or the initiative id (resolves to its current draft). responses: '200': description: Success content: application/json: schema: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: id: type: string description: Journey (workflow version) id. initiativeId: type: string description: The initiative this journey belongs to. status: type: string enum: - DRAFT - PUBLISHED - STOPPED description: DRAFT (editable), PUBLISHED (live, frozen), or STOPPED (retired). version: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Version number within the initiative. definition: type: object properties: id: description: Journey id; carried for round-trip ergonomics. Optional on create. type: string name: type: string minLength: 1 description: Journey name. metadata: type: object properties: initiativeType: type: string version: type: integer minimum: -9007199254740991 maximum: 9007199254740991 cancelOnEvents: description: Cancel an in-flight run when any of these events arrive. type: object properties: eventNames: type: array items: type: string required: - eventNames additionalProperties: false additionalProperties: false description: Optional journey-level metadata. actions: minItems: 1 type: array items: oneOf: - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: ENTRY name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: description: type: string triggerType: description: 'How people enter: manual (added by an operator or API call), segment (on entering a segment), or cdp_event (when an event is received). Defaults to manual.' type: string enum: - manual - segment - cdp_event segmentId: description: Segment id — required when triggerType is segment. type: string segmentName: description: Cached segment display name (optional). type: string eventName: description: CDP event name — required when triggerType is cdp_event. type: string maxEnrollments: description: 'Frequency cap: max enrollments per person within enrollmentWindow. Both-or-neither with enrollmentWindow.' type: integer minimum: 1 maximum: 9007199254740991 enrollmentWindow: description: Rolling window for the frequency cap. type: string additionalProperties: false description: Trigger node config. Exactly one ENTRY node per journey. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: SEND_MESSAGE name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: templateId: description: Approved WhatsApp template id. Resolve ids from the catalog. type: string templateName: type: string channel: description: Send channel. Only whatsapp is live today. type: string enum: - whatsapp - sms - email templateBindings: description: Map of template placeholder → variable reference. type: object propertyNames: type: string additionalProperties: type: string channelId: description: Sending WhatsApp channel (WABA) id. Required before publishing. type: string sendImmediately: description: Deprecated business-hours gate; prefer a preceding DELAY. type: boolean additionalProperties: false description: Sends a WhatsApp template. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: CONVERSATION_BLOCK name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: goal: type: string maxTimeout: description: How long to wait for a reply before timing out. type: string mode: type: string enum: - AGENT - ESCALATE outputs: type: array items: type: object properties: id: type: string label: type: string type: type: string enum: - string - number - date - boolean - json description: type: string builtin: type: boolean required: - id - label - type - builtin additionalProperties: false additionalProperties: false description: Legacy combined wait + AI conversation block. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: WAIT_FOR_REPLY name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: maxTimeout: description: How long to wait for the first reply before timing out. type: string additionalProperties: false description: Waits for the person to reply. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: MANAGE_CONVERSATION name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: mode: description: AGENT (AI-led) or ESCALATE (human handoff). Defaults to AGENT. type: string enum: - AGENT - ESCALATE inactivityTimeout: description: Rolling idle window (e.g. '12h'), resets on each inbound message. After this much silence the node routes INACTIVE (extracts, does not close). Range 1h–24h; requires the journey-inactivity-timeout flag. type: string additionalProperties: false description: Runs the AI-led conversation. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: DISPATCH_EVENT name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: eventName: type: string minLength: 1 description: CDP event name to record. Must match the CDP name pattern. properties: description: 'Literal string values, or { var: path } bindings resolved to typed values at dispatch time.' type: object propertyNames: type: string additionalProperties: anyOf: - type: string - type: object properties: var: type: string required: - var additionalProperties: false description: type: string required: - eventName additionalProperties: false description: Records a CDP event for the person. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: DELAY name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: mode: description: How the wait is measured. Defaults to duration. type: string enum: - duration - until_date - until_weekday duration: description: For mode duration. type: string targetAt: description: ISO 8601 instant, for mode until_date. type: string weekdays: description: ISO weekdays 1=Mon..7=Sun, for mode until_weekday. type: array items: type: integer minimum: 1 maximum: 7 windowStartMinutes: type: integer minimum: 0 maximum: 1439 windowEndMinutes: type: integer minimum: 0 maximum: 1439 timezone: description: IANA timezone. Load-bearing for until_weekday. type: string description: type: string additionalProperties: false description: Pauses the run. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: DECISION name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: logic: type: string enum: - AND - OR conditions: type: array items: oneOf: - type: object properties: kind: type: string const: value selectionPath: type: string description: Dot-path into the run, e.g. workflowState.totalPrice. operator: type: string enum: - eq - neq - gt - lt - contains - isSet value: type: string required: - kind - selectionPath - operator - value additionalProperties: false - type: object properties: kind: type: string const: event eventName: type: string subjectSelectionPath: type: string occurred: type: boolean required: - kind - eventName - subjectSelectionPath - occurred additionalProperties: false - type: object properties: kind: type: string const: cdp_predicate term: type: object propertyNames: type: string additionalProperties: {} description: A single live person/computed predicate term. See journeys_authoring_catalog for its shape. required: - kind - term additionalProperties: false - type: object properties: kind: type: string const: cdp_object objectType: type: string matchAttr: type: string matchSelectionPath: type: string exists: type: boolean required: - kind - objectType - matchAttr - matchSelectionPath - exists additionalProperties: false description: One decision condition. description: type: string required: - logic - conditions additionalProperties: false description: Two-way branch. Emits YES / NO. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: CASE name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: selectionPath: type: string description: Person attribute (attributes.*) or extracted field (engagement.extracted.*) to switch on. branches: type: array items: type: object properties: id: type: string description: Stable branch id; edge handle is case:. value: type: string description: Value matched. Unique within the node. label: type: string required: - id - value additionalProperties: false description: Up to 10 branches. A case:default handle is always required. description: type: string required: - selectionPath - branches additionalProperties: false description: N-way switch on a person attribute. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: HTTP_REQUEST name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: method: type: string enum: - GET - POST - PUT - PATCH - DELETE description: HTTP method. url: type: string minLength: 1 description: Target URL. Supports {{variable}} placeholders. headers: description: Request headers as key/value pairs. type: array items: type: object properties: key: type: string value: type: string required: - key - value additionalProperties: false body: description: Request body. mode none sends no body. type: object properties: mode: type: string enum: - none - json - raw content: type: string contentType: type: string required: - mode additionalProperties: false credentialId: description: HttpCredential id used to authenticate the request. type: string timeoutMs: description: Request timeout in milliseconds. Max 30000 (30s). type: integer exclusiveMinimum: 0 maximum: 30000 maxAttempts: description: Max attempts including the first. Max 5. type: integer exclusiveMinimum: 0 maximum: 5 documentUrlTtlSeconds: description: TTL (seconds, ≤86400) for presigned engagement.documents URLs this node emits. Default 86400. type: integer exclusiveMinimum: 0 maximum: 86400 required: - method - url additionalProperties: false description: Calls an external HTTP endpoint. Emits SUCCESS or FAILED. required: - id - kind additionalProperties: false - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: EXIT name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: outcome: type: string nextInitiativeId: description: Chain into another initiative on exit. type: string additionalProperties: false description: Terminal node. required: - id - kind additionalProperties: false description: The nodes. Exactly one ENTRY and at least one EXIT are required to publish. edges: type: array items: type: object properties: from: type: string description: Source node id. to: type: string description: Target node id. sourceHandle: type: string description: The emitted signal that activates this edge (e.g. SENT, REPLIED, YES, case:). A handle may wire to at most one node. metadata: type: object properties: signalCategory: type: string enum: - lifecycle - system signalDescription: type: string additionalProperties: false required: - from - to - sourceHandle additionalProperties: false description: 'A connection: node `from` routes to `to` when it emits `sourceHandle`.' description: The connections between node handles. required: - name - actions - edges additionalProperties: false description: The full journey graph. required: - id - initiativeId - status - version - definition additionalProperties: false '400': description: Validation failed or the request cannot proceed. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '401': description: Missing, malformed, or revoked API key. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '404': description: The resource does not exist in this organization. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '409': description: Conflicts with the current state (duplicates, wrong lifecycle state). content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '422': description: The request is well-formed but semantically invalid. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '429': description: Rate limit exceeded — retry after `Retry-After`. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '500': description: Internal server error. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '503': description: Transient error — retry with a narrower request. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error /api/v1/journeys/catalog: get: operationId: journeys_authoring_catalog summary: Node catalog description: Describes every journey node kind — its inputs, its output handles (the signals it can emit), and the rules for connecting nodes. Read this before building or editing a journey. tags: - Journeys responses: '200': description: Success content: application/json: schema: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: kinds: type: array items: type: object properties: kind: type: string group: type: string enum: - trigger - action - logic - terminal description: type: string outputHandles: type: array items: type: string dynamicHandles: type: string inputs: type: array items: type: object properties: name: type: string type: type: string required: type: boolean description: type: string required: - name - type - required - description additionalProperties: false required: - kind - group - description - outputHandles - inputs additionalProperties: false graphRules: type: array items: type: string required: - kinds - graphRules additionalProperties: false '400': description: Validation failed or the request cannot proceed. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '401': description: Missing, malformed, or revoked API key. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '404': description: The resource does not exist in this organization. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '409': description: Conflicts with the current state (duplicates, wrong lifecycle state). content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '422': description: The request is well-formed but semantically invalid. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '429': description: Rate limit exceeded — retry after `Retry-After`. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '500': description: Internal server error. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '503': description: Transient error — retry with a narrower request. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error /api/v1/journeys/condition-catalog: get: operationId: journeys_condition_catalog summary: Condition catalog description: 'List the person attributes and computed attributes available for DECISION and CASE CONDITIONS, plus the custom object types. Attribute tokens are ready to use as condition selection paths (e.g. attributes.plan, computed.ltv). NOTE: these `attributes.*` tokens are ONLY for DECISION/CASE conditions — SEND_MESSAGE template bindings use a different syntax (`person.`); call journeys_message_variables for those.' tags: - Journeys responses: '200': description: Success content: application/json: schema: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: person: type: array items: type: object properties: attr: type: string label: type: string type: type: string required: - attr - label - type additionalProperties: false computed: type: array items: type: object properties: attr: type: string label: type: string type: type: string required: - attr - label - type additionalProperties: false objectTypes: type: array items: type: object properties: name: type: string displayName: anyOf: - type: string - type: 'null' required: - name - displayName additionalProperties: false required: - person - computed - objectTypes additionalProperties: false '400': description: Validation failed or the request cannot proceed. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '401': description: Missing, malformed, or revoked API key. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '404': description: The resource does not exist in this organization. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '409': description: Conflicts with the current state (duplicates, wrong lifecycle state). content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '422': description: The request is well-formed but semantically invalid. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '429': description: Rate limit exceeded — retry after `Retry-After`. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '500': description: Internal server error. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '503': description: Transient error — retry with a narrower request. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error /api/v1/journeys/event-catalog: get: operationId: journeys_event_catalog summary: Event catalog description: List the CDP event names seen for your organization. Use these for a cdp_event trigger, a DISPATCH_EVENT node, or an event-based DECISION condition. tags: - Journeys responses: '200': description: Success content: application/json: schema: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: data: type: array items: type: object properties: name: type: string description: anyOf: - type: string - type: 'null' required: - name - description additionalProperties: false required: - data additionalProperties: false '400': description: Validation failed or the request cannot proceed. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '401': description: Missing, malformed, or revoked API key. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '404': description: The resource does not exist in this organization. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '409': description: Conflicts with the current state (duplicates, wrong lifecycle state). content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '422': description: The request is well-formed but semantically invalid. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '429': description: Rate limit exceeded — retry after `Retry-After`. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '500': description: Internal server error. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '503': description: Transient error — retry with a narrower request. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error /api/v1/journeys/message-channels: get: operationId: journeys_message_channels summary: List message channels description: List the WhatsApp channels a SEND_MESSAGE node can send from. Use a channel id as channelId on the node and to look up its approved templates. tags: - Journeys responses: '200': description: Success content: application/json: schema: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: data: type: array items: type: object properties: id: type: string name: type: string phoneNumber: type: string isPrimary: type: boolean required: - id - name - phoneNumber - isPrimary additionalProperties: false required: - data additionalProperties: false '400': description: Validation failed or the request cannot proceed. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '401': description: Missing, malformed, or revoked API key. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '404': description: The resource does not exist in this organization. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '409': description: Conflicts with the current state (duplicates, wrong lifecycle state). content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '422': description: The request is well-formed but semantically invalid. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '429': description: Rate limit exceeded — retry after `Retry-After`. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '500': description: Internal server error. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '503': description: Transient error — retry with a narrower request. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error /api/v1/journeys/message-templates: get: operationId: journeys_message_templates summary: List message templates description: List the approved WhatsApp templates a SEND_MESSAGE node can use from a given channel. A template belongs to one channel account, so pass the same channelId you pin on the node. tags: - Journeys parameters: - name: channelId in: query required: true schema: $schema: https://json-schema.org/draft/2020-12/schema type: string minLength: 1 description: Channel id from journeys_message_channels. responses: '200': description: Success content: application/json: schema: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: data: type: array items: type: object properties: id: type: string friendlyName: type: string category: type: string contentType: type: string required: - id - friendlyName - category - contentType additionalProperties: false required: - data additionalProperties: false '400': description: Validation failed or the request cannot proceed. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '401': description: Missing, malformed, or revoked API key. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '404': description: The resource does not exist in this organization. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '409': description: Conflicts with the current state (duplicates, wrong lifecycle state). content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '422': description: The request is well-formed but semantically invalid. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '429': description: Rate limit exceeded — retry after `Retry-After`. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '500': description: Internal server error. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '503': description: Transient error — retry with a narrower request. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error /api/v1/journeys/validate: post: operationId: journeys_validate summary: Validate journey description: Dry-run the publish checks against a journey graph without saving. Returns whether it is valid and the list of issues (errors block publishing; warnings are advisory). Use it to iterate a draft to valid before publishing in the app. tags: - Journeys requestBody: required: true content: application/json: schema: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: definition: type: object properties: id: description: Journey id; carried for round-trip ergonomics. Optional on create. type: string name: type: string minLength: 1 description: Journey name. metadata: type: object properties: initiativeType: type: string version: type: integer minimum: -9007199254740991 maximum: 9007199254740991 cancelOnEvents: description: Cancel an in-flight run when any of these events arrive. type: object properties: eventNames: type: array items: type: string required: - eventNames description: Optional journey-level metadata. actions: minItems: 1 type: array items: oneOf: - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: ENTRY name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: description: type: string triggerType: description: 'How people enter: manual (added by an operator or API call), segment (on entering a segment), or cdp_event (when an event is received). Defaults to manual.' type: string enum: - manual - segment - cdp_event segmentId: description: Segment id — required when triggerType is segment. type: string segmentName: description: Cached segment display name (optional). type: string eventName: description: CDP event name — required when triggerType is cdp_event. type: string maxEnrollments: description: 'Frequency cap: max enrollments per person within enrollmentWindow. Both-or-neither with enrollmentWindow.' type: integer minimum: 1 maximum: 9007199254740991 enrollmentWindow: description: Rolling window for the frequency cap. type: string description: Trigger node config. Exactly one ENTRY node per journey. required: - id - kind - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: SEND_MESSAGE name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: templateId: description: Approved WhatsApp template id. Resolve ids from the catalog. type: string templateName: type: string channel: description: Send channel. Only whatsapp is live today. type: string enum: - whatsapp - sms - email templateBindings: description: Map of template placeholder → variable reference. type: object propertyNames: type: string additionalProperties: type: string channelId: description: Sending WhatsApp channel (WABA) id. Required before publishing. type: string sendImmediately: description: Deprecated business-hours gate; prefer a preceding DELAY. type: boolean description: Sends a WhatsApp template. required: - id - kind - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: CONVERSATION_BLOCK name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: goal: type: string maxTimeout: description: How long to wait for a reply before timing out. type: string mode: type: string enum: - AGENT - ESCALATE outputs: type: array items: type: object properties: id: type: string label: type: string type: type: string enum: - string - number - date - boolean - json description: type: string builtin: type: boolean required: - id - label - type - builtin description: Legacy combined wait + AI conversation block. required: - id - kind - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: WAIT_FOR_REPLY name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: maxTimeout: description: How long to wait for the first reply before timing out. type: string description: Waits for the person to reply. required: - id - kind - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: MANAGE_CONVERSATION name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: mode: description: AGENT (AI-led) or ESCALATE (human handoff). Defaults to AGENT. type: string enum: - AGENT - ESCALATE inactivityTimeout: description: Rolling idle window (e.g. '12h'), resets on each inbound message. After this much silence the node routes INACTIVE (extracts, does not close). Range 1h–24h; requires the journey-inactivity-timeout flag. type: string description: Runs the AI-led conversation. required: - id - kind - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: DISPATCH_EVENT name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: eventName: type: string minLength: 1 description: CDP event name to record. Must match the CDP name pattern. properties: description: 'Literal string values, or { var: path } bindings resolved to typed values at dispatch time.' type: object propertyNames: type: string additionalProperties: anyOf: - type: string - type: object properties: var: type: string required: - var description: type: string required: - eventName description: Records a CDP event for the person. required: - id - kind - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: DELAY name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: mode: description: How the wait is measured. Defaults to duration. type: string enum: - duration - until_date - until_weekday duration: description: For mode duration. type: string targetAt: description: ISO 8601 instant, for mode until_date. type: string weekdays: description: ISO weekdays 1=Mon..7=Sun, for mode until_weekday. type: array items: type: integer minimum: 1 maximum: 7 windowStartMinutes: type: integer minimum: 0 maximum: 1439 windowEndMinutes: type: integer minimum: 0 maximum: 1439 timezone: description: IANA timezone. Load-bearing for until_weekday. type: string description: type: string description: Pauses the run. required: - id - kind - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: DECISION name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: logic: type: string enum: - AND - OR conditions: type: array items: oneOf: - type: object properties: kind: type: string const: value selectionPath: type: string description: Dot-path into the run, e.g. workflowState.totalPrice. operator: type: string enum: - eq - neq - gt - lt - contains - isSet value: type: string required: - kind - selectionPath - operator - value - type: object properties: kind: type: string const: event eventName: type: string subjectSelectionPath: type: string occurred: type: boolean required: - kind - eventName - subjectSelectionPath - occurred - type: object properties: kind: type: string const: cdp_predicate term: type: object propertyNames: type: string additionalProperties: {} description: A single live person/computed predicate term. See journeys_authoring_catalog for its shape. required: - kind - term - type: object properties: kind: type: string const: cdp_object objectType: type: string matchAttr: type: string matchSelectionPath: type: string exists: type: boolean required: - kind - objectType - matchAttr - matchSelectionPath - exists description: One decision condition. description: type: string required: - logic - conditions description: Two-way branch. Emits YES / NO. required: - id - kind - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: CASE name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: selectionPath: type: string description: Person attribute (attributes.*) or extracted field (engagement.extracted.*) to switch on. branches: type: array items: type: object properties: id: type: string description: Stable branch id; edge handle is case:. value: type: string description: Value matched. Unique within the node. label: type: string required: - id - value description: Up to 10 branches. A case:default handle is always required. description: type: string required: - selectionPath - branches description: N-way switch on a person attribute. required: - id - kind - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: HTTP_REQUEST name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: method: type: string enum: - GET - POST - PUT - PATCH - DELETE description: HTTP method. url: type: string minLength: 1 description: Target URL. Supports {{variable}} placeholders. headers: description: Request headers as key/value pairs. type: array items: type: object properties: key: type: string value: type: string required: - key - value body: description: Request body. mode none sends no body. type: object properties: mode: type: string enum: - none - json - raw content: type: string contentType: type: string required: - mode credentialId: description: HttpCredential id used to authenticate the request. type: string timeoutMs: description: Request timeout in milliseconds. Max 30000 (30s). type: integer exclusiveMinimum: 0 maximum: 30000 maxAttempts: description: Max attempts including the first. Max 5. type: integer exclusiveMinimum: 0 maximum: 5 documentUrlTtlSeconds: description: TTL (seconds, ≤86400) for presigned engagement.documents URLs this node emits. Default 86400. type: integer exclusiveMinimum: 0 maximum: 86400 required: - method - url description: Calls an external HTTP endpoint. Emits SUCCESS or FAILED. required: - id - kind - type: object properties: id: type: string minLength: 1 description: Node id, unique within the journey. kind: type: string const: EXIT name: type: string minLength: 1 description: The label shown on the canvas. Required before publishing. position: type: object properties: x: type: number y: type: number required: - x - y description: Explicit canvas position. Omit it and the server auto-lays-out the graph top-down; only set it to preserve a hand-arranged layout. inputs: type: object properties: outcome: type: string nextInitiativeId: description: Chain into another initiative on exit. type: string description: Terminal node. required: - id - kind description: The nodes. Exactly one ENTRY and at least one EXIT are required to publish. edges: type: array items: type: object properties: from: type: string description: Source node id. to: type: string description: Target node id. sourceHandle: type: string description: The emitted signal that activates this edge (e.g. SENT, REPLIED, YES, case:). A handle may wire to at most one node. metadata: type: object properties: signalCategory: type: string enum: - lifecycle - system signalDescription: type: string required: - from - to - sourceHandle description: 'A connection: node `from` routes to `to` when it emits `sourceHandle`.' description: The connections between node handles. required: - name - actions - edges description: The full journey graph. Drafts may be incomplete; run journeys_validate before publishing. required: - definition responses: '200': description: Success content: application/json: schema: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: valid: type: boolean description: True when there are no error-severity issues. issues: type: array items: type: object properties: code: type: string description: Stable issue code. severity: type: string enum: - error - warning description: error blocks publishing; warning is advisory. nodeId: description: The node this issue is about, if any. type: string message: type: string description: Plain-English explanation. required: - code - severity - message additionalProperties: false required: - valid - issues additionalProperties: false '400': description: Validation failed or the request cannot proceed. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '401': description: Missing, malformed, or revoked API key. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '404': description: The resource does not exist in this organization. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '409': description: Conflicts with the current state (duplicates, wrong lifecycle state). content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '422': description: The request is well-formed but semantically invalid. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '429': description: Rate limit exceeded — retry after `Retry-After`. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '500': description: Internal server error. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error '503': description: Transient error — retry with a narrower request. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Stable machine-readable error code (snake_case). message: type: string required: - code - message required: - error components: securitySchemes: bearerAuth: type: http scheme: bearer description: 'Organization API key, sent as `Authorization: Bearer boom_org_...`.'