Journeys API

Journeys are multi-step onboarding or engagement sequences that guide users through a canvas of nodes (triggers, flows, waits, conditions, goals) connected by edges. All endpoints require JWT authentication.

List Journeys

GET /api/journeys

Query Parameters

Parameter	Type	Default	Description
page	string	"1"	Page number
limit	string	"20"	Items per page
status	string	—	Filter by lifecycle status (DRAFT, PUBLISHED, PAUSED, ARCHIVED)
siteId	uuid	—	Filter by site

Response

{
  "data": [
    {
      "id": "j_abc123",
      "name": "New User Onboarding",
      "description": "Guide new users through core features",
      "status": "PUBLISHED",
      "audienceId": "aud_xyz",
      "siteId": "site_xyz",
      "settings": {},
      "goalConfig": null,
      "createdAt": "2025-01-10T09:00:00Z",
      "updatedAt": "2025-01-15T12:00:00Z",
      "_count": { "nodes": 5, "edges": 4, "enrollments": 128 }
    }
  ],
  "meta": { "total": 8, "page": 1, "limit": 20, "totalPages": 1 }
}

Create Journey

POST /api/journeys

Request Body

{
  "name": "New User Onboarding",
  "siteId": "site_xyz",
  "description": "Guide new users through core features",
  "audienceId": "aud_xyz",
  "settings": {},
  "goalConfig": {
    "type": "flow_completed",
    "config": { "flowId": "flow_abc" },
    "deadline": 7
  },
  "nodes": [
    {
      "type": "TRIGGER",
      "config": {
        "triggerType": "URL_MATCH",
        "triggerConfig": { "matchType": "contains", "pattern": "/dashboard" }
      },
      "position": { "x": 0, "y": 0 }
    },
    {
      "type": "CONTENT",
      "contentId": "flow_abc",
      "config": { "contentType": "flow" },
      "position": { "x": 200, "y": 0 }
    }
  ],
  "edges": [{ "sourceNodeId": "<node-1-id>", "targetNodeId": "<node-2-id>" }]
}

Field	Type	Required	Description
name	string (1-255)	Yes	Journey name
siteId	uuid	Yes	Site the journey belongs to
description	string	No	Description
audienceId	uuid	No	Target audience for auto-enrollment
settings	object	No	Journey-level settings
goalConfig	object	No	Goal definition (see "Goal Config" below)
allowAnonymous	boolean	No	Allow enrollment by anonymousId for unidentified visitors
nodes	array	No	Initial canvas nodes
edges	array	No	Initial canvas edges connecting nodes

Node Types

Type	Description
TRIGGER	Entry point. config.triggerType is one of URL_MATCH, CUSTOM_EVENT, ELEMENT_CLICK, MANUAL.
CONTENT	Renders a content item by contentId. Set config.contentType (e.g., "flow", "tooltip") to disambiguate.
WAIT	Waits a fixed duration before continuing
WAIT_FOR_EVENT	Pauses until a specific event fires for the user
CONDITION	Branches on user traits or evaluated rules
SPLIT	Randomized A/B split between outgoing edges
GOAL_CHECK	Evaluates whether the journey goal has been met
EXIT	Terminal node — marks the enrollment as completed

Goal Config

Field	Type	Description
type	string	event, page_visit, attribute_match, or flow_completed
config	object	Type-specific payload (e.g. { "eventName": "signup_completed" })
deadline	integer	Optional number of days to reach the goal before the journey is abandoned

Get Journey

GET /api/journeys/:id

Returns the journey with all nodes, edges, audience details, and counts.

Update Journey

PATCH /api/journeys/:id

Updates journey metadata (name, siteId, description, audienceId, settings, goalConfig, allowAnonymous) as a partial update — only provided fields are modified. The canvas (nodes/edges) is managed separately via PUT /api/journeys/:id/canvas.

Save Canvas

PUT /api/journeys/:id/canvas

Replaces the entire canvas (nodes + edges) in a single atomic transaction. Use this after editing the journey in the builder.

Request Body

{
  "nodes": [
    {
      "id": "<uuid>",
      "type": "TRIGGER",
      "config": {
        "triggerType": "MANUAL",
        "triggerConfig": {}
      },
      "position": { "x": 0, "y": 0 }
    },
    {
      "id": "<uuid>",
      "type": "CONTENT",
      "contentId": "flow_abc",
      "config": { "contentType": "flow" },
      "position": { "x": 220, "y": 0 }
    }
  ],
  "edges": [
    {
      "sourceNodeId": "<trigger-node-uuid>",
      "targetNodeId": "<content-node-uuid>",
      "label": "Start"
    }
  ]
}

All existing nodes and edges for the journey are deleted and replaced. Node id values are optional on create; supply existing UUIDs to preserve them across saves.

Archive Journey

DELETE /api/journeys/:id

Soft-deletes the journey (sets status to ARCHIVED) and stops all active enrollments. Use POST /api/journeys/:id/restore to bring it back.

Publish Journey

POST /api/journeys/:id/publish

Activates the journey. Users matching the audience criteria will begin enrollment.

Unpublish Journey

POST /api/journeys/:id/unpublish

Moves a published journey back to DRAFT. New enrollments stop; existing enrollments are left as-is.

Pause Journey

POST /api/journeys/:id/pause

Pauses the journey. No new users are enrolled; existing enrollments continue.

Restore Journey

POST /api/journeys/:id/restore

Restores an archived journey back to DRAFT.

List Enrollments

GET /api/journeys/:id/enrollments

Returns paginated list of users enrolled in this journey.

Response

{
  "data": [
    {
      "id": "enroll_abc",
      "journeyId": "j_abc123",
      "endUserId": "eu_456",
      "status": "in_progress",
      "enrolledAt": "2025-01-12T10:00:00Z",
      "endUser": { "id": "eu_456", "traits": { "role": "admin" } }
    }
  ],
  "meta": { "total": 128, "page": 1, "limit": 20, "totalPages": 7 }
}