Skip to main content

Deciders Commands

See Deciders module docs for permissions and data model.

soat list-deciders​

List deciders

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

Usage​

soat list-deciders

Options​

--project-id​

Project ID (required if not using project key auth)

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

soat create-decider​

Create a decider

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

Usage​

soat create-decider --name <string> --questions <array<object>>

Options​

--project-id​

Project ID (required if not using project key auth)

  • Source: body
  • Required: no
  • Type: string
  • Example: proj_V1StGXR8Z5jdHi6B
--name​

Human-readable name, unique per project

  • Source: body
  • Required: yes
  • Type: string
  • Example: support-triage
--description​

—

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

A tool-less agent that answers

  • Source: body
  • Required: no
  • Type: string
  • Example: agent_V1StGXR8Z5jdHi6B
--tool-id​

An http or pipeline tool that answers

  • Source: body
  • Required: no
  • Type: string
  • Example: tool_V1StGXR8Z5jdHi6B
--questions​

The questions, in the order the model is shown them.

  • Source: body
  • Required: yes
  • Type: array<object>
  • Example: [\{"type":"choice","name":"department","instructions":"Which department should handle this complaint?","choices":[\{"value":"billing","description":"Payments, invoices and refunds."\},\{"value":"technical","description":"Problems using the product."\}]\},\{"type":"predicate","name":"needs_human","instructions":"Must a person read this before any automated reply?"\}]
--version-label​

Optional tag for version 1, e.g. initial

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

soat get-decider​

Get a decider

  • Method: GET
  • Path: /api/v1/deciders/{decider_id}

Usage​

soat get-decider

Options​

This command has no options.

soat update-decider​

Update a decider

  • Method: PATCH
  • Path: /api/v1/deciders/{decider_id}

Usage​

soat update-decider

Options​

--name​

—

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

—

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

Replaces the backend with this agent

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

Replaces the backend with this tool

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

The questions, in the order the model is shown them.

  • Source: body
  • Required: no
  • Type: array<object>
  • Example: [\{"type":"choice","name":"department","instructions":"Which department should handle this complaint?","choices":[\{"value":"billing","description":"Payments, invoices and refunds."\},\{"value":"technical","description":"Problems using the product."\}]\},\{"type":"predicate","name":"needs_human","instructions":"Must a person read this before any automated reply?"\}]
--version-label​

Optional tag for the version this write archives. Ignored when the write changes no question, since no version is archived.

  • Source: body
  • Required: no
  • Type: string
  • Example: add-account-option
--expected-version​

Refuses the write unless the decider is at this version.

  • Source: body
  • Required: no
  • Type: unknown

soat delete-decider​

Delete a decider

  • Method: DELETE
  • Path: /api/v1/deciders/{decider_id}

Usage​

soat delete-decider

Options​

This command has no options.

soat list-decider-versions​

List a decider's versions

  • Method: GET
  • Path: /api/v1/deciders/{decider_id}/versions

Usage​

soat list-decider-versions

Options​

This command has no options.

soat get-decider-version​

Fetch an archived decider version

  • Method: GET
  • Path: /api/v1/deciders/{decider_id}/versions/{version}

Usage​

soat get-decider-version

Options​

This command has no options.

soat restore-decider-version​

Restore an archived decider version

  • Method: POST
  • Path: /api/v1/deciders/{decider_id}/versions/{version}/restore

Usage​

soat restore-decider-version

Options​

--label​

Optional tag for the new version. Defaults to restored from vN.

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

soat create-decision​

Request a decision

  • Method: POST
  • Path: /api/v1/deciders/{decider_id}/decisions

Usage​

soat create-decision --input <unknown>

Options​

--input​

What is judged, not stored: a string; a list of user messages whose content is a string or input_text and input_image parts (an image as a base64 data URL); or any other JSON value, which an agent is shown as indented JSON. An array of objects carrying role is read as messages.

  • Source: body
  • Required: yes
  • Type: unknown
  • Example: I was charged twice for the same order.
--metadata​

Caller-owned annotations stored on the decision and returned on every read — typically the id of what was judged, since the input itself is not stored. Written once, with the decision. A non-object is rejected with 400 VALIDATION_FAILED and no decision is written.

  • Source: body
  • Required: no
  • Type: unknown
  • Example: \{"ticket_id":"ZD-48213"\}
--wait​

True evaluates before answering and returns the settled decision. False — the default — returns the queued decision at once. A tool call, builtin or MCP, always waits.

  • Source: body
  • Required: no
  • Type: boolean
  • Default: false
  • Example: true

soat create-inline-decision​

Request a decision with inline questions

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

Usage​

soat create-inline-decision --questions <array<object>> --input <unknown>

Options​

--project-id​

Project ID (required if not using project key auth)

  • Source: body
  • Required: no
  • Type: string
  • Example: proj_V1StGXR8Z5jdHi6B
--agent-id​

A tool-less agent that answers

  • Source: body
  • Required: no
  • Type: string
  • Example: agent_V1StGXR8Z5jdHi6B
--tool-id​

An http or pipeline tool that answers

  • Source: body
  • Required: no
  • Type: string
  • Example: tool_V1StGXR8Z5jdHi6B
--questions​

The questions, in the order the model is shown them.

  • Source: body
  • Required: yes
  • Type: array<object>
  • Example: [\{"type":"choice","name":"department","instructions":"Which department should handle this complaint?","choices":[\{"value":"billing","description":"Payments, invoices and refunds."\},\{"value":"technical","description":"Problems using the product."\}]\},\{"type":"predicate","name":"needs_human","instructions":"Must a person read this before any automated reply?"\}]
--input​

What is judged, not stored: a string; a list of user messages whose content is a string or input_text and input_image parts (an image as a base64 data URL); or any other JSON value, which an agent is shown as indented JSON. An array of objects carrying role is read as messages.

  • Source: body
  • Required: yes
  • Type: unknown
  • Example: I was charged twice for the same order.
--metadata​

Caller-owned annotations stored on the decision. A non-object is rejected with 400 VALIDATION_FAILED.

  • Source: body
  • Required: no
  • Type: unknown
  • Example: \{"ticket_id":"ZD-48213"\}
--wait​

True evaluates before answering and returns the settled decision. False — the default — returns the queued decision at once. A tool call, builtin or MCP, always waits.

  • Source: body
  • Required: no
  • Type: boolean
  • Default: false
  • Example: true

soat list-decisions​

List decisions

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

Usage​

soat list-decisions

Options​

--project-id​

Project ID (required if not using project key auth)

  • Source: query
  • Required: no
  • Type: string
  • Example: proj_V1StGXR8Z5jdHi6B
--decider-id​

Only decisions requested from this decider

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

Only decisions in these statuses. Repeat the parameter to OR values. A value outside the enum, empty string included, is a 400.

  • Source: query
  • Required: no
  • Type: array<enum("queued", "running", "completed", "failed")>

soat get-decision​

Get a decision

  • Method: GET
  • Path: /api/v1/decisions/{decision_id}

Usage​

soat get-decision --decision-id <string>

Options​

--decision-id​

The decision ID

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