Skip to main content

Tasks Commands

See Tasks module docs for permissions and data model.

soat list-tasks​

List tasks

  • Method: GET
  • Path: /api/v1/tasks

Usage​

soat list-tasks

Options​

--project-id​

—

  • Source: query
  • Required: no
  • Type: string
--workflow-id​

—

  • Source: query
  • Required: no
  • Type: string
--state​

—

  • Source: query
  • Required: no
  • Type: string
--status​

Filter by whether the task is open or closed. Repeat the parameter to OR values. A value outside the enum, empty string included, is a 400.

  • Source: query
  • Required: no
  • Type: array<enum("open", "closed")>
--automation-status​

Filter by the current state's dispatch status. Repeat the parameter to OR values. none selects the tasks whose automation_status is null — the ones that never entered a state with an automation. It is a value a task really holds, so it is a value of the filter too; the parameter's own absence already means "every task". A value outside the enum, empty string included, is a 400.

  • Source: query
  • Required: no
  • Type: array<enum("running", "completed", "failed", "unrouted", "paused", "none")>
  • Example: ["running"]
--assignee​

—

  • Source: query
  • Required: no
  • Type: string

soat create-task​

Create a task

  • Method: POST
  • Path: /api/v1/tasks

Usage​

soat create-task --workflow-id <string> --title <string>

Options​

--project-id​

—

  • Source: body
  • Required: no
  • Type: string
--workflow-id​

—

  • Source: body
  • Required: yes
  • Type: string
--title​

—

  • Source: body
  • Required: yes
  • Type: string
--payload​

—

  • Source: body
  • Required: no
  • Type: object
--assignee​

—

  • Source: body
  • Required: no
  • Type: string \| null
--idempotency-key​

The create's deduplication key, unique within the project and claimed for as long as the task it created exists. The same key with the same body returns that task as it is now (200) instead of creating a second one; with a different body it is 409 IDEMPOTENCY_KEY_REUSED. A create that fails claims no key. Equivalent to the Idempotency-Key header.

  • Source: body
  • Required: no
  • Type: string
--state​

Name of a declared workflow state to create the task in directly, instead of the workflow's initial state. Must name a state declared on the workflow, or the request is rejected with TASK_STATE_NOT_FOUND (400). Defaults to the initial state.

  • Source: body
  • Required: no
  • Type: string
--tool-context​

Key-value pairs forwarded as X-Soat-Context-<key> headers on every http, mcp and builtin tool call made by this task's automation dispatches — the agent generations a state's on_enter starts, and the agent nodes of any orchestration run it starts. The header name is X-Soat-Context- plus the key verbatim; no character is re-cased. Creation is the task's first move, so this is the bag the entry state's on_enter runs with. Each transition may replace it (see TransitionTaskRequest.tool_context). The reserved identity keys (session_id, actor_id, actor_external_id) are stripped in any casing and re-derived server-side, so a task-dispatched generation cannot forge them. A key outside the HTTP header-name grammar is rejected with INVALID_TOOL_CONTEXT_KEY (400). Write-only: the stored bag is never returned by any task read, and it is cleared when the task reaches a terminal state.

  • Source: body
  • Required: no
  • Type: object<string, string>
--metadata​

Caller-supplied key/value metadata attached to the task record for attribution — which of your own tenants the task belongs to, the ticket that raised it, the import batch that created it. Round-trips verbatim on every read of the task, the list included, and survives every transition (a transition supplies no metadata of its own). The bag is caller-owned and no key is reserved: everything the engine decides about a task (state, status, workflow_version, last_result, active_dispatch, the automation fields) is a field of its own and cannot be written from here. Prefer this over payload for anything that is not task data: payload is read by every guard as task.payload and may be written by the workflow's declared payload_writes, so a label parked there is neither invisible to the state machine nor safe from it. A non-object is rejected with 400 VALIDATION_FAILED and no task is created.

  • Source: body
  • Required: no
  • Type: unknown
  • Example: \{"tenant_account_id":"42","source":"zendesk"\}

soat get-task​

Get a task

  • Method: GET
  • Path: /api/v1/tasks/{task_id}

Usage​

soat get-task --task-id <string>

Options​

--task-id​

—

  • Source: path
  • Required: yes
  • Type: string

soat update-task​

Update a task

  • Method: PATCH
  • Path: /api/v1/tasks/{task_id}

Usage​

soat update-task --task-id <string>

Options​

--task-id​

—

  • Source: path
  • Required: yes
  • Type: string
--title​

—

  • Source: body
  • Required: no
  • Type: string
--payload​

Partial payload, shallow-merged over the existing payload. Omitted keys are preserved; provided keys overwrite. The merged result must satisfy the workflow's payload_schema.

  • Source: body
  • Required: no
  • Type: object
--assignee​

—

  • Source: body
  • Required: no
  • Type: string \| null

soat delete-task​

Delete a task

  • Method: DELETE
  • Path: /api/v1/tasks/{task_id}

Usage​

soat delete-task --task-id <string>

Options​

--task-id​

—

  • Source: path
  • Required: yes
  • Type: string

soat list-task-transitions​

List a task's transitions

  • Method: GET
  • Path: /api/v1/tasks/{task_id}/transitions

Usage​

soat list-task-transitions --task-id <string>

Options​

--task-id​

The task whose transitions are listed.

  • Source: path
  • Required: yes
  • Type: string

soat transition-task​

Transition a task

  • Method: POST
  • Path: /api/v1/tasks/{task_id}/transitions

Usage​

soat transition-task --task-id <string> --transition <string>

Options​

--task-id​

—

  • Source: path
  • Required: yes
  • Type: string
--transition​

—

  • Source: body
  • Required: yes
  • Type: string
--note​

—

  • Source: body
  • Required: no
  • Type: string \| null
--payload​

Keys shallow-merged over the task's payload under the transition's lock, before the guard reads it, exactly as PATCH merges them; the result must satisfy the payload schema of the version the task is pinned to (TASK_PAYLOAD_INVALID). A refused move writes none of it. On a requires_approval transition the payload is held with the gate and merged when the approval fires the move, so a rejected or expired gate writes nothing.

  • Source: body
  • Required: no
  • Type: object
--idempotency-key​

The move's deduplication key, unique within the task and claimed for as long as the task exists. The same key with the same body replays the task as it is now instead of moving it again, whether the move applied or parked an approval; with a different body it is 409 IDEMPOTENCY_KEY_REUSED. Equivalent to the Idempotency-Key header.

  • Source: body
  • Required: no
  • Type: string
--tool-context​

Caller context for the automation dispatches the task makes from here on, forwarded as X-Soat-Context-<key> headers on their tool calls. Supplying it replaces the task's stored bag wholesale; omitting it keeps the current one, so the context follows whoever last moved the task and survives every move that does not speak about it — including an approval gate, a retry, and an automation hop. Send an empty object to clear it without closing the task. The reserved identity keys (session_id, actor_id, actor_external_id) are stripped in any casing and re-derived server-side. A key outside the HTTP header-name grammar is rejected with INVALID_TOOL_CONTEXT_KEY (400). Write-only: never returned by a task read, and cleared when the transition closes the task.

  • Source: body
  • Required: no
  • Type: object<string, string>

soat migrate-task​

Migrate a task to a newer workflow version

  • Method: POST
  • Path: /api/v1/tasks/{task_id}/migrate

Usage​

soat migrate-task --task-id <string> --to-version <integer>

Options​

--task-id​

The task to migrate.

  • Source: path
  • Required: yes
  • Type: string
--to-version​

The workflow version to move the task onto; newer than its current one.

  • Source: body
  • Required: yes
  • Type: integer
--state-map​

Current state name to a state the target version declares. Required only for a state the target lacks; an entry for a state both declare overrides the identity mapping.

  • Source: body
  • Required: no
  • Type: object<string, string>

soat pause-task​

Pause a task

  • Method: POST
  • Path: /api/v1/tasks/{task_id}/pause

Usage​

soat pause-task --task-id <string>

Options​

--task-id​

—

  • Source: path
  • Required: yes
  • Type: string
--reason​

Why the task is being paused, surfaced on pause_reason.

  • Source: body
  • Required: no
  • Type: string

soat resume-task​

Resume a task

  • Method: POST
  • Path: /api/v1/tasks/{task_id}/resume

Usage​

soat resume-task --task-id <string>

Options​

--task-id​

—

  • Source: path
  • Required: yes
  • Type: string

soat get-task-history​

Get task history

  • Method: GET
  • Path: /api/v1/tasks/{task_id}/history

Usage​

soat get-task-history --task-id <string>

Options​

--task-id​

—

  • Source: path
  • Required: yes
  • Type: string