Skip to navigation
ReferenceAPI ReferenceworkflowsRuns

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.

The optional request body supplies run-scoped inputs: script_text (and optionally source_language) replaces the source_script text for THIS run’s snapshot only — the stored workflow definition is not modified, so concurrent runs with different scripts cannot race. Requires exactly one source_script node (422 otherwise).

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.

Requires at least editor role in the workspace; viewers cannot run workflows.

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

Request

This endpoint expects a nullable object.
script_textstring or nullOptional>=3 characters

Run this workflow with this script text instead of the text saved in the workflow's source_script node. Applied to the run's definition snapshot only.

source_languagestring or nullOptional

BCP-47 language of script_text (e.g. en-us). Optional; when omitted the saved source_language (or automatic detection) applies.

Response

Successful Response
dataobject
metaobject

Errors

422
Unprocessable Entity Error