# Orchestrations Commands > See [Orchestrations module docs](../../modules/orchestrations) for permissions and data model. # Orchestrations Commands See [Orchestrations module docs](../../modules/orchestrations) for permissions and data model. ### `soat create-orchestration` Create an orchestration - Method: `POST` - Path: `/api/v1/orchestrations` #### Usage ```bash soat create-orchestration --name --nodes > --edges > ``` #### Options ##### `--project-id` Public ID of the project. Optional when authenticating with a project-scoped API key, which defaults to the key's project; required otherwise. - Source: `body` - Required: no - Type: `string` ##### `--name` Human-readable name. - Source: `body` - Required: yes - Type: `string` ##### `--description` — - Source: `body` - Required: no - Type: `string \| null` ##### `--nodes` — - Source: `body` - Required: yes - Type: `array` ##### `--edges` — - Source: `body` - Required: yes - Type: `array` ##### `--state-schema` — - Source: `body` - Required: no - Type: `object` ##### `--input-schema` — - Source: `body` - Required: no - Type: `object` ##### `--version-label` Optional tag for the version this create archives, e.g. `initial`. - Source: `body` - Required: no - Type: `string` - Example: `initial` ### `soat list-orchestrations` List orchestrations - Method: `GET` - Path: `/api/v1/orchestrations` #### Usage ```bash soat list-orchestrations ``` #### Options ##### `--project-id` Filter by project public ID - Source: `query` - Required: no - Type: `string` ##### `--limit` Maximum number of results to return - Source: `query` - Required: no - Type: `integer` - Default: `50` ##### `--offset` Number of results to skip - Source: `query` - Required: no - Type: `integer` - Default: `0` ### `soat validate-orchestration` Validate an orchestration graph - Method: `POST` - Path: `/api/v1/orchestrations/validate` #### Usage ```bash soat validate-orchestration ``` #### Options ##### `--nodes` — - Source: `body` - Required: no - Type: `array` ##### `--edges` — - Source: `body` - Required: no - Type: `array` ##### `--input-schema` Optional JSON Schema for run inputs; its top-level properties seed state. - Source: `body` - Required: no - Type: `object` ### `soat get-queue-stats` Get orchestration queue stats - Method: `GET` - Path: `/api/v1/orchestrations/queue/stats` #### Usage ```bash soat get-queue-stats ``` #### Options This command has no options. ### `soat get-orchestration` Get an orchestration - Method: `GET` - Path: `/api/v1/orchestrations/{orchestration_id}` #### Usage ```bash soat get-orchestration ``` #### Options This command has no options. ### `soat update-orchestration` Update an orchestration - Method: `PATCH` - Path: `/api/v1/orchestrations/{orchestration_id}` #### Usage ```bash soat update-orchestration ``` #### Options ##### `--name` — - Source: `body` - Required: no - Type: `string` ##### `--description` — - Source: `body` - Required: no - Type: `string \| null` ##### `--nodes` — - Source: `body` - Required: no - Type: `array` ##### `--edges` — - Source: `body` - Required: no - Type: `array` ##### `--state-schema` — - Source: `body` - Required: no - Type: `object` ##### `--input-schema` — - Source: `body` - Required: no - Type: `object` ##### `--version-label` Optional tag for the version this write archives, e.g. `pre-rewire`. Ignored when the write changes no graph field, since no version is archived. - Source: `body` - Required: no - Type: `string` - Example: `pre-rewire` ### `soat delete-orchestration` Delete an orchestration - Method: `DELETE` - Path: `/api/v1/orchestrations/{orchestration_id}` #### Usage ```bash soat delete-orchestration ``` #### Options This command has no options. ### `soat list-orchestration-versions` List an orchestration's graph versions - Method: `GET` - Path: `/api/v1/orchestrations/{orchestration_id}/versions` #### Usage ```bash soat list-orchestration-versions ``` #### Options ##### `--limit` Maximum number of results to return - Source: `query` - Required: no - Type: `integer` - Default: `50` ##### `--offset` Number of results to skip - Source: `query` - Required: no - Type: `integer` - Default: `0` ### `soat get-orchestration-version` Fetch an archived orchestration version - Method: `GET` - Path: `/api/v1/orchestrations/{orchestration_id}/versions/{version}` #### Usage ```bash soat get-orchestration-version --version ``` #### Options ##### `--version` The archived version number - Source: `path` - Required: yes - Type: `integer` ### `soat restore-orchestration-version` Restore an archived orchestration graph - Method: `POST` - Path: `/api/v1/orchestrations/{orchestration_id}/versions/{version}/restore` #### Usage ```bash soat restore-orchestration-version --version ``` #### Options ##### `--version` The archived version number - Source: `path` - Required: yes - Type: `integer` ##### `--label` Optional tag for the version the restore creates. Defaults to `restored from v`. - Source: `body` - Required: no - Type: `string` - Example: `rollback to pre-incident graph` ### `soat start-orchestration-run` Start an orchestration run - Method: `POST` - Path: `/api/v1/orchestration-runs` #### Usage ```bash soat start-orchestration-run --orchestration-id ``` #### Options ##### `--orchestration-id` Orchestration to run (orch_...). - Source: `body` - Required: yes - Type: `string` - Example: `orch_V1StGXR8Z5jdHi6B` ##### `--input` Initial state for the run (merged with orchestration defaults). - Source: `body` - Required: no - Type: `object` ##### `--tool-context` Key-value pairs forwarded as `X-Soat-Context-` headers on every `http`, `mcp` and `builtin` tool call made by an agent node of this run — including the agents of any child run a `loop` or `sub_orchestration` node starts. The header name is `X-Soat-Context-` plus the key verbatim; no character is re-cased. The bag is stored on the run and re-read on every step, so it survives an `awaiting_input` pause, a `sleeping` wait, a background worker drive and a crash redrive. A key that is not a valid HTTP header name, or two keys that map to the same header, are rejected with `400 INVALID_TOOL_CONTEXT_KEY` and no run is created. The reserved identity keys (`session_id`, `actor_id`, `actor_external_id`) are stripped at generation time — a caller cannot address them from here. - Source: `body` - Required: no - Type: `object` - Example: `\{"ocaToken":"eyJhbGciOiJIUzI1NiJ9.abc"\}` ##### `--metadata` Caller-supplied key/value metadata attached to the run record for per-run attribution (e.g. which of your own tenants this run belongs to, or the dispatch batch that started it). Round-trips verbatim on every read of the run, on the list as well as the single read. The bag is caller-owned and no key is reserved: server-owned state (status, the pinned orchestration version, the trace, usage, artifacts, the run's own `input` and accumulated `state`) lives in its own top-level field and cannot be written from here. It is **not** merged into run state: no graph node sees it, and an `input_schema` never has to tolerate it — which is what makes it the place for an infrastructural label, rather than `input`. Keys are never transformed. It is not inherited by the child runs a `loop` or `sub_orchestration` node starts; each child carries whatever the graph gives it, which today is nothing. - Source: `body` - Required: no - Type: `object` - Example: `\{"tenant_account_id":"42","dispatch_batch":"nightly-2026-08-25"\}` ##### `--wait` When true, block until the run reaches a terminal (succeeded/failed) or awaiting_input state and return the settled run. When false (default), return immediately with status "queued" and execute the run in the background. - Source: `body` - Required: no - Type: `boolean` - Default: `false` ### `soat list-orchestration-runs` List orchestration runs - Method: `GET` - Path: `/api/v1/orchestration-runs` #### Usage ```bash soat list-orchestration-runs ``` #### Options ##### `--orchestration-id` Filter by orchestration public ID (orch_...) - Source: `query` - Required: no - Type: `string` ##### `--parent-orchestration-run-id` Filter to the runs one specific parent run's `loop` / `sub_orchestration` nodes started (run_...). This is how a caller holding a parent names the individual children behind its `usage`. - Source: `query` - Required: no - Type: `string` ##### `--nested` Filter by whether the run was started by another run. `false` returns only the runs a caller started (no parent), which is the set to sum `usage` over; `true` returns only the runs a `loop` / `sub_orchestration` node started, across every parent. Omit to return both. Contradicting `parent_orchestration_run_id` with `nested=false` is a `400`; any value other than `true` or `false` is a `400`. - Source: `query` - Required: no - Type: `boolean` ##### `--limit` Maximum number of results to return - Source: `query` - Required: no - Type: `integer` - Default: `50` ##### `--offset` Number of results to skip - Source: `query` - Required: no - Type: `integer` - Default: `0` ### `soat cancel-orchestration-run` Cancel an orchestration run - Method: `POST` - Path: `/api/v1/orchestration-runs/{orchestration_run_id}/cancel` #### Usage ```bash soat cancel-orchestration-run ``` #### Options This command has no options. ### `soat submit-human-input` Submit human input - Method: `POST` - Path: `/api/v1/orchestration-runs/{orchestration_run_id}/human-input` #### Usage ```bash soat submit-human-input --node-id ``` #### Options ##### `--node-id` ID of the human node to satisfy. - Source: `body` - Required: yes - Type: `string` ##### `--output` Output/response provided by the human reviewer. - Source: `body` - Required: no - Type: `object` ### `soat resume-orchestration-run` Resume an orchestration run - Method: `POST` - Path: `/api/v1/orchestration-runs/{orchestration_run_id}/resume` #### Usage ```bash soat resume-orchestration-run ``` #### Options This command has no options. ### `soat get-orchestration-run` Get an orchestration run - Method: `GET` - Path: `/api/v1/orchestration-runs/{orchestration_run_id}` #### Usage ```bash soat get-orchestration-run ``` #### Options This command has no options.