# 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](https://developers.playbookops.ai/guides/documents).

## Answer a question from your documents

### Search

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

**curl**

```bash
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?"}'
```

**Python**

```python
results = api.post("/knowledge/search", json={"query": "How do we handle refunds over $500?"}).json()
for hit in results["data"]:
    print(hit["title"], hit["url"])
    print(hit["passage"])
```

```json
{
  "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
}
```

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

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

```bash
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](https://developers.playbookops.ai/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.

```bash
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.

```json
{
  "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

| 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](https://developers.playbookops.ai/reference/knowledge).
