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 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
- 1
Pick a playbook
Documents live in playbooks.
GET /v1/playbookslists the ones the key's owner can see; use theid. - 2
Post the Markdown
POST /v1/playbooks/PLAYBOOK_ID/documentswith a title and the body incontent.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" } JSONYou get the document back with its
id,version(1) and aurlthat 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. |
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.
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.
{
"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:
contentreplaces the whole body. Use it when your system owns the document, like a policy generated from another source.editschange 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.
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:
{
"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:
{
"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 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 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:
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.