WebSocket API

Subscribe to live execution events without polling.

Connection

WS ws://your-host:4454/api/ws

Authenticate by including the session cookie or API key token as a query parameter:

ws://localhost:4454/api/ws?token=eyJ...

Event Format

All messages are JSON:

{
  "type": "play:layer:completed",
  "playId": "65play1",
  "flowId": "65flow1",
  "layerId": "65layer1",
  "ref": "fetchInvoice",
  "state": "DONE",
  "out": {
    "statusCode": 200,
    "body": {"id": "INV-001"}
  },
  "timestamp": "2024-01-15T10:05:01Z"
}

Event Types

Event	When Fired
`play:started`	A play begins execution
`play:layer:started`	A flowlet begins executing
`play:layer:completed`	A flowlet completes (state: DONE, SKIP, FILTERED)
`play:layer:failed`	A flowlet fails
`play:completed`	Play finishes successfully
`play:failed`	Play finishes with failure
`play:waiting`	Play pauses for approval

JavaScript Client Example

const token = 'eyJ...';
const ws = new WebSocket(`ws://localhost:4454/api/ws?token=${token}`);

ws.onopen = () => console.log('Connected to flow8');

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);

  switch (msg.type) {
    case 'play:started':
      console.log(`Flow started: play ${msg.playId}`);
      break;
    case 'play:layer:completed':
      console.log(`Step ${msg.ref}: ${msg.state}`, msg.out);
      break;
    case 'play:completed':
      console.log(`Flow done in ${msg.duration}ms`);
      break;
    case 'play:failed':
      console.error(`Flow failed at step ${msg.ref}:`, msg.error);
      break;
  }
};

ws.onclose = () => {
  console.log('Disconnected — reconnecting in 3s...');
  setTimeout(connect, 3000);
};

Connection Keepalive

The server sends a ping every 15 seconds. Respond with pong to keep the connection alive. Most WebSocket libraries handle this automatically. The connection closes after 30 seconds without a response.