Playbooks

Update a playbook

Updates any of name, description and definition. Only a change to definition archives a new version; a rename or a rewrite of the definition the playbook already holds leaves version where it is. A case keeps the version it was created on.

A new version is authored by the caller, checked as on create: 403 PLAYBOOK_EXECUTOR_FORBIDDEN for an executor it may not start, 409 PLAYBOOK_AUTHOR_UNAVAILABLE for a trigger or OAuth token.

patch/v1/projects/{project_id}/playbooks/{playbook_id}

Request

  • Base URL: https://api.naturali.ai
  • URL: https://api.naturali.ai/v1/projects/{project_id}/playbooks/{playbook_id}
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://api.naturali.ai/authorize, token URL https://api.naturali.ai/token, scopes: mcp:access)

Path parameters

playbook_idstring required
Example:pbk_V1StGXR8Z5jdHi6B

The playbook ID

Headers

If-Matchstring

The version the caller believes the resource holds, as an entity tag (3 or "3"). Equivalent to expected_version in the request body; * states no precondition beyond the resource existing. A mismatch is 409 VERSION_CONFLICT.

Request body

namestring

Human-readable name, unique per project

descriptionstring nullable

What the playbook is for

version_labelstring

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

expected_versioninteger nullable

The version the caller believes the resource holds. When the resource is at any other version the write is refused with 409 VERSION_CONFLICT and nothing is written; meta.current_version on that response names the version in force.

Omit it to write unconditionally. Omitting it does not make the write unordered: two writes that reach the server together are still serialized, and the one whose version was taken first is refused the same way. What the field adds is refusing a write whose author read the resource some time ago and has not seen what happened since.

The If-Match header carries the same precondition for a client that prefers the HTTP spelling. Sending both with different versions is 400 VALIDATION_FAILED.

Example request

{
  "definition": {
    "nodes": [
      {
        "id": "regime",
        "title": "Tax regime",
        "inputs": [
          {
            "name": "revenue",
            "schema": {
              "type": "number"
            },
            "source": {
              "node_id": "revenue",
              "field": "output.annual_revenue"
            }
          }
        ],
        "executor": {
          "id": "dcd_V1StGXR8Z5jdHi6B"
        },
        "transformations": [
          {
            "name": "proposal",
            "format": "pdf",
            "tool": "tool_V1StGXR8Z5jdHi6B"
          }
        ]
      }
    ]
  },
  "expected_version": 3
}

Response

Playbook updated

idstring
project_idstring
namestring
descriptionstring nullable
versioninteger

The definition's version. Bumped only by a write that changes definition.

created_atstring date-time
updated_atstring date-time

Example response

{
  "id": "pbk_V1StGXR8Z5jdHi6B",
  "project_id": "proj_V1StGXR8Z5jdHi6B",
  "name": "client-pricing",
  "version": 1,
  "definition": {
    "nodes": [
      {
        "id": "regime",
        "title": "Tax regime",
        "inputs": [
          {
            "name": "revenue",
            "schema": {
              "type": "number"
            },
            "source": {
              "node_id": "revenue",
              "field": "output.annual_revenue"
            }
          }
        ],
        "executor": {
          "id": "dcd_V1StGXR8Z5jdHi6B"
        },
        "transformations": [
          {
            "name": "proposal",
            "format": "pdf",
            "tool": "tool_V1StGXR8Z5jdHi6B"
          }
        ]
      }
    ]
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.