---
source: CrewKit documentation
url: https://crewkit.io/docs/api-playbooks.md
title: "Playbooks API"
description: "Manage playbooks, conventions, and subscriptions."
---


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.

### Subscribe

```
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

- [Experiments API](/docs/api-experiments)
- [API overview](/docs/api-overview)