Playbooks

Create a playbook

Creates a playbook at version 1. The definition is refused with 400 PLAYBOOK_VALIDATION_FAILED when it holds a duplicate node or input, an input reading a missing node or field, an execute node without an executor or another kind with one, transformations on a non-final node, or a cycle; meta.problems lists every one. A duplicate name in the project is 409 NAME_CONFLICT.

The caller becomes the version's author, whom its executors run as, so it must be allowed to start every executor the definition names (403 PLAYBOOK_EXECUTOR_FORBIDDEN). A definition with executors written with a trigger or OAuth token is 409 PLAYBOOK_AUTHOR_UNAVAILABLE: those carry their boundary in the token, so no run can act as them.

post/v1/projects/{project_id}/playbooks

Request

  • Base URL: https://api.naturali.ai
  • URL: https://api.naturali.ai/v1/projects/{project_id}/playbooks
  • 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)

Request body

namestring required

Human-readable name, unique per project

descriptionstring nullable

What the playbook is for

version_labelstring

Optional tag for version 1, e.g. initial

Example request

{
  "name": "client-pricing",
  "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"
          }
        ]
      }
    ]
  },
  "version_label": "initial"
}

Response

Playbook created

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.