Skip to main content
POST
/
workflows
/
v1
/
workflows
/
{workflow_id}
/
execute
Execute Workflow
curl --request POST \
  --url https://api-qa.interactly.ai/workflows/v1/workflows/{workflow_id}/execute \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "run_input": {
    "dynamic_variables": {},
    "runtime_variables": {},
    "miscellaneous": {},
    "command": "start",
    "workflow_id": "5eb7cf5a86d9755df3a6c593",
    "version_number": 0,
    "run_by": "<string>",
    "workflow_run_id": "5eb7cf5a86d9755df3a6c593",
    "team_id": "<string>",
    "start_node_logical_id": "<string>",
    "initial_state": {},
    "thread_to_node_inputs": {}
  },
  "run_id": "<string>"
}
'
{
  "run_id": "<string>",
  "turn_number": 123,
  "events": [
    {}
  ],
  "is_waiting_for_input": true,
  "is_completed": true,
  "error": "<string>",
  "next_input_hint": {}
}

Authorizations

​
Authorization
string
header
required

Retrieve your API Key from Dashboard API Keys Section.

Path Parameters

​
workflow_id
string
required
Required string length: 24
Pattern: ^[0-9a-f]{24}$
Example:

"5eb7cf5a86d9755df3a6c593"

Query Parameters

​
version
integer | null

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

Required range: x >= 0

Body

application/json

Request body for POST /v1/workflows/{workflow_id}/execute.

Protocol

  • First turn — omit run_id. The server creates a WorkflowRunsModel in MongoDB, derives the run_id from its ObjectId, and returns it in the response.
  • Subsequent turns — echo back the run_id received in the previous response to continue the session.
  • Cancellation — echo back run_id and set run_input.command = "stop".
​
run_input
WorkflowRunInput · object
required

The workflow run input for this turn.

​
run_id
string | null

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.

Response

Successful Response

Response body for POST /v1/workflows/{workflow_id}/execute.

Returned for both first-turn (no run_id in request) and subsequent turns.

​
run_id
string
required

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

​
status
enum<string>
required

Status of the workflow run after this turn.

Available options:
not_started,
started,
running,
failed,
completed,
paused,
waiting_for_user_input,
cancelled,
aborted_looping_risk
​
turn_number
integer
required

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

​
events
Events · object[]
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_input
boolean
required

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

​
is_completed
boolean
required

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

​
error
string | null

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

​
next_input_hint
Next Input Hint · object

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