Sign in

v5

OpenAPI 3.1.02026-07-31129337684.6 KB
Workflow Execution

Execute Workflow

Execute a workflow interactively over standard HTTP POST.

First turn (run_id absent in request body): Starts a new interactive session, runs until pause/terminal, and returns a run_id the client must echo back on all subsequent requests.

Subsequent turns (run_id present): Resumes the paused session with new user input, runs until the next pause or terminal state.

Cancellation (run_id present, run_input.command = "stop"): Cancels the session, flushes state to MongoDB, returns status=CANCELLED.

post/workflows/v1/workflows/{workflow_id}/execute

Path parameters

workflow_idstring required
Example:5eb7cf5a86d9755df3a6c593

Query parameters

versioninteger nullable

Workflow version to run. Applies to the first turn only; subsequent turns always use the version from the initial turn.

Workflow version to run. Applies to the first turn only; subsequent turns always use the version from the initial turn.

Request body

run_idstring nullable

Interactive session identifier. Omit on the first request — the server will derive one from MongoDB and return it. Echo back on all subsequent requests to continue the session.

Example request

{
  "run_input": {
    "workflow_id": "5eb7cf5a86d9755df3a6c593",
    "workflow_run_id": "5eb7cf5a86d9755df3a6c593"
  }
}

Response

Successful Response

run_idstring required

Session identifier (= MongoDB ObjectId of the underlying WorkflowRun record). Include in all subsequent POST requests to continue this session.

status'not_started' | 'started' | 'running' | 'failed' | 'completed' | 'paused' | 'waiting_for_user_input' | 'cancelled' | 'aborted_looping_risk' required
turn_numberinteger required

The turn that this response corresponds to (1-indexed).

eventsobject[] required

All events emitted by the workflow runtime during this turn. Includes start/end-node events, LLM events, show-state events, and the terminal pause/end/error event.

is_waiting_for_inputboolean required

True when the workflow paused and is waiting for user input in the next POST request.

is_completedboolean required

True when the workflow has reached a terminal state (completed, failed, cancelled, or aborted).

errorstring nullable

Present when status is FAILED. Human-readable error message.

next_input_hintobject nullable

Serialised BusyWaitForUserMessageEvent payload when is_waiting_for_input=True. Describes what the workflow expects as input in the next turn.

has_active_companionsboolean

True when fork-companion threads are still running background work (e.g. a polling self-loop) after this turn. A scheduler/client can call the pump-companions endpoint on an interval to advance them while the main thread waits for the next user input.

has_background_workboolean

True when ANY background work remains after this turn: an active fork companion, or a parked thread with an armed conditional-edge evaluation (see EvaluateWhileWaitingConfig). This is the flag a scheduler/client should poll the pump-companions endpoint on — it is a superset of has_active_companions, which is retained for backward compatibility. Note that a pump may now return MAIN-thread assistant output, when a waiting condition matched and the workflow advanced without a user turn.