---
title: "List a playbook's versions"
method: GET
path: "/v1/projects/{project_id}/playbooks/{playbook_id}/versions"
tags: ["Playbooks"]
---

# List a playbook's versions

`GET /v1/projects/{project_id}/playbooks/{playbook_id}/versions`

## Request

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

Returns the playbook's archived definitions, newest first. A version is written on create and on every write that changes `definition`.

## Path parameters

- `playbook_id` string, required

## Query parameters

- `limit` integer
- `offset` integer

## Response `200`

List of playbook versions, newest first

- object
  - `data` PlaybookVersion[], required
    - `id` string
    - `playbook_id` string
    - `version` integer
    - `config` object: The versioned surface as it stood at this version.
      - `definition` PlaybookDefinition
        - `nodes` PlaybookNode[], required
          - `id` string, required: Stable across versions: a case's values carry over by ID. Letters, digits and underscores, starting with a letter or underscore.
          - `title` string, required
          - `description` string
          - `kind` 'collect' | 'execute' | 'confirm', required: `collect` outputs its inputs, `execute` runs its executor, `confirm` waits for a person to confirm its inputs.
          - `final` boolean: A goal of the playbook; only a final node carries transformations
          - `inputs` PlaybookInput[], required
            - `name` string, required: Letters, digits and underscores, starting with a letter or underscore
            - `schema` object, required: The JSON Schema a value must satisfy
            - `required` boolean, required: The node cannot run until a required input is set
            - `description` string: What to ask for; shown with the input when it is missing
            - `source` union, required: `manual` for an input a person or an integration writes, or the field of an earlier node it reads: `output[.path]`, or `input.<name>[.path]`. Sources are the playbook's edges.
              - …
          - `executor` PlaybookExecutor
            - `type` 'agent' | 'tool' | 'decider' | 'workflow' | 'orchestration', required
            - `id` string, required: The ID of the agent, tool, decider, workflow or orchestration
            - `input` object: JSON Logic over the node's inputs, as an orchestration's `input_mapping`: each key is a field of the executor's input. Absent, the executor receives the node's input values as they are.
          - `transformations` PlaybookTransformation[]
            - `name` string, required
            - `format` 'csv' | 'docx' | 'html' | 'jpg' | 'json' | 'md' | 'pdf' | 'png' | 'pptx' | 'txt' | 'xlsx', required: The file's format; the tool must answer its content type: `application/pdf` for `pdf`, the Office Open XML types for `docx`, `xlsx` and `pptx`, `text/csv`, `text/html`, `text/markdown`, `text/plain`, `application/json`, `image/png` and `image/jpeg` for `jpg`
            - `tool` string, required: The tool that renders the final node's output as a file, answering with `execute.response_mode: base64`
    - `label` string, nullable
    - `created_by_principal_type` 'user' | 'api_key' | 'agent' | 'automation' | 'approval' | 'system': What kind of principal acted. `user` and `api_key` are authenticated callers, and the id is the user's (`user_…`) or the key's own (`key_…`), so a record names which key acted rather than its owner. `agent` is an agent writing under its own identity (`agent_…`). `automation` is the task engine acting on a dispatch outcome and `approval` an approval resolution; neither carries an id. `system` is the platform itself, with an id naming the mechanism (`retention_sweep`, `zero_retention`).
    - `created_by_principal_id` string, nullable: Public id of that principal: the user (`user_…`), or for API key auth the key itself (`key_…`), so the record names which key acted.
    - `created_at` string, date-time
  - `total` integer, required
  - `limit` integer, required
  - `offset` integer, required

## Other responses

- `401`: Unauthorized
- `404`: Playbook not found

---

[API](https://skmtc.dev/naturali/apis/naturali-ai-api.md) · [All operations](https://skmtc.dev/naturali/apis/naturali-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/naturali/apis/naturali-ai-api/revisions/e4905b78f422?raw)