Execution & Plays

Triggering a Flow

POST /api/flows/{flowId}/run
Content-Type: application/json

{
  "args": {
    "invoiceId": "INV-001",
    "customerEmail": "client@example.com"
  }
}

Response:

{
  "playId": "65xyz789",
  "state": "RUN"
}

The args map is available in expressions throughout the flow as {{ $prev.args.invoiceId }}.

Play States

State	Meaning
`NEW`	Created, not yet started
`RUN`	Currently executing
`DONE`	Completed successfully
`FAIL`	Failed at one or more steps
`SKIP`	Flow was skipped by logic
`FILTERED`	All steps were filtered out
`DEFERRED`	Queued for later execution
`WAIT`	Waiting for approval or external event
`ON_HOLD`	Manually paused

Polling for Results

GET /api/plays/{playId}

{
  "id": "65xyz789",
  "flowId": "65abc123",
  "state": "DONE",
  "startedAt": "2024-01-15T10:05:00Z",
  "completedAt": "2024-01-15T10:05:03Z",
  "duration": 3241
}

Poll with a simple loop:

while true; do
  STATE=$(curl -s -b cookies.txt http://localhost:4454/api/plays/$PLAY_ID | jq -r '.state')
  if [[ "$STATE" == "DONE" || "$STATE" == "FAIL" ]]; then
    echo "Final state: $STATE"
    break
  fi
  sleep 1
done

Getting Step Output

GET /api/plays/{playId}/layers

[
  {
    "id": "65layer1",
    "ref": "downloadPdf",
    "state": "DONE",
    "startedAt": "2024-01-15T10:05:00Z",
    "completedAt": "2024-01-15T10:05:01Z",
    "out": {
      "statusCode": 200,
      "body": "...",
      "headers": {"content-type": "application/pdf"}
    }
  },
  {
    "id": "65layer2",
    "ref": "extractText",
    "state": "DONE",
    "out": {
      "text": "Invoice #INV-001\nAmount: $1,250.00\n..."
    }
  }
]

Real-time Monitoring via WebSocket

Instead of polling, subscribe to real-time events:

const ws = new WebSocket('ws://localhost:4454/api/ws');

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  if (msg.playId === targetPlayId) {
    console.log(`Step ${msg.ref} → ${msg.state}`, msg.out);
  }
};

See the WebSocket API reference for full event format.

Idempotent Execution

Pass an idempotency key to prevent duplicate executions:

POST /api/flows/{flowId}/run
{
  "args": {"orderId": "ORD-999"},
  "idempotencyKey": "process-order-ORD-999"
}

If a play with this key already exists and is DONE, the same play is returned rather than creating a new one.

Listing Play History

GET /api/flows/{flowId}/plays?state=FAIL&size=25&page=0

Returns paginated list of plays filtered by state, date range, or other criteria.