Skip to main content
POST
Create a workflow run. The canonical API route is flat: workflow_id belongs in the request body, not in the URL. The response returns immediately with lifecycle.status set to "running" or "pending" — use the Get Run endpoint to check for updates. Workflows can accept two types of inputs:
  • documents: File inputs for Document (start) blocks
  • json_inputs: JSON data for JSON Input (start_json) blocks

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Create a new workflow run from a workflow id, an optional version selector, and optional inputs.

workflow_id
string
required

Workflow id for the fresh run.

documents
Documents · object

Mapping of start_document block IDs to their input documents.

json_inputs
Json Inputs · object

Mapping of start-json block IDs to their input JSON data.

version
string
default:production

Workflow version to run: 'production', 'draft', or a pinned version id like 'ver_...'. Only valid for fresh-run creation.

Examples:

"production"

"draft"

"ver_abc123def456"

metadata
Metadata · object | null

User-defined metadata to associate with this workflow run.

Response

Successful Response

A single execution of a workflow.

id
string
required

Unique ID for this run

workflow_id
string
required

ID of the workflow that was run

workflow_version_id
string
required

Content-addressed workflow version used for this run.

trigger
TriggerInfo · object
required

What started this run

lifecycle
PendingRun · object
required

The run has been created but execution has not started.

timing
RunTiming · object
required

All timing information

inputs
RunInputs · object

Input payloads supplied at run creation time

metadata
Metadata · object | null

User-defined metadata associated with this workflow run.