Skip to main content
POST
Run Workflow by ID

Authorizations

Authorization
string
header
required

Every request authenticates with an API key: Authorization: Bearer {API_KEY}. App endpoints take an app API key; knowledge endpoints take a knowledge base API key (Get Started).

Keep keys server-side; never embed them in client code. Requests with a missing or invalid key fail with HTTP 401 (unauthorized).

Path Parameters

workflow_id
string
required

Published workflow version to run. Returned in the workflow_id field of Run Workflow responses and Get Workflow Run Detail. Must reference a published version; a draft version ID is rejected with bad_request.

Body

application/json
inputs
object
required

Key-value pairs for workflow input variables. Discover the variable names and types your app expects from the user_input_form field of Get App Parameters.

File-type variables take an array of file objects with type, transfer_method, and either url or upload_file_id.

user
string
required

End-user identifier, defined by your app and unique within it. Scopes data access: a workflow run and its files are only visible to later requests that carry the same user. See End User Identity.

response_mode
enum<string>

Response mode. Use blocking for synchronous responses (Cloudflare timeout is 100 s), or streaming for Server-Sent Events. When omitted, defaults to blocking behavior.

Available options:
streaming,
blocking
files
object[] | null

File list. Suitable when files need to be combined with text for input, available only when the model supports Vision capability. To attach a local file, first upload it via Upload File and use the returned id as upload_file_id with transfer_method: local_file.

Response

Successful response. The content type and structure depend on the response_mode parameter in the request.

  • If response_mode is blocking, returns application/json with a WorkflowBlockingResponse object.
  • If response_mode is streaming, returns text/event-stream with a stream of ChunkWorkflowEvent objects.
task_id
string<uuid>

Task ID for the in-progress execution. Use this with Stop Workflow Task to cancel a running workflow. Only valid during execution.

workflow_run_id
string<uuid>

Persistent identifier for this workflow run record. Use this with Get Workflow Run Detail to retrieve results after execution.

data
object