# Documents

> Create playbook documents from Markdown, then change them safely: replace the body or patch one section at a time.

Documents are written in Markdown, in the API and in the app. Whatever you send is what people see in the editor, with the same headings, checklists, callouts, tables and mentions. [Writing in Markdown](https://developers.playbookops.ai/guides/markdown) shows the syntax for each kind of content.

Writing needs the `knowledge:write` scope, and the key's owner needs a role above viewer and edit access to the playbook. Reading needs `knowledge:read`.

## Create a document

### Pick a playbook

Documents live in playbooks. `GET /v1/playbooks` lists the ones the key's owner can see; use the `id`.

### Post the Markdown

`POST /v1/playbooks/PLAYBOOK_ID/documents` with a title and the body in `content`.

**curl**

```bash
curl -X POST https://developers.playbookops.ai/v1/playbooks/PLAYBOOK_ID/documents \
  -H "Authorization: Bearer $PLAYBOOKOPS_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d @- <<'JSON'
{
  "title": "Refund policy",
  "document_type": "policy",
  "status": "published",
  "tags": ["support"],
  "content": "## Who can ask\n\nAnyone who paid in the last 30 days.\n\n:::note\nRefunds over $500 need a manager's approval.\n:::\n\n## How to refund\n\n1. Find the payment in Stripe\n2. Refund it to the original card\n3. Reply to the customer"
}
JSON
```

**Python**

```python
from pathlib import Path
import uuid

doc = api.post(
    f"/playbooks/{playbook_id}/documents",
    json={
        "title": "Refund policy",
        "document_type": "policy",
        "status": "published",
        "content": Path("refund-policy.md").read_text(),
    },
    headers={"Idempotency-Key": str(uuid.uuid4())},
).json()
print(doc["id"], doc["version"], doc["url"])
```

**JavaScript**

```js
import { readFile } from "node:fs/promises";

const res = await fetch(`https://developers.playbookops.ai/v1/playbooks/${playbookId}/documents`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PLAYBOOKOPS_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    title: "Refund policy",
    content: await readFile("refund-policy.md", "utf8"),
  }),
});
const doc = await res.json();
```

You get the document back with its `id`, `version` (1) and a `url` that opens it in the app.

Optional fields:

| Field | What it does |
| --- | --- |
| `description` | A one-line summary shown in lists. |
| `document_type` | `sop`, `process`, `training`, `policy`, `procedure`, `manual`, `workflow`, `internal_document`, `job_description`, `project_plan`, `proven_process` or `general` (the default). It can't change later. |
| `status` | `draft` (the default) or `published`. A label in the app; it doesn't change who can see the document. |
| `tags` | Up to 20. |
| `folder_id` | A folder in the same playbook. Leave it out for the top level. |

> **Retries are safe**
> Send an `Idempotency-Key` with every create. If the connection drops and you retry with the same key, you get the first document back instead of a duplicate. See [idempotency](https://developers.playbookops.ai/idempotency).

## Read it back

`GET /v1/documents/DOCUMENT_ID` returns the Markdown in `content` and the current `version`. Long documents are cut at 24,000 characters with `truncated: true`; add `?full=true` to get all of it.

```json
{
  "id": "6f1d2c1e-…",
  "title": "Refund policy",
  "kind": "policy",
  "content": "## Who can ask\n\nAnyone who paid in the last 30 days.\n\n…",
  "truncated": false,
  "version": 1,
  "status": "published",
  "playbook_id": "…",
  "folder_id": null,
  "tags": ["support"],
  "updated_at": "2026-11-21T15:04:05Z",
  "url": "https://app.playbookops.ai/playbooks/…?content=document&contentId=…"
}
```

## Change a document

`PATCH /v1/documents/DOCUMENT_ID` changes what you send and leaves the rest alone. Every change that touches the body or details saves a new version in the document's history.

There are two ways to change the body:

- **`content`** replaces the whole body. Use it when your system owns the document, like a policy generated from another source.
- **`edits`** change part of it: one section, one sentence, or something added at the end. Use them when people also edit the document in the app, so you don't undo their work.

### Edits

Edits find their place by heading text or by exact text, never by line numbers, so they still work after someone adds a paragraph elsewhere.

| `op` | Fields | What it does |
| --- | --- | --- |
| `replace_section` | `section`, `markdown` | Replaces everything under a heading, subsections included. The heading stays. |
| `append` | `markdown`, optional `section` | Adds to the end of the document, or to the end of that section. |
| `insert` | `markdown`, and `before` or `after` | Adds blocks just before a section's heading, or just after the section ends. |
| `remove_section` | `section` | Deletes a heading and everything under it. |
| `replace_text` | `find`, `replace`, optional `all` | Swaps exact text, including its Markdown. It must appear once unless `all` is `true`. Use it to fix a sentence or rename a heading. |

A `section` is a heading's text, with or without its `#`s, ignoring case. A section runs until the next heading of the same or a higher level, so `## Day one` includes its `### Steps`. If two headings share a name, give the path: `Day two > Steps`. Headings inside code blocks don't count.

```bash
curl -X PATCH https://developers.playbookops.ai/v1/documents/DOCUMENT_ID \
  -H "Authorization: Bearer $PLAYBOOKOPS_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "base_version": 3,
    "edits": [
      { "op": "replace_section", "section": "Who can ask", "markdown": "Anyone who paid in the last 60 days." },
      { "op": "insert", "after": "Who can ask", "markdown": "## Exceptions\n\n- Gift cards can'\''t be refunded" },
      { "op": "replace_text", "find": "Refund it to the original card", "replace": "Refund it to the original payment method" },
      { "op": "append", "markdown": "## Questions\n\nAsk [@Ana Ruiz](mention://user/PERSON_ID)." }
    ]
  }'
```

Edits apply in order, each to the result of the one before, and they're all or nothing: if one can't apply, nothing changes and you get a `400` with the code `edit_failed`, saying which edit failed and why. Here the second edit misspelled a heading:

```json
{
  "error": {
    "code": "edit_failed",
    "message": "Edit 2 (insert): There's no heading called \"Exeptions\". Headings: \"Who can ask\", \"How to refund\"."
  }
}
```

### Details

The same call changes `title`, `description`, `tags` (replaces them all) and `folder_id` (`null` moves it to the top level). `status` can be `draft`, `published` or `archived`, and only the document's owner can change it. You can send details with or without a body change.

## Don't overwrite someone else's change

Send the `version` you read as `base_version`. If anyone changed the document since, nothing is saved and you get a `409`:

```json
{
  "error": {
    "code": "version_conflict",
    "message": "The document is at version 5, not 4. Read it again, then make your change on the latest version."
  }
}
```

Read the document again, check your edits still make sense, and send them with the new version. Without `base_version`, edits still apply to whatever the document says now, which is usually what you want for small appends; `content` without it replaces whatever is there.

## What happens in the app

Saves through the API work like saves in the editor:

- A new version is added to the document's history, under the key owner's name.
- Search catches up within a minute or so.
- People and groups you [mention](https://developers.playbookops.ai/guides/markdown#mentions) for the first time get a notification. Mentions already in the previous version don't notify again.
- If people had confirmed they'd reviewed the document, a body change asks them to review it again.
- A body that doesn't actually change doesn't create a version.

## With an AI agent

Over [MCP](https://developers.playbookops.ai/mcp) the same actions are the `create_document` and `update_document` tools, with the same fields. Agents do best when you ask them to read first and patch sections rather than rewrite:

```text
Read the "Refund policy" document. Change the refund window to 60 days and add
an Exceptions section after "Who can ask" saying gift cards can't be refunded.
Use update_document with edits and base_version; don't rewrite the whole document.
```

## Reference

| Action | Endpoint | MCP tool |
| --- | --- | --- |
| Create a document | `POST /v1/playbooks/{playbook_id}/documents` | `create_document` |
| Read a document | `GET /v1/documents/{id}` | `read_document` |
| Change a document | `PATCH /v1/documents/{id}` | `update_document` |
| Find a playbook | `GET /v1/playbooks` | `list_playbooks` |
| Find a document | `GET /v1/content?kinds=document` | `list_content` |

Every field is in the [API reference](https://developers.playbookops.ai/reference/knowledge).
