Boom Ai Journeys API
The Journeys API from Boom Ai — 16 operation(s) for journeys.
OpenAPI Specification
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
# --- truncated at 32 KB (742 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/boom-ai/refs/heads/main/openapi/boom-ai-journeys-api-openapi.yml