Skip to main content

Playbooks Commands

See Playbooks module docs for permissions and data model.

soat list-playbooks​

List playbooks

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

Usage​

soat list-playbooks

Options​

--project-id​

Project ID (required if not using project key auth)

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

soat create-playbook​

Create a playbook

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

Usage​

soat create-playbook --name <string> --definition <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: client-pricing
--description​

What the playbook is for

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

The nodes and how their inputs are sourced

  • Source: body
  • Required: yes
  • Type: object
--version-label​

Optional tag for version 1, e.g. initial

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

soat validate-playbook​

Validate a playbook definition

  • Method: POST
  • Path: /api/v1/playbooks/validate

Usage​

soat validate-playbook --definition <object>

Options​

--definition​

The definition to check

  • Source: body
  • Required: yes
  • Type: object

soat get-playbook​

Get a playbook

  • Method: GET
  • Path: /api/v1/playbooks/{playbook_id}

Usage​

soat get-playbook

Options​

This command has no options.

soat update-playbook​

Update a playbook

  • Method: PATCH
  • Path: /api/v1/playbooks/{playbook_id}

Usage​

soat update-playbook

Options​

--name​

Human-readable name, unique per project

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

What the playbook is for

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

Replaces the whole definition; a change archives a new version

  • Source: body
  • Required: no
  • Type: object
--version-label​

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

  • Source: body
  • Required: no
  • Type: string
--expected-version​

Refuses the write unless the playbook is at this version.

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

soat delete-playbook​

Delete a playbook

  • Method: DELETE
  • Path: /api/v1/playbooks/{playbook_id}

Usage​

soat delete-playbook

Options​

This command has no options.

soat list-playbook-versions​

List a playbook's versions

  • Method: GET
  • Path: /api/v1/playbooks/{playbook_id}/versions

Usage​

soat list-playbook-versions

Options​

This command has no options.

soat get-playbook-version​

Fetch an archived playbook version

  • Method: GET
  • Path: /api/v1/playbooks/{playbook_id}/versions/{version}

Usage​

soat get-playbook-version

Options​

This command has no options.

soat restore-playbook-version​

Restore an archived playbook version

  • Method: POST
  • Path: /api/v1/playbooks/{playbook_id}/versions/{version}/restore

Usage​

soat restore-playbook-version

Options​

--label​

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

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

soat create-playbook-case​

Create a case

  • Method: POST
  • Path: /api/v1/playbooks/{playbook_id}/cases

Usage​

soat create-playbook-case --subject <string>

Options​

--subject​

Who or what the case is about, as you name it

  • Source: body
  • Required: yes
  • Type: string
  • Example: ACME Ltda (CNPJ 12.345.678/0001-90)

soat list-playbook-cases​

List playbook cases

  • Method: GET
  • Path: /api/v1/playbook-cases

Usage​

soat list-playbook-cases

Options​

--project-id​

Project ID (required if not using project key auth)

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

Only the cases of this playbook

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

Only the cases in these automation 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("idle", "running", "waiting", "paused")>

soat get-playbook-case​

Get a case

  • Method: GET
  • Path: /api/v1/playbook-cases/{case_id}

Usage​

soat get-playbook-case

Options​

This command has no options.

soat delete-playbook-case​

Delete a case

  • Method: DELETE
  • Path: /api/v1/playbook-cases/{case_id}

Usage​

soat delete-playbook-case

Options​

This command has no options.

soat write-playbook-case-inputs​

Write a case's inputs

  • Method: POST
  • Path: /api/v1/playbook-cases/{case_id}/inputs

Usage​

soat write-playbook-case-inputs --inputs <array<object>>

Options​

--inputs​

The writes, applied all or none

  • Source: body
  • Required: yes
  • Type: array<object>
--wait​

Answer once every execution the write queued, and every one those queue in turn, has settled or parked, instead of right away

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

soat get-playbook-case-missing​

List what a node still needs

  • Method: GET
  • Path: /api/v1/playbook-cases/{case_id}/missing

Usage​

soat get-playbook-case-missing --node-id <string>

Options​

--node-id​

The ID of the node to reach, usually a final node

  • Source: query
  • Required: yes
  • Type: string
  • Example: pricing

soat list-playbook-case-entries​

List a case's entries

  • Method: GET
  • Path: /api/v1/playbook-cases/{case_id}/entries

Usage​

soat list-playbook-case-entries

Options​

--node-id​

Only the entries of this node

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

soat run-playbook-case-node​

Run a node of a case

  • Method: POST
  • Path: /api/v1/playbook-cases/{case_id}/nodes/{node}/run

Usage​

soat run-playbook-case-node

Options​

--wait​

Answer once the executor settles or parks instead of right away

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

soat list-playbook-case-executions​

List a case's executions

  • Method: GET
  • Path: /api/v1/playbook-cases/{case_id}/executions

Usage​

soat list-playbook-case-executions

Options​

--node-id​

Only the executions of this node

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

soat get-playbook-case-execution​

Get an execution

  • Method: GET
  • Path: /api/v1/playbook-cases/{case_id}/executions/{execution_id}

Usage​

soat get-playbook-case-execution

Options​

This command has no options.

soat export-playbook-case-node​

Export a final node

  • Method: POST
  • Path: /api/v1/playbook-cases/{case_id}/nodes/{node}/exports

Usage​

soat export-playbook-case-node

Options​

--transformations​

The names of the transformations to render; every one the node declares when omitted

  • Source: body
  • Required: no
  • Type: array<string>
--revision​

The output or confirmation of the node to render; its current output when omitted

  • Source: body
  • Required: no
  • Type: integer
--wait​

Answer once every export settles instead of right away. A tool call, builtin or MCP, always waits.

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

soat list-playbook-case-exports​

List a case's exports

  • Method: GET
  • Path: /api/v1/playbook-cases/{case_id}/exports

Usage​

soat list-playbook-case-exports

Options​

--node-id​

Only the exports of this node

  • Source: query
  • Required: no
  • Type: string
  • Example: pricing
--transformation​

Only the exports of this transformation

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

soat get-playbook-case-export​

Get an export

  • Method: GET
  • Path: /api/v1/playbook-cases/{case_id}/exports/{export_id}

Usage​

soat get-playbook-case-export

Options​

This command has no options.

soat upgrade-playbook-case​

Upgrade a case

  • Method: POST
  • Path: /api/v1/playbook-cases/{case_id}/upgrade

Usage​

soat upgrade-playbook-case

Options​

--version​

The version to move the case to; the playbook's current one when omitted

  • Source: body
  • Required: no
  • Type: integer
  • Example: 2
--wait​

Answer once every execution the write queued, and every one those queue in turn, has settled or parked, instead of right away

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

soat list-playbook-case-upgrades​

List a case's upgrades

  • Method: GET
  • Path: /api/v1/playbook-cases/{case_id}/upgrades

Usage​

soat list-playbook-case-upgrades

Options​

This command has no options.

soat pause-playbook-case​

Pause a case

  • Method: POST
  • Path: /api/v1/playbook-cases/{case_id}/pause

Usage​

soat pause-playbook-case

Options​

This command has no options.

soat resume-playbook-case​

Resume a case

  • Method: POST
  • Path: /api/v1/playbook-cases/{case_id}/resume

Usage​

soat resume-playbook-case

Options​

This command has no options.

soat confirm-playbook-case-node​

Confirm a node of a case

  • Method: POST
  • Path: /api/v1/playbook-cases/{case_id}/nodes/{node}/confirmation

Usage​

soat confirm-playbook-case-node --decision <enum("approve", "reject")> --expected-revisions <object<string, integer | null>>

Options​

--decision​

Whether the node's inputs, as read, are approved

  • Source: body
  • Required: yes
  • Type: enum("approve", "reject")
--reason​

Why the inputs were rejected; required on a rejection

  • Source: body
  • Required: no
  • Type: string
  • Example: The revenue does not match the filed statement
--expected-revisions​

Each of the node's inputs, by name, mapped to the revision read, or null for one read as unset

  • Source: body
  • Required: yes
  • Type: object<string, integer \| null>
  • Example: \{"revenue":3\}
--wait​

Answer once every execution the write queued, and every one those queue in turn, has settled or parked, instead of right away

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