> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vendexlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Playbooks & AI drafts

> Manage playbooks and drive the AI comment drafting flow.

These endpoints power [playbooks](https://docs.vendexlabs.com/guides/playbooks.md) and [Draft with AI](https://docs.vendexlabs.com/guides/draft-comments-with-ai.md). All routes take an `account-id` query parameter and live under `/vendor-assessments`. AI drafting requires the **Enterprise** plan.

## Playbooks

| Method | Path | Role | Purpose |
| - | - | - | - |
| `GET` | `/playbooks` | viewer | List playbooks. Add `include-archived=true` to include archived ones. |
| `GET` | `/playbooks/resolve?vendor-list-id={id}&vendor-id={id}` | viewer | Return the playbook that applies to a vendor (picked by tier and tags, else the default). |
| `POST` | `/playbooks` | editor | Create a playbook as a draft. |
| `GET` | `/playbooks/{playbook_id}` | viewer | Get a playbook. |
| `PUT` | `/playbooks/{playbook_id}` | editor | Update a draft. Published playbooks can only be changed by admins. |
| `POST` | `/playbooks/{playbook_id}/publish` | admin | Publish a draft. |
| `POST` | `/playbooks/{playbook_id}/archive` | admin | Archive a playbook. |
| `POST` | `/playbooks/{playbook_id}/set-default` | admin | Make it the default playbook. |
| `POST` · `DELETE` | `/playbooks/{playbook_id}/document` | editor | Attach (multipart `file`, text PDF up to 5 MB) or remove the reference document. |

## Draft a comment

Drafting is a short conversation, called a **thread**. Opening a thread gathers and freezes the evidence, so every refinement cites the same sources.

**GET /vendor-assessments/\{assessment\_id}/comment-sources?account-id=\{uuid}\&comment-type=security\&playbook-id=\{id}**

Preview the evidence a draft would use, without generating anything or using up the monthly allowance. `comment-type` is `security`, `compliance`, or `privacy`.

**POST /vendor-assessments/\{assessment\_id}/comment-threads?account-id=\{uuid}**

Open a thread and generate the first draft. Body: `comment_type` (required), plus optional `playbook_id` and `prompt_override` (instructions for this draft only).

**POST /vendor-assessments/comment-threads/\{thread\_id}/turns?account-id=\{uuid}**

Refine the draft. Body: `{ "user_message": "Shorter, and name the gaps." }`

**GET /vendor-assessments/comment-threads/\{thread\_id}?account-id=\{uuid}**

Get the thread with every turn.

**POST /vendor-assessments/comment-threads/\{thread\_id}/insert?account-id=\{uuid}**

Write a turn's draft into the assessment's comment field. Body: `{ "turn_index": 0 }`

Each draft returns the comment text and a `claims` list. Every claim lists the `source_ids` it rests on and a `kind` such as a cited fact, a gap, or `unattested`.

| Status | Meaning |
| - | - |
| `403` | The organization isn't on Enterprise (`enterprise_required`), or your role can't write. |
| `402` | The monthly draft allowance is used up (`insufficient_credits`). |
| `429` | The thread hit its refinement limit (`turn_limit_reached`). Open a new thread. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.