Start Run | Onepin

{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "workflow_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "status": "running",
    "run_number": 42,
    "token_cost": 350,
    "created_at": "2024-04-20T14:20:00Z",
    "updated_at": "2024-04-20T14:22:00Z",
    "total_nodes": 12,
    "total_steps": 48,
    "finished_steps": 10,
    "usage_summary": {},
    "started_at": "2024-04-20T14:22:00Z",
    "completed_at": "null",
    "pause_requested_at": "null",
    "paused_at": "null",
    "error": "null",
    "has_export": false,
    "triggered_by": {
      "user_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "user_name": "jane.doe@example.com"
    },
    "credits": 5
  },
  "meta": {
    "request_id": "req_1234567890abcdef",
    "timestamp": "2024-04-20T14:22:01Z"
  }
}

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.

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.

Authentication

AuthorizationBearer

Clerk JWT token

AuthorizationBearer

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

Path parameters

workflow_idstringRequiredformat: "uuid"

Request

This endpoint expects a nullable object.

script_textstring or nullOptional>=1 character

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