WebSocket API
Keep dashboards and integrations current with execution progress, results, and failures.
Connection
ws://localhost:8080/engine/ws
Send a subscribe message to receive events. Each subscription follows one or more aggregates: ordered event streams for a catalog, cluster, Feed version, or individual Flow.
Subscribe
{
"type": "subscribe",
"data": {
"sub_id": "flow-detail",
"aggregate_ids": [["flow", "wf-123"]],
"event_types": ["flow_started", "step_completed", "flow_completed"],
"include_state": true
}
}
| Field | Description |
|---|---|
sub_id | Required client-defined subscription ID |
aggregate_ids | Optional array of aggregate IDs to follow, where omitted or empty follows all aggregates |
event_types | Optional event type filter |
include_state | If true, server first sends the current projected state, then streams live events |
Aggregate IDs
An aggregate ID is a type and a key. Catalog and cluster are singleton aggregates whose key is _, which subscriptions may omit. Server responses and events always include both components.
| ID | Meaning |
|---|---|
["catalog", "_"] or ["catalog"] | Step, Space, and Feed registry (registrations, updates) |
["cluster", "_"] or ["cluster"] | Cluster state (per-Step health across nodes) |
["flow", "flow-id"] | One Flow’s execution events |
["feed", "feed-id:version"] | One Feed version’s folded value |
A Feed key joins the Feed ID and the version that GET /engine/feeds/{feed_id} returns.
To follow every Flow, omit aggregate_ids and filter with event_types.
Subscribed Response
When include_state: true, the server sends current state before live events:
{
"type": "subscribed",
"sub_id": "flow-detail",
"items": [
{
"id": ["flow", "wf-123"],
"data": { "id": "wf-123", "status": "active" },
"sequence": 42
}
]
}
Event Messages
{
"type": "flow_started",
"data": {
"flow_id": "wf-123",
"init": { "customer_id": ["cust-456"] },
"plan": { "...": "..." },
"tags": ["customer:cust-456"]
},
"id": ["flow", "wf-123"],
"sub_id": "flow-detail",
"timestamp": 1704067425000,
"sequence": 42
}
Event Types
Catalog (Aggregate ["catalog", "_"])
step_registered, step_unregistered, step_updated, space_registered, space_updated, space_unregistered, feed_registered, feed_updated, feed_unregistered
Feed (Aggregate ["feed", "feed-id:version"])
feed_folded, feed_fold_failed
Cluster (Aggregate ["cluster", "_"])
step_health_changed
Flow (Aggregate ["flow", "flow-id"])
flow_started, flow_completed, flow_failed, flow_deactivated, step_started, step_completed, step_failed, step_skipped, attribute_set, work_started, work_succeeded, work_failed, work_not_completed, work_retry_scheduled, dispatch_deferred, comp_started, comp_succeeded, comp_failed, comp_retry_scheduled
A comp_failed event records the Work Item status compensate_failed.
For lifecycle consumers, flow_completed and flow_failed establish an outcome that callers can use immediately. flow_deactivated is emitted once no pending, active, or compensating Work Items can still produce side effects and no parent Flow can still order a rollback.
Sequence numbers are per aggregate, so compare them only within one aggregate. Events committed together arrive individually.
Unsubscribe
{
"type": "unsubscribe",
"data": { "sub_id": "flow-detail" }
}
Reconnection
On disconnect, reconnect and resubscribe with the same filters. Each event arrives once across the initial state and live events.