Skip to main content

Approvals Commands

See Approvals module docs for permissions and data model.

soat list-approvals​

List approval items

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

Usage​

soat list-approvals

Options​

--project-id​

Project ID (required if not using project key auth)

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

Filter by lifecycle status. Repeat the parameter to OR values. A value outside the enum, empty string included, is a 400.

  • Source: query
  • Required: no
  • Type: array<enum("pending", "approved", "rejected", "expired")>
--origin​

Filter by producer origin

  • Source: query
  • Required: no
  • Type: enum("node", "tool_call", "task_transition")
--expires-from​

Only items whose expires_at is at or after this timestamp (ISO 8601)

  • Source: query
  • Required: no
  • Type: string
--expires-to​

Only items whose expires_at is at or before this timestamp (ISO 8601)

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

soat list-approval-recurrences​

List recurring approval groups

  • Method: GET
  • Path: /api/v1/approvals/recurrences

Usage​

soat list-approval-recurrences

Options​

--project-id​

Project ID (required if not using project key auth)

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

Lifecycle statuses the groups are built from (default rejected). Repeat the parameter to OR values. A value outside the enum, empty string included, is a 400.

  • Source: query
  • Required: no
  • Type: array<enum("pending", "approved", "rejected", "expired")>
  • Default: ["rejected"]
--min-count​

Minimum items in a group for it to be returned

  • Source: query
  • Required: no
  • Type: integer
  • Default: 2

soat get-approval​

Get an approval item

  • Method: GET
  • Path: /api/v1/approvals/{approval_id}

Usage​

soat get-approval

Options​

This command has no options.

soat approve-approval​

Approve an approval item

  • Method: POST
  • Path: /api/v1/approvals/{approval_id}/approve

Usage​

soat approve-approval

Options​

--arguments​

Edited arguments to execute instead of the proposed ones. Editing composes a new call, so it additionally requires permission to make that call: tools:CallTool on the tool, and for a builtin proposal the action's own IAM action. Refused on an item with no proposed_action.

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

Key-value pairs forwarded as context headers on the approved action and on every tool call of the continuation turn, as on a generation's tool_context. Never stored on the item: supply it on the approve call itself, for a tool that authorizes with a credential minted at decision time. The server-pinned identity keys (session_id, actor_id, actor_external_id) are dropped. An invalid or colliding key is rejected with 400 INVALID_TOOL_CONTEXT_KEY and nothing is resolved.

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

soat reject-approval​

Reject an approval item

  • Method: POST
  • Path: /api/v1/approvals/{approval_id}/reject

Usage​

soat reject-approval --reason <string>

Options​

--reason​

Why the item is being rejected (required)

  • Source: body
  • Required: yes
  • Type: string
  • Example: Amount exceeds the approved monthly budget.