Documentation Index
Fetch the complete documentation index at: https://docs.kaireonai.com/llms.txt
Use this file to discover all available pages before exploring further.
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 |
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" }
}'
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 |
entryCondition | object | Updated entry condition |
maxDurationDays | integer | Updated max duration |
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) |
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
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
| Field | Type | Required | Description |
|---|
customerAttributes | object | No | Simulated 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 Type | Behavior |
|---|
entry_trigger | Journey entry point |
wait | Wait for configured duration |
condition_split | Evaluates condition against customer attributes (true/false branching) |
nba_decision | Requests a next-best-action decision |
channel_action | Sends via configured channel |
exit | Journey 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
| 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 |
