Orchestrations API

Orchestrations 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. Orchestrations are defined as a DAG (directed acyclic graph) of tiles connected by edges.

Endpoints

List Orchestrations

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

Returns all orchestrations 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://composable.zeotap.com/api/v1/workspaces/{id}/journeys \
  -H "Authorization: Bearer <token>" \
  -H "X-Workspace-ID: <workspace-id>"

Create Orchestration

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

Creates a new orchestration.

Request Body

Tile Types

Tiles define the steps in an orchestration. The type field takes one of:

Each tile carries a config object whose shape depends on its type — for example, time_delay uses { "duration_minutes": 4320 }, ab_split uses { "branches": [{ "port": "split_0", "label": "A", "percentage": 80 }, ...] }, and send_to_destination uses { "destination_id": "...", "field_mapping": [...] }.

Example

curl -X POST https://composable.zeotap.com/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": "send_to_destination",
        "config": {
          "destination_id": "880e8400-e29b-41d4-a716-446655440000",
          "field_mapping": [...]
        },
        "position": {"x": 0, "y": 200}
      },
      {
        "id": "tile-3",
        "type": "time_delay",
        "config": {"duration_minutes": 4320},
        "position": {"x": 0, "y": 400}
      }
    ],
    "edges": [
      {"from": "tile-1", "to": "tile-2"},
      {"from": "tile-2", "to": "tile-3"}
    ]
  }'

Get Orchestration

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

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

Update Orchestration

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

Updates an existing orchestration. Changes to active orchestrations take effect on the next evaluation run.

Delete Orchestration

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

Deletes an orchestration. Active orchestrations must be paused before deletion.

Response

{
  "status": "deleted"
}

Validate Orchestration

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

Validates the orchestration’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": [
    "Orchestration must have exactly one entry tile",
    "Tile 'tile-5' has no incoming edges and is not an entry tile"
  ]
}

Activate Orchestration

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

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

Response

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

Pause Orchestration

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

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

Response

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

Resume Orchestration

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

Resumes a paused orchestration.

Response

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

Trigger Evaluation

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

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

Response

Returns the created orchestration run object with status 201 Created.

Example

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

Rehearse Orchestration

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

Starts a rehearsal — a simulation of how members would flow through the orchestration over a time window, without executing any destination sends. Rehearsals run asynchronously; poll the result endpoint below with the returned rehearsalId.

Request Body

Get Rehearsal Result

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

Returns the rehearsal result, including per-tile counts (entered, currently there) and orchestration-level totals (entered, completed, exited). No data is written to destinations.

List Runs

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

Returns the evaluation history for an orchestration (last 50 runs).

Get Run

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

Returns details of a specific orchestration 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 an orchestration, including member counts by tile and status.

Response

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

Orchestration Object

Orchestration Member Statuses

Member state is materialized in your warehouse (see Warehouse tables). The status column takes one of: