Knowledge

Search your playbooks and documents, read them, and find who knows about a topic.

Everything here needs knowledge:read, and only returns what the key's owner can open in the app. To write documents, see Documents.

Answer a question from your documents

  1. 1

    Search

    POST /v1/knowledge/search finds the passages that best answer a question. Ask a whole question: search matches meaning, not just words.

    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?"}'
    
    {
      "data": [
        {
          "document_id": "…",
          "title": "Refunds and credits",
          "passage": "Refunds over $500 need a manager's approval…",
          "similarity": 0.87,
          "playbook_name": "Support",
          "url": "https://app.playbookops.ai/playbooks/…"
        }
      ],
      "credits_used": 1
    }
    
  2. 2

    Read the document

    If the passage isn't enough, GET /v1/documents/DOCUMENT_ID returns the whole document as Markdown. Documents over 24,000 characters are cut off, with truncated: true; add ?full=true for all of it.

  3. 3

    Find someone to ask

    When the documents don't cover it, POST /v1/knowledge/who-knows with a topic returns the people who know about it, and why.

    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"}'
    
Search and who knows use AI credits

Each call uses 1 AI credit from your organization, and says so in credits_used. Everything else on this page is free. See limits and credits.

Browse

  • GET /v1/playbooks?search=onboarding lists playbooks, with how many documents each has.
  • GET /v1/playbooks/PLAYBOOK_ID/folders lists a playbook's folders, each with its path, like Runbooks / Database.
  • GET /v1/content?kinds=document&playbook_id=PLAYBOOK_ID lists documents, files, flowcharts, videos and more, most recently changed first.

Organize

With knowledge:write, a key can set up the structure documents go in. The key's owner needs a role above viewer.

  • POST /v1/playbooks with a name and description makes a playbook. Everyone in the organization can see it until someone limits access in the app.
  • POST /v1/playbooks/PLAYBOOK_ID/folders with a name, and a parent_folder_id to nest it, makes a folder. Folders go up to six levels deep, and need edit access to the playbook.
curl -X POST https://developers.playbookops.ai/v1/playbooks/PLAYBOOK_ID/folders \
  -H "Authorization: Bearer $PLAYBOOKOPS_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: folder:runbooks" \
  -d '{"name": "Runbooks"}'

Keep up with changes

GET /v1/document-changes?since=TIME returns what happened to documents after a time, for keeping a copy somewhere else in step: a folder of Markdown files, a search index, an agent's cache.

{
  "changed": [
    { "id": "…", "title": "Restore a backup", "playbook_id": "…", "folder_id": "…", "version": 4, "status": "published", "updated_at": "2026-11-21T18:02:11Z", "url": "…" }
  ],
  "removed": [
    { "id": "…", "playbook_id": "…", "removed_at": "2026-11-21T18:05:40Z" }
  ],
  "has_more": false,
  "next_since": "2026-11-21T18:09:00Z"
}
  • changed has documents created or edited, oldest change first. Read the ones you need with GET /v1/documents/{id}. Archived documents show up here with status: "archived".
  • removed has documents deleted, or moved to another playbook, including every document in a deleted playbook. Removals are kept for 90 days, so poll more often than that.
  • Send next_since as since next time. When has_more is true, ask again straight away. Answers overlap a little so nothing is missed between polls, so treat a document you've already seen as a no-op.
  • Add playbook_id to follow one playbook.

Reference

ActionEndpointMCP tool
SearchPOST /v1/knowledge/searchsearch_knowledge
Who knowsPOST /v1/knowledge/who-knowswho_knows
Read a documentGET /v1/documents/{id}read_document
Create a documentPOST /v1/playbooks/{id}/documentscreate_document
Change a documentPATCH /v1/documents/{id}update_document
PlaybooksGET /v1/playbookslist_playbooks
Create a playbookPOST /v1/playbookscreate_playbook
FoldersGET /v1/playbooks/{id}/folderslist_folders
Create a folderPOST /v1/playbooks/{id}/folderscreate_folder
ContentGET /v1/contentlist_content
What changedGET /v1/document-changeslist_document_changes

Every parameter is in the API reference.