Knowledge

Playbooks, documents in Markdown, and AI search across them.

GET/v1/playbooks

List playbooks

Playbooks you can see, newest first (up to 15), with how many documents each has.

Needs knowledge:readMCP tool list_playbooks

Query parameters

  • searchstring or null

    Part of a playbook's name or description

Response

  • datalist of PlaybookRequired
curl "https://developers.playbookops.ai/v1/playbooks" \
  -H "Authorization: Bearer $PLAYBOOKOPS_API_KEY"
Response · 200
{
  "data": [
    {
      "id": "6f1d2c1e-8a3b-4b8e-9d55-2c0f9e7a1b42",
      "name": "Ana Ruiz",
      "description": "Confirm the date and ask about parking.",
      "document_count": 0,
      "url": "https://app.playbookops.ai/…"
    }
  ]
}
GET/v1/content

Browse content

List or title-search documents, flowcharts, media, uploaded files, courses, projects and workflows you can see. Pass playbook_id to list what's in one playbook.

Needs knowledge:readMCP tool list_content

Query parameters

  • searchstring or null

    Part of a title

  • kindslist of one of "playbook", "document", "flowchart", "video", "audio", "image", "pdf", "word_document", "spreadsheet", "powerpoint", "learning", "project", "workflow" or null

    Only these kinds of content

  • playbook_idstring or null

    Only content inside this playbook

  • offsetinteger

    At least 0, default 0.

  • limitinteger

    1–100, default 30.

Response

  • has_morebooleanRequired

    More results after these; ask again with offset=next_offset

  • next_offsetinteger or null
  • datalist of ContentItemRequired
curl "https://developers.playbookops.ai/v1/content?limit=10" \
  -H "Authorization: Bearer $PLAYBOOKOPS_API_KEY"
Response · 200
{
  "has_more": false,
  "next_offset": 0,
  "data": [
    {
      "id": "6f1d2c1e-8a3b-4b8e-9d55-2c0f9e7a1b42",
      "kind": "document",
      "title": "Call the venue",
      "playbook_id": "6f1d2c1e-8a3b-4b8e-9d55-2c0f9e7a1b42",
      "playbook_name": "Support",
      "updated_at": "2026-11-21T15:04:05Z",
      "url": "https://app.playbookops.ai/…"
    }
  ]
}
GET/v1/documents/{document_id}

Read a document

A playbook document as Markdown, with its version, or the text of an uploaded PDF, Word document or PowerPoint. Up to 24,000 characters unless you ask for full=true.

Needs knowledge:readMCP tool read_document

Path parameters

  • document_idstringRequired

Query parameters

  • fullboolean

    Return all of a document's Markdown instead of the first 24,000 characters

    Default false.

Response

  • idstringRequired
  • titlestringRequired
  • kindstringRequired
  • contentstringRequired

    Markdown for documents; extracted text for uploaded files

  • truncatedbooleanRequired

    The content was cut short. Ask for full=true to get all of a document.

  • versioninteger or null

    Documents only. Send it back as base_version when you change the document.

  • statusone of "draft", "published", "archived" or null
  • playbook_idstring or null
  • folder_idstring or null
  • tagslist of string
  • updated_atstring (date and time) or null
  • notestring or null
  • urlstring or null
curl "https://developers.playbookops.ai/v1/documents/DOCUMENT_ID" \
  -H "Authorization: Bearer $PLAYBOOKOPS_API_KEY"
Response · 200
{
  "id": "6f1d2c1e-8a3b-4b8e-9d55-2c0f9e7a1b42",
  "title": "Call the venue",
  "kind": "document",
  "content": "## Refunds\n\nRefunds over $500 need a manager's approval…",
  "truncated": false,
  "version": 0,
  "status": "draft",
  "playbook_id": "6f1d2c1e-8a3b-4b8e-9d55-2c0f9e7a1b42",
  "folder_id": "6f1d2c1e-8a3b-4b8e-9d55-2c0f9e7a1b42",
  "tags": [
    "…"
  ],
  "updated_at": "2026-11-21T15:04:05Z",
  "note": "Up after the spring campaign",
  "url": "https://app.playbookops.ai/…"
}
POST/v1/knowledge/search

Search the knowledge base

Semantic search across the documents and uploaded files you can see. Returns the best passages with their documents. Uses 1 AI credit per search.

Needs knowledge:readMCP tool search_knowledge

Body

  • querystringRequired

    A question or topic, in plain words

    Up to 500 characters.

Response

  • querystringRequired
  • datalist of SearchHitRequired
  • credits_usedintegerRequired
curl -X POST "https://developers.playbookops.ai/v1/knowledge/search" \
  -H "Authorization: Bearer $PLAYBOOKOPS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "How do we handle refunds over $500?"
}'
Response · 200
{
  "query": "How do we handle refunds over $500?",
  "data": [
    {
      "document_id": "6f1d2c1e-8a3b-4b8e-9d55-2c0f9e7a1b42",
      "file_id": "6f1d2c1e-8a3b-4b8e-9d55-2c0f9e7a1b42",
      "title": "Call the venue",
      "passage": "Refunds over $500 need a manager's approval…",
      "similarity": 0,
      "playbook_name": "Support",
      "url": "https://app.playbookops.ai/…"
    }
  ],
  "credits_used": 0
}
POST/v1/knowledge/who-knows

Who knows about…

The people to ask about a topic, ranked by the documents they own, review or work from. Uses 1 AI credit.

Needs knowledge:readMCP tool who_knows

Body

  • topicstringRequired

    Up to 500 characters.

Response

  • topicstringRequired
  • datalist of ExpertRequired
  • credits_usedintegerRequired
curl -X POST "https://developers.playbookops.ai/v1/knowledge/who-knows" \
  -H "Authorization: Bearer $PLAYBOOKOPS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "topic": "payroll"
}'
Response · 200
{
  "topic": "payroll",
  "data": [
    {
      "name": "Ana Ruiz",
      "why": [
        "…"
      ]
    }
  ],
  "credits_used": 0
}
POST/v1/playbooks/{playbook_id}/documents

Create a document

Add a document to a playbook, written in Markdown. Returns it with its id and version.

Needs knowledge:writeChanges data · supports Idempotency-KeyMCP tool create_document

Path parameters

  • playbook_idstringRequired

Body

  • titlestringRequired

    Up to 300 characters.

  • contentstring

    The body as Markdown: headings, lists, checklists, tables, code, callouts (:::note), toggles (<details>), images and @mentions. See the Markdown guide in the docs.

    Up to 500,000 characters, default "".

  • descriptionstring

    A one-line summary shown in lists

    Up to 2,000 characters, default "".

  • document_typeone of "sop", "process", "training", "policy", "procedure", "manual", "workflow", "internal_document", "job_description", "project_plan", "general", "proven_process"

    What kind of document it is. It can't change later.

    Default "general".

  • statusone of "draft", "published"

    Shown on the document in the app. It doesn't change who can see it.

    Default "draft".

  • tagslist of string
  • folder_idstring or null

    A folder in this playbook; leave out for the top level

Response

  • idstringRequired
  • titlestringRequired
  • kindstringRequired
  • contentstringRequired

    Markdown for documents; extracted text for uploaded files

  • truncatedbooleanRequired

    The content was cut short. Ask for full=true to get all of a document.

  • versioninteger or null

    Documents only. Send it back as base_version when you change the document.

  • statusone of "draft", "published", "archived" or null
  • playbook_idstring or null
  • folder_idstring or null
  • tagslist of string
  • updated_atstring (date and time) or null
  • notestring or null
  • urlstring or null
curl -X POST "https://developers.playbookops.ai/v1/playbooks/PLAYBOOK_ID/documents" \
  -H "Authorization: Bearer $PLAYBOOKOPS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Refund policy",
  "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:::",
  "status": "published"
}'
Response · 201
{
  "id": "6f1d2c1e-8a3b-4b8e-9d55-2c0f9e7a1b42",
  "title": "Call the venue",
  "kind": "document",
  "content": "## Refunds\n\nRefunds over $500 need a manager's approval…",
  "truncated": false,
  "version": 0,
  "status": "draft",
  "playbook_id": "6f1d2c1e-8a3b-4b8e-9d55-2c0f9e7a1b42",
  "folder_id": "6f1d2c1e-8a3b-4b8e-9d55-2c0f9e7a1b42",
  "tags": [
    "…"
  ],
  "updated_at": "2026-11-21T15:04:05Z",
  "note": "Up after the spring campaign",
  "url": "https://app.playbookops.ai/…"
}
PATCH/v1/documents/{document_id}

Update a document

Change a document's Markdown and details. Send content to replace the whole body, or edits to change part of it: replace_text, replace_section, append, insert or remove_section. Send base_version to avoid overwriting someone else's change.

Needs knowledge:writeChanges data · supports Idempotency-KeyMCP tool update_document

Path parameters

  • document_idstringRequired

Body

  • base_versioninteger or null

    The version you read. If someone changed the document since, nothing changes and you get a 409.

    At least 1.

  • contentstring or null

    Replace the whole body with this Markdown

    Up to 500,000 characters.

  • editslist of ReplaceText or ReplaceSection or Append or Insert or RemoveSection or null

    Precise changes, applied in order; all of them apply or none do. Each has an op: replace_text, replace_section, append, insert or remove_section. Don't send with content.

  • titlestring or null

    Up to 300 characters.

  • descriptionstring or null

    Up to 2,000 characters.

  • statusone of "draft", "published", "archived" or null

    Only the document's owner can change this. Archived documents drop out of title search.

  • tagslist of string or null

    Replaces all of the document's tags

  • folder_idstring or null

    Move it to this folder in the same playbook; null moves it to the top level

Response

  • idstringRequired
  • titlestringRequired
  • kindstringRequired
  • contentstringRequired

    Markdown for documents; extracted text for uploaded files

  • truncatedbooleanRequired

    The content was cut short. Ask for full=true to get all of a document.

  • versioninteger or null

    Documents only. Send it back as base_version when you change the document.

  • statusone of "draft", "published", "archived" or null
  • playbook_idstring or null
  • folder_idstring or null
  • tagslist of string
  • updated_atstring (date and time) or null
  • notestring or null
  • urlstring or null
curl -X PATCH "https://developers.playbookops.ai/v1/documents/DOCUMENT_ID" \
  -H "Authorization: Bearer $PLAYBOOKOPS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "base_version": 3,
  "edits": [
    {
      "op": "replace_section",
      "section": "Who can ask",
      "markdown": "Anyone who paid in the last 60 days."
    },
    {
      "op": "append",
      "markdown": "## Questions\n\nAsk in #support."
    }
  ]
}'
Response · 200
{
  "id": "6f1d2c1e-8a3b-4b8e-9d55-2c0f9e7a1b42",
  "title": "Call the venue",
  "kind": "document",
  "content": "## Refunds\n\nRefunds over $500 need a manager's approval…",
  "truncated": false,
  "version": 0,
  "status": "draft",
  "playbook_id": "6f1d2c1e-8a3b-4b8e-9d55-2c0f9e7a1b42",
  "folder_id": "6f1d2c1e-8a3b-4b8e-9d55-2c0f9e7a1b42",
  "tags": [
    "…"
  ],
  "updated_at": "2026-11-21T15:04:05Z",
  "note": "Up after the spring campaign",
  "url": "https://app.playbookops.ai/…"
}