Start Run

Start a new execution of a workflow (202 Accepted). Enqueues the workflow for asynchronous execution and returns the newly created run in `pending` or `running` status. The run progresses through its nodes in the background; poll `GET /runs/{run_id}/status` for lightweight progress updates, or `GET /runs/{run_id}` once to load the immutable definition snapshot. Use `POST /runs/preview` or `POST /estimate` to compute the credit cost before committing to an actual run — those endpoints are read-only and incur no charges. Returns 409 if the workspace is at its concurrent-run limit or another run for this workflow is already active.

Authentication

AuthorizationBearer
Clerk JWT token
OR
AuthorizationBearer

Onepin live API key (op_live_...). Test and public keys are reserved in Phase 1.

Path parameters

workflow_idstringRequiredformat: "uuid"

Headers

X-Workspace-Idstring or nullOptional

Response

Successful Response
dataobject
metaobject

Errors

422
Unprocessable Entity Error