Playbooks API

Create, list, update, and version playbooks.

Playbooks are version-controlled workflow templates. Each playbook has one or more versions, and only one version can be approved (active) at a time. All endpoints require authentication.

Endpoints

GET /playbooks — List playbooks
GET /playbooks/:id — Get a playbook
POST /playbooks — Create a playbook
PATCH /playbooks/:id — Update metadata
DELETE /playbooks/:id — Archive a playbook
POST /playbooks/:id/versions — Create a version
PATCH /versions/:id/approve — Approve a version

All paths are relative to /api/v1/workspaces/{workspaceId}

List playbooks

GET /playbooks

Returns a paginated list of playbooks in the workspace.

Query parameters

Parameter	Type	Description
`status`	string	Filter by version status: `draft`, `approved`, `deprecated`
`function_area`	string	Filter by function area (e.g. "Marketing")
`owner`	string	Filter by owner user ID
`sort`	string	`updated_at` (default), `title`, `created_at`
`order`	string	`desc` (default), `asc`
`page`	number	Page number (default: 1)
`limit`	number	Results per page (default: 50)

curl "https://patina.so/api/v1/workspaces/WORKSPACE_ID/playbooks?status=approved&limit=10" \
  -H "Authorization: Bearer pk_YOUR_API_KEY"

{
  "playbooks": [
    {
      "id": "pb_abc123...",
      "title": "Blog Post Workflow",
      "slug": "blog-post-workflow",
      "summary": "Step-by-step process for writing blog posts",
      "functionArea": "Marketing",
      "visibility": "workspace_private",
      "latestVersion": {
        "id": "ver_xyz...",
        "versionNumber": 3,
        "status": "approved"
      },
      "createdAt": "2025-01-15T10:00:00.000Z",
      "updatedAt": "2025-03-10T14:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 42
  }
}

Get a playbook

GET /playbooks/:playbookId

Returns the full playbook including its versions, linked context nodes, and tags.

curl https://patina.so/api/v1/workspaces/WORKSPACE_ID/playbooks/PLAYBOOK_ID \
  -H "Authorization: Bearer pk_YOUR_API_KEY"

Create a playbook

POST /playbooks

Creates a new playbook with an initial draft version. Requires editor role or above.

Request body

Field	Type	Required	Description
`title`	string	Yes	Playbook name
`version`	object	Yes	Initial version with `content` (object, required) and `changeNote` (string, optional)
`slug`	string	No	URL-safe identifier. Auto-generated from title if omitted.
`summary`	string	No	Brief description
`description`	string	No	Longer description (supports markdown)
`functionArea`	string	No	Category label (e.g. "Marketing", "Engineering")
`visibility`	string	No	`workspace_private` (default) or `parent_readonly`

curl -X POST https://patina.so/api/v1/workspaces/WORKSPACE_ID/playbooks \
  -H "Authorization: Bearer pk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Customer Onboarding Email",
    "summary": "Template for welcoming new customers",
    "functionArea": "Customer Success",
    "version": {
      "content": {
        "instructions": "Write a warm onboarding email that introduces the key features..."
      },
      "changeNote": "Initial draft"
    }
  }'

Update a playbook

PATCH /playbooks/:playbookId

Updates playbook metadata. Does not create a new version — use the versions endpoint for that. Requires editor role.

curl -X PATCH https://patina.so/api/v1/workspaces/WORKSPACE_ID/playbooks/PLAYBOOK_ID \
  -H "Authorization: Bearer pk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Customer Onboarding Email v2",
    "summary": "Updated template with product tour link"
  }'

Archive a playbook

DELETE /playbooks/:playbookId

Soft-deletes the playbook by setting archivedAt. The playbook is hidden from list results but not permanently removed. Requires owner role.

curl -X DELETE https://patina.so/api/v1/workspaces/WORKSPACE_ID/playbooks/PLAYBOOK_ID \
  -H "Authorization: Bearer pk_YOUR_API_KEY"

Create a version

POST /playbooks/:playbookId/versions

Creates a new draft version of a playbook. The previous approved version remains active until the new version is explicitly approved.

Request body

Field	Type	Required	Description
`content`	object	Yes	Version content (typically includes `instructions`)
`changeNote`	string	No	Description of what changed

curl -X POST https://patina.so/api/v1/workspaces/WORKSPACE_ID/playbooks/PLAYBOOK_ID/versions \
  -H "Authorization: Bearer pk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": {
      "instructions": "Updated instructions with new brand voice..."
    },
    "changeNote": "Aligned with Q2 brand refresh"
  }'

Approve a version

PATCH /playbooks/:playbookId/versions/:versionId/approve

Marks a draft version as approved. Any previously approved version on the same playbook is automatically deprecated. Requires editor role.

curl -X PATCH https://patina.so/api/v1/workspaces/WORKSPACE_ID/playbooks/PLAYBOOK_ID/versions/VERSION_ID/approve \
  -H "Authorization: Bearer pk_YOUR_API_KEY"

Next: Context API