WebSocket events

Faimulus uses two server-side WebSocket streams. Both send JSON text frames and support replay by monotonically increasing sequence.

Application stream

Connect to /api/events, optionally with ?after=<sequence>. A new connection first receives a snapshot of pending interactions. If after is provided, replay then starts from the first persisted event with a sequence greater than after.

{
  "version": 1,
  "sequence": 42,
  "type": "interaction-request.required",
  "timestamp": "2026-07-18T12:00:00.000Z",
  "payload": {}
}

Types are interaction-request.required and interaction-request.resolved. Store the highest processed sequence and reconnect with it. If no sequence is supplied, use the initial snapshot as the current baseline.

Snapshots and events contain only requests with broadcasted: true. Scheduled runs are broadcasted by default; direct async, webhook, and channel runs are not.

Run stream

Connect to /api/runs/:runId/events, optionally with ?after=<sequence>. The stream begins with a run snapshot and then emits version-1 run-scoped events. If after is provided, replay starts after that sequence. Event types include run status changes and node start/completion/failure/suspension transitions; payloads carry the relevant node or run data.

{
  "version": 1,
  "sequence": 7,
  "runId": "run-id",
  "type": "node.completed",
  "timestamp": "2026-07-18T12:00:00.000Z",
  "payload": { "nodeId": "summarize" }
}

Sequences are scoped to the stream/store context. Within a stream, sequence values are monotonic and suitable for reconnect checkpoints. Clients must tolerate unknown future event types and fields while continuing to process version 1 envelopes.

Connection behavior

Streams are read-only; control operations use HTTP. Reconnect with backoff, persist the highest applied sequence per stream, and refresh the corresponding HTTP resource after a gap or parse failure.