Playbooks API

Playbooks contain conventions — team standards that guide AI behavior. The API supports convention CRUD, subscriptions, and AI-powered extraction.

Playbook sync (CLI)

For detected stacks

GET /:org_id/playbooks/for_stacks

Returns playbooks matching the project's detected framework stack. Used by the CLI to suggest playbooks.

For file sync

GET /:org_id/playbooks/for_sync

Returns formatted playbook content for writing to .claude/playbooks.md. Used during resource sync.

Subscriptions

Org-scoped: /:org_id/playbook_subscriptions.

List subscriptions

GET /:org_id/playbook_subscriptions

Available playbooks

GET /:org_id/playbook_subscriptions/available

Returns platform playbooks the organization hasn't subscribed to yet.

POST /:org_id/playbook_subscriptions
Content-Type: application/json

{
  "playbook_id": "playbook_abc123"
}

Unsubscribe

DELETE /:org_id/playbook_subscriptions/:id

Enable/disable

POST /:org_id/playbook_subscriptions/:id/enable
POST /:org_id/playbook_subscriptions/:id/disable

Conventions

Nested under playbooks: /playbooks/:playbook_id/conventions.

List conventions

GET /api/v1/playbooks/:playbook_id/conventions

Effective conventions

GET /api/v1/playbooks/:playbook_id/conventions/effective

Returns conventions with overrides applied.

Create convention

POST /api/v1/playbooks/:playbook_id/conventions
Content-Type: application/json

{
  "category": "testing",
  "key": "use-minitest",
  "value": "Use MiniTest for all tests. Do not use RSpec.",
  "anti_patterns": ["require 'rspec'", "RSpec.describe"]
}

Update convention

PATCH /api/v1/playbooks/:playbook_id/conventions/:id

Delete convention

DELETE /api/v1/playbooks/:playbook_id/conventions/:id

Challenge a convention

POST /api/v1/playbooks/:playbook_id/conventions/challenge
Content-Type: application/json

{
  "convention_id": "conv_abc123",
  "reason": "RSpec is standard for this project"
}

Import from markdown

POST /api/v1/playbooks/:playbook_id/conventions/import_from_markdown
Content-Type: application/json

{
  "markdown": "## Testing\n- Use MiniTest\n- ..."
}

AI extraction

POST /api/v1/playbooks/extract_convention
Content-Type: application/json

{
  "code_sample": "class UsersController < ApplicationController...",
  "context": "Rails API application"
}

Uses AI to identify conventions from code samples. Returns suggested conventions for review.

Project assignments

Nested under projects: /:org_id/projects/:project_id/playbook_assignments.

GET /:org_id/projects/:project_id/playbook_assignments
POST /:org_id/projects/:project_id/playbook_assignments
PATCH /:org_id/projects/:project_id/playbook_assignments/:id
DELETE /:org_id/projects/:project_id/playbook_assignments/:id

Next steps