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 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. 1

    Pick a playbook

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

  2. 2

    Post the Markdown

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

    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
    

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

Optional fields:

FieldWhat it does
descriptionA one-line summary shown in lists.
document_typesop, process, training, policy, procedure, manual, workflow, internal_document, job_description, project_plan, proven_process or general (the default). It can't change later.
statusdraft (the default) or published. A label in the app; it doesn't change who can see the document.
tagsUp to 20.
folder_idA 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.

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:

  • 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.

opFieldsWhat it does
replace_sectionsection, markdownReplaces everything under a heading, subsections included. The heading stays.
appendmarkdown, optional sectionAdds to the end of the document, or to the end of that section.
insertmarkdown, and before or afterAdds blocks just before a section's heading, or just after the section ends.
remove_sectionsectionDeletes a heading and everything under it.
replace_textfind, replace, optional allSwaps 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

ActionEndpointMCP tool
Create a documentPOST /v1/playbooks/{playbook_id}/documentscreate_document
Read a documentGET /v1/documents/{id}read_document
Change a documentPATCH /v1/documents/{id}update_document
Find a playbookGET /v1/playbookslist_playbooks
Find a documentGET /v1/content?kinds=documentlist_content

Every field is in the API reference.