Skip to main content
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

​
GET /api/v1/journeys

List all journeys with offset-based pagination.

​
Query Parameters

ParameterTypeDefaultDescription
statusstring—Filter by status: "draft", "active", "paused", "archived"
limitinteger50Max results (max 200)
offsetinteger0Pagination 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

FieldTypeRequiredDescription
namestringYesJourney name (max 255 chars)
descriptionstringNoDescription (max 2000 chars)
definitionobjectNoFlow definition with nodes and edges. Default: { nodes: [], edges: [] }
entryConditionobjectNoEntry trigger condition
maxDurationDaysintegerNoMax journey duration in days (1-365). Default: 30

​
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.
FieldTypeDescription
namestringUpdated name
descriptionstringUpdated description
statusstring"draft", "active", "paused", "archived"
definitionobjectUpdated flow definition
entryConditionobjectUpdated entry condition
maxDurationDaysintegerUpdated 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

FieldTypeRequiredDescription
customerIdstringNoSingle customer ID to enroll
customerIdsstring[]NoBatch 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
}
FieldDescription
journeyIdThe journey ID
journeyNameThe journey’s display name
enrolledNumber of customers newly enrolled
skippedNumber of customers already enrolled (duplicates)
errorsNumber of enrollment failures (e.g., database errors)
totalTotal customers processed

​
Error Codes

CodeReason
400Journey is not in active status
404Journey not found

​
POST /api/v1/journeys//test

Simulate journey execution with sample customer attributes. Walks through the flow graph step by step, evaluating condition splits and producing a trace of decisions.

​
Request Body

FieldTypeRequiredDescription
customerAttributesobjectNoSimulated customer attributes for condition evaluation

​
Response

{
  "steps": [
    { "nodeId": "n1", "nodeType": "entry_trigger", "decision": "customer enters journey", "timestamp": "2026-03-16T14:30:00.000Z" },
    { "nodeId": "n2", "nodeType": "condition_split", "decision": "condition met (true branch)", "timestamp": "2026-03-16T14:30:00.001Z" },
    { "nodeId": "n3", "nodeType": "nba_decision", "decision": "NBA decision requested (decision flow: default-flow)", "timestamp": "2026-03-16T14:30:00.002Z" },
    { "nodeId": "n4", "nodeType": "channel_action", "decision": "send via email", "timestamp": "2026-03-16T14:30:00.003Z" },
    { "nodeId": "n5", "nodeType": "exit", "decision": "journey complete", "timestamp": "2026-03-16T14:30:00.004Z" }
  ],
  "outcome": "completed"
}

​
Supported Node Types

Node TypeBehavior
entry_triggerJourney entry point
waitWait for configured duration
condition_splitEvaluates condition against customer attributes (true/false branching)
nba_decisionRequests a next-best-action decision
channel_actionSends via configured channel
exitJourney complete

​
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

EndpointAllowed Roles
GET /journeysadmin, editor
POST /journeysadmin, editor
PUT /journeys/{id}admin, editor
DELETE /journeys/{id}admin
POST /journeys/{id}/enrolladmin, editor
POST /journeys/{id}/testadmin, editor
GET /journeys/{id}/analyticsadmin, editor, viewer
See also: Journeys