Journeys API

Journeys are multi-step, multi-channel automation workflows that move customers through a sequence of actions based on entry criteria, branching logic, time delays, and exit conditions. Journeys are defined as a DAG (directed acyclic graph) of tiles connected by edges.

Endpoints

List Journeys

GET /api/v1/workspaces/{id}/journeys

Returns all journeys in the workspace.

Response

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "workspace_id": "660e8400-e29b-41d4-a716-446655440000",
    "parent_model_id": "770e8400-e29b-41d4-a716-446655440000",
    "name": "Onboarding Flow",
    "description": "Welcome series for new customers",
    "entry_criteria": {...},
    "exit_criteria": {...},
    "tiles": [...],
    "edges": [...],
    "schedule": "0 */6 * * *",
    "status": "active",
    "status_error": "",
    "created_by": "880e8400-e29b-41d4-a716-446655440000",
    "created_at": "2024-01-15T09:30:00Z",
    "updated_at": "2024-01-15T09:30:00Z",
    "last_run_id": "990e8400-e29b-41d4-a716-446655440000",
    "last_run_at": "2024-01-15T15:00:00Z"
  }
]

Example

curl -X GET https://your-instance.signalsmith.io/api/v1/workspaces/{id}/journeys \
  -H "Authorization: Bearer <token>" \
  -H "X-Workspace-ID: <workspace-id>"

Create Journey

POST /api/v1/workspaces/{id}/journeys

Creates a new journey.

Request Body

Tile Types

Tiles define the steps in a journey:

Example

curl -X POST https://your-instance.signalsmith.io/api/v1/workspaces/{id}/journeys \
  -H "Authorization: Bearer <token>" \
  -H "X-Workspace-ID: <workspace-id>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Onboarding Flow",
    "description": "Welcome series for new customers",
    "parent_model_id": "770e8400-e29b-41d4-a716-446655440000",
    "schedule": "0 */6 * * *",
    "tiles": [
      {
        "id": "tile-1",
        "type": "entry",
        "position": {"x": 0, "y": 0}
      },
      {
        "id": "tile-2",
        "type": "sync",
        "config": {
          "destination_id": "880e8400-e29b-41d4-a716-446655440000",
          "field_mapping": [...]
        },
        "position": {"x": 0, "y": 200}
      },
      {
        "id": "tile-3",
        "type": "wait",
        "config": {"duration": 3, "unit": "days"},
        "position": {"x": 0, "y": 400}
      }
    ],
    "edges": [
      {"from": "tile-1", "to": "tile-2"},
      {"from": "tile-2", "to": "tile-3"}
    ]
  }'

Get Journey

GET /api/v1/workspaces/{id}/journeys/{journeyId}

Returns a single journey by ID, including the full tile DAG definition.

Update Journey

PUT /api/v1/workspaces/{id}/journeys/{journeyId}

Updates an existing journey. Changes to active journeys take effect on the next evaluation run.

Delete Journey

DELETE /api/v1/workspaces/{id}/journeys/{journeyId}

Deletes a journey. Active journeys must be paused before deletion.

Response

{
  "status": "deleted"
}

Validate Journey

POST /api/v1/workspaces/{id}/journeys/{journeyId}/validate

Validates the journey’s tile DAG for structural correctness. Checks for:

• Exactly one entry tile
• No cycles in the graph
• All edges reference valid tiles
• Required configuration on each tile type

Response

{
  "valid": true,
  "errors": []
}

Or with validation errors:

{
  "valid": false,
  "errors": [
    "Journey must have exactly one entry tile",
    "Tile 'tile-5' has no incoming edges and is not an entry tile"
  ]
}

Activate Journey

POST /api/v1/workspaces/{id}/journeys/{journeyId}/activate

Activates a journey, enabling it to evaluate entry criteria and process members on schedule. The journey must pass validation before activation.

Response

Returns the updated journey object with status: "active".

Pause Journey

POST /api/v1/workspaces/{id}/journeys/{journeyId}/pause

Pauses an active journey. Members currently in the journey remain at their current tile but no new evaluations occur.

Response

Returns the updated journey object with status: "paused".

Resume Journey

POST /api/v1/workspaces/{id}/journeys/{journeyId}/resume

Resumes a paused journey.

Response

Returns the updated journey object with status: "active".

Trigger Evaluation

POST /api/v1/workspaces/{id}/journeys/{journeyId}/trigger

Manually triggers a journey evaluation run. Evaluates entry criteria, moves members through tiles, and processes any pending actions.

Response

Returns the created journey run object with status 201 Created.

Example

curl -X POST https://your-instance.signalsmith.io/api/v1/workspaces/{id}/journeys/{journeyId}/trigger \
  -H "Authorization: Bearer <token>" \
  -H "X-Workspace-ID: <workspace-id>"

List Runs

GET /api/v1/workspaces/{id}/journeys/{journeyId}/runs

Returns the evaluation history for a journey (last 50 runs).

Get Run

GET /api/v1/workspaces/{id}/journeys/{journeyId}/runs/{runId}

Returns details of a specific journey run.

Cancel Run

POST /api/v1/workspaces/{id}/journeys/{journeyId}/runs/{runId}/cancel

Cancels a running evaluation.

Response

{
  "status": "cancelled"
}

Get Stats

GET /api/v1/workspaces/{id}/journeys/{journeyId}/stats

Returns aggregate statistics for a journey, including member counts by tile and status.

Response

{
  "tiles": {},
  "total": {
    "active": 0,
    "completed": 0,
    "exited": 0
  }
}

Journey Object

Journey Member Statuses