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
Search
POST /v1/knowledge/searchfinds 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
Read the document
If the passage isn't enough,
GET /v1/documents/DOCUMENT_IDreturns the whole document as Markdown. Documents over 24,000 characters are cut off, withtruncated: true; add?full=truefor all of it. - 3
Find someone to ask
When the documents don't cover it,
POST /v1/knowledge/who-knowswith 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"}'
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=onboardinglists playbooks, with how many documents each has.GET /v1/playbooks/PLAYBOOK_ID/folderslists a playbook's folders, each with its path, likeRunbooks / Database.GET /v1/content?kinds=document&playbook_id=PLAYBOOK_IDlists 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/playbookswith anameanddescriptionmakes a playbook. Everyone in the organization can see it until someone limits access in the app.POST /v1/playbooks/PLAYBOOK_ID/folderswith aname, and aparent_folder_idto 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"
}
changedhas documents created or edited, oldest change first. Read the ones you need withGET /v1/documents/{id}. Archived documents show up here withstatus: "archived".removedhas 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_sinceassincenext time. Whenhas_moreis 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_idto follow one playbook.
Reference
| Action | Endpoint | MCP tool |
|---|---|---|
| Search | POST /v1/knowledge/search | search_knowledge |
| Who knows | POST /v1/knowledge/who-knows | who_knows |
| Read a document | GET /v1/documents/{id} | read_document |
| Create a document | POST /v1/playbooks/{id}/documents | create_document |
| Change a document | PATCH /v1/documents/{id} | update_document |
| Playbooks | GET /v1/playbooks | list_playbooks |
| Create a playbook | POST /v1/playbooks | create_playbook |
| Folders | GET /v1/playbooks/{id}/folders | list_folders |
| Create a folder | POST /v1/playbooks/{id}/folders | create_folder |
| Content | GET /v1/content | list_content |
| What changed | GET /v1/document-changes | list_document_changes |
Every parameter is in the API reference.