# 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/content?kinds=document&playbook_id=PLAYBOOK_ID` lists documents, files, flowcharts, videos and more, newest first.

## 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` |
| Content | `GET /v1/content` | `list_content` |

Every parameter is in the [API reference](https://developers.playbookops.ai/reference/knowledge).
