Journeys

See also: Journeys concept and configuration for what this API powers, when to call it, and how it is configured.

Journeys list view in the Studio module — The Journeys editor.

GET /api/v1/journeys

List all journeys with offset-based pagination.

Query Parameters

Parameter	Type	Default	Description
`status`	string	—	Filter by status: `"draft"`, `"active"`, `"paused"`, `"archived"`
`limit`	integer	`50`	Max results (max 200)
`offset`	integer	`0`	Pagination offset

Response

{
  "data": [
    {
      "id": "journey_001",
      "name": "New Customer Onboarding",
      "description": "7-day onboarding sequence for new customers",
      "status": "active",
      "maxDurationDays": 30,
      "entryCondition": { "event": "account_created" },
      "definition": { "nodes": [], "edges": [] },
      "createdAt": "2026-02-15T10:00:00.000Z"
    }
  ],
  "pagination": { "total": 5, "limit": 50, "offset": 0, "hasMore": false }
}

POST /api/v1/journeys

Create a new journey.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Journey name (max 255 chars)
`description`	string	No	Description (max 2000 chars)
`definition`	object	No	Flow definition with `nodes` and `edges`. Default: `{ nodes: [], edges: [] }`
`entryCondition`	object	No	Entry trigger condition
`maxDurationDays`	integer	No	Max journey duration in days (1-365). Default: `30`

Definition validation

The definition graph is structurally validated on create and update. A payload that fails any of these checks is rejected with 422 VALIDATION_ERROR (details.fields.definition lists every problem):

nodes and edges must be arrays (of objects)
every node needs a non-empty string id, and node ids must be unique
every edge’s source and target must reference an existing node id
the graph must be acyclic (the runtime engine has no loop guard, so cycles are rejected at save time)

Node type values are not restricted — the engine executes entry_trigger, wait, condition_split, nba_decision, channel_action, ab_split, webhook_wait, and exit (the Studio editor exposes the first six; ab_split and webhook_wait are API-authored).

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid journey definition",
    "status": 422,
    "details": { "fields": { "definition": ["edges[0].target \"ghost\" does not reference an existing node"] } }
  }
}

Example

curl -X POST https://playground.kaireonai.com/api/v1/journeys \
  -H "Content-Type: application/json" \
  -H "X-Tenant-Id: my-tenant" \
  -d '{
    "name": "New Customer Onboarding",
    "description": "7-day onboarding sequence",
    "maxDurationDays": 30,
    "entryCondition": { "event": "account_created" }
  }'

Response: 201 Created

GET /api/v1/journeys/

Get journey details.

PUT /api/v1/journeys/

Update a journey. All fields are optional.

Field	Type	Description
`name`	string	Updated name
`description`	string	Updated description
`status`	string	`"draft"`, `"active"`, `"paused"`, `"archived"`
`definition`	object	Updated flow definition (structurally validated — see Definition validation)
`entryCondition`	object	Updated entry condition
`maxDurationDays`	integer	Updated max duration

Response: 200 OK

DELETE /api/v1/journeys/

Delete a journey. Requires admin role. Response: 204 No Content

POST /api/v1/journeys//enroll

Enroll one or more customers into an active journey. The journey must be in active status. Duplicate enrollments are silently skipped (not errors).

Request Body

Field	Type	Required	Description
`customerId`	string	No	Single customer ID to enroll
`customerIds`	string[]	No	Batch of customer IDs to enroll (max 1000)

Provide either customerId or customerIds, not both.

Response — `201 Created`

{
  "journeyId": "journey_001",
  "journeyName": "New Customer Onboarding",
  "enrolled": 5,
  "skipped": 1,
  "errors": 0,
  "total": 6
}

Field	Description
`journeyId`	The journey ID
`journeyName`	The journey’s display name
`enrolled`	Number of customers newly enrolled
`skipped`	Number of customers already enrolled (duplicates)
`errors`	Number of enrollment failures (e.g., database errors)
`total`	Total customers processed

Error Codes

Code	Reason
`400`	Journey is not in `active` status
`404`	Journey not found

POST /api/v1/journeys//test

Test Mode — a real-engine dry run. Runs one (real or synthetic) customer through the whole journey and returns a step-by-step trace. Condition splits use the production operator logic and NBA Decision steps call the real decision engine (draft flows previewed), so the offers returned are the ones that customer would actually receive. To keep it safe and instant: waits are fast-forwarded, Channel Action sends are simulated (nothing is delivered), and nothing is persisted (no enrollment, no queue jobs). See Testing a journey. Requires the admin or editor role.

Request Body

Field	Type	Required	Description
`customerId`	string	No	Loads this customer’s real attributes so splits/decisions run against real data
`customerAttributes`	object	No	Synthetic attributes, overlaid on top of the real ones (or used alone), e.g. `{ "tier": "gold", "score": 72 }`

Response

{
  "steps": [
    { "order": 0, "nodeId": "n1", "nodeType": "entry_trigger", "label": "Entry", "detail": "Customer enters the journey.", "timestamp": "2026-03-16T14:30:00.000Z" },
    { "order": 1, "nodeId": "n2", "nodeType": "condition_split", "label": "Condition", "branch": "true", "detail": "Condition met (tier eq \"gold\") → true branch.", "timestamp": "2026-03-16T14:30:00.000Z" },
    { "order": 2, "nodeId": "n3", "nodeType": "nba_decision", "label": "Decision", "detail": "NBA decision (flow: welcome-flow) → Gold Card Upgrade (0.87), Travel Rewards (0.62).", "decision": { "flowKey": "welcome-flow", "offers": [ { "name": "Gold Card Upgrade", "score": 0.87 }, { "name": "Travel Rewards", "score": 0.62 } ] }, "timestamp": "2026-03-16T14:30:00.000Z" },
    { "order": 3, "nodeId": "n4", "nodeType": "channel_action", "label": "Send", "simulated": true, "detail": "Would send \"Welcome Email\" via Email — simulated, nothing delivered.", "timestamp": "2026-03-16T14:30:00.000Z" },
    { "order": 4, "nodeId": "n5", "nodeType": "exit", "label": "Exit", "detail": "Journey complete: completed.", "timestamp": "2026-03-16T14:30:00.000Z" }
  ],
  "outcome": "exited",
  "visitedNodeIds": ["n1", "n2", "n3", "n4", "n5"],
  "notes": [
    "Send steps are simulated — no message was delivered to the customer."
  ]
}

Field	Type	Description
`steps[]`	array	Ordered trace. Each step: `order`, `nodeId`, `nodeType`, `label`, `detail`, optional `branch` (splits), `decision` (NBA offers), `simulated` (sends/webhooks)
`outcome`	string	`exited` \| `completed` \| `ended (no outgoing edge)` \| `ended (cycle detected)` \| `ended (max steps)` \| `empty`
`visitedNodeIds`	string[]	Node ids in visit order — used to highlight the path on the canvas
`notes`	string[]	Caveats restating which steps were fast-forwarded or simulated

Node behavior in Test Mode

Node Type	Behavior
`entry_trigger`	Journey entry point
`wait`	Fast-forwarded — recorded, no real delay
`condition_split`	Evaluates the real condition (`eq/neq/gt/gte/lt/lte/in/exists`); routes true/false
`nba_decision`	Calls the real decision engine and returns the ranked offers
`channel_action`	Simulated — reports the would-be send; nothing delivered
`exit`	Journey complete

POST /api/v1/journeys/callback/

Resumes an enrollment that is paused on a webhook_wait step. When the engine reaches a webhook_wait node it generates a one-time UUID token, an HMAC-SHA256 signature, and an expiry (default 48h, timeoutHours config), stores them on the enrollment, and sets the enrollment status to waiting. An external system calls this endpoint to advance the journey. This endpoint is public — no session or API key required. The signed URL is the credential: the route verifies the HMAC signature (keyed by WEBHOOK_SIGNING_SECRET) and expiry, and the token is one-time use. It is rate-limited per IP (10/min) and per token (5/min).

curl -X POST "https://playground.kaireonai.com/api/v1/journeys/callback/<token>?sig=<hmac>&exp=<iso-expiry>" \
  -H "Content-Type: application/json" \
  -d '{ "event": "external-approval" }'

The optional JSON body is passed to the engine as customer context — a condition_split immediately after the webhook_wait can branch on it.

Response — `200 OK`

{
  "enrollmentId": "b4ab4a02-64ed-4684-a9a3-b61666b66eda",
  "previousStepId": "hook",
  "nextStepId": "final_exit",
  "action": "exit:done",
  "status": "exited"
}

Error Codes

Code	Reason
`400`	Token is not a UUID, or `sig`/`exp` query parameters are missing
`403`	HMAC signature verification failed
`404`	Token unknown, already used (one-time), or the enrollment is no longer `waiting`
`410`	Callback token has expired
`429`	Rate limit exceeded (10/min per IP, 5/min per token)
`503`	`WEBHOOK_SIGNING_SECRET` is not configured (fail-closed)

GET /api/v1/journeys//analytics

Get journey funnel analytics including enrollment counts, completion rates, and per-step metrics.

Response

{
  "funnel": {
    "totalEntries": 15200,
    "activeCount": 3400,
    "completedCount": 8900,
    "exitedCount": 2900,
    "completionRate": 0.5855
  },
  "steps": [
    { "nodeId": "n1", "nodeType": "entry_trigger", "reached": 15200, "dropoff": 0 }
  ]
}

Roles

Endpoint	Allowed Roles
`GET /journeys`	admin, editor
`POST /journeys`	admin, editor
`PUT /journeys/{id}`	admin, editor
`DELETE /journeys/{id}`	admin
`POST /journeys/{id}/enroll`	admin, editor
`POST /journeys/{id}/test`	admin, editor
`GET /journeys/{id}/analytics`	admin, editor, viewer

Overview

Decisioning

Studio

Data

Algorithms & Models

Content & Metrics

Orchestration

Customers & Traces

Events & Attribution

Analytics

AI

Testing & Simulation

Export & Import

Admin

Integrations

GET /api/v1/journeys

Query Parameters

Response

POST /api/v1/journeys

Request Body

Definition validation

Example

GET /api/v1/journeys/

PUT /api/v1/journeys/

DELETE /api/v1/journeys/

POST /api/v1/journeys//enroll

Request Body

Response — `201 Created`

Error Codes

POST /api/v1/journeys//test

Request Body

Response

Node behavior in Test Mode

POST /api/v1/journeys/callback/

Response — `200 OK`

Error Codes

GET /api/v1/journeys//analytics

Response

Roles

​GET /api/v1/journeys

​Query Parameters

​Response

​POST /api/v1/journeys

​Request Body

​Definition validation

​Example

​GET /api/v1/journeys/

​PUT /api/v1/journeys/

​DELETE /api/v1/journeys/

​POST /api/v1/journeys//enroll

​Request Body

​Response — 201 Created

​Error Codes

​POST /api/v1/journeys//test

​Request Body

​Response

​Node behavior in Test Mode

​POST /api/v1/journeys/callback/

​Response — 200 OK

​Error Codes

​GET /api/v1/journeys//analytics

​Response

​Roles

GET /api/v1/journeys

Query Parameters

Response

POST /api/v1/journeys

Request Body

Definition validation

Example

GET /api/v1/journeys/

PUT /api/v1/journeys/

DELETE /api/v1/journeys/

POST /api/v1/journeys//enroll

Request Body

Response — `201 Created`

Error Codes

POST /api/v1/journeys//test

Request Body

Response

Node behavior in Test Mode

POST /api/v1/journeys/callback/

Response — `200 OK`

Error Codes

GET /api/v1/journeys//analytics

Response

Roles