Create Execution

Start a new execution of a workflow definition within a session.

POST `/revisions/:id/data/command` (Command: `create_execution`)

Request Body

Parameter	Type	Required	Description
`command`	string	Yes	Must be `create_execution`.
`target`	object	Yes	Where it runs: `{"session": "<id or alias>"}`, resolved in the route’s revision. `target` holds only `session`, a non-blank string of at most 64 characters — the route already names the organization, blob and revision.
`workflow`	object	Yes	What to run. See The workflow reference.
`input_data`	array	No	List of input objects `{"alias": "foo", "value": {...}}`.
`description`	string	No	At most 256 characters, stored on the execution. A schedule sends its own `description` here on every fire.

workflow takes one of three shapes at a glance: {definition} for the session’s own revision, {blob, revision, definition} for a blob named by id, in whatever organization it belongs to, or {org, blob, revision, definition} fully qualified — see The workflow reference for the full grammar.

Response

Parameter	Type	Description
`execution`	object	The created execution object.

execution carries workflow, definition and snapshot, which a create response always sets to "created" — see Get Execution for the full shape. It also carries session_id — the session’s id, whichever of id or alias target.session named it by. The snapshot is taken after the access checks and before the record is written; if the copy fails, the request fails and no execution exists. See The execution snapshot. Execution identity. An execution must trace to a user: the request needs an identified caller, or the call returns 403. Interactive callers (JWT or API key) and scheduled invocations (via create_schedule) always carry one; the guard fails closed if that identity is ever missing.

Errors

Status	Error	Cause
400	`invalid_request_body`	`target` carries a key other than `session`, `target.session` is blank or over 64 characters, the body carries a field this page does not list, or `description` is over 256 characters — see Migrating from the removed shapes.
400	`invalid_workflow_reference`	`workflow` is malformed — wrong shape, or a combination the grammar refuses.
400	`invalid_definition_category`	`workflow.definition` is a definition id naming a `playground` definition the caller can reach. An alias never gets this error — alias lookups see only the `workflow` category.
403	`forbidden`	`target.session` does not resolve to a session in the route’s revision, or any failure to resolve or reach the `workflow` source — identical whatever the cause.
409	`session_not_open`	The session exists but is not open.

Example

{
  "command": "create_execution",
  "description": "Nightly data processing run",
  "target": {"session": "nightly-runs"},
  "workflow": {"definition": "data-process"},
  "input_data": [
    { "alias": "input_1", "value": { "type": "string" } }
  ]
}

{
  "status": "success",
  "execution": {
    "id": "exec_001",
    "session_id": "8d41b7e3-5c2a-4f90-a1b6-3e7d9c0f2a15",
    "status": "creating",
    "description": "Nightly data processing run",
    "workflow": {"definition": "data-process"},
    "definition": {"org_id": "org_001", "blob_id": "blob_001", "revision_id": "rev_001", "id": "def_001", "alias": "data-process"},
    "snapshot": "created"
  }
}

target.session names the session by its alias, nightly-runs; the execution’s session_id is the id that alias resolved to.

Overview

Workflow

Scheduler

ONNX

Create Execution

POST `/revisions/:id/data/command` (Command: `create_execution`)

Request Body

Response

Errors

Example

​POST /revisions/:id/data/command (Command: create_execution)

​Request Body

​Response

​Errors

​Example

POST `/revisions/:id/data/command` (Command: `create_execution`)

Request Body

Response

Errors

Example