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
  }
}
FieldDescription
sub_idRequired client-defined subscription ID
aggregate_idsOptional array of aggregate IDs to follow, where omitted or empty follows all aggregates
event_typesOptional event type filter
include_stateIf 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.

IDMeaning
["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.