# Build on PlaybookOps
> Connect your code and AI agents to your projects, tasks, knowledge, automations, apps, people and KPIs.
PlaybookOps has a REST API for your own code and an MCP server for AI agents. Both use the same API keys and offer the same actions, and a key can only reach what the person who made it can reach in the app.
- [Quickstart](https://developers.playbookops.ai/quickstart): Make a key and get your projects back in about two minutes.
- [Connect an AI agent](https://developers.playbookops.ai/mcp): Give Claude, Cursor or ChatGPT access to PlaybookOps over MCP.
- [Guides](https://developers.playbookops.ai/guides/projects-and-items): Walkthroughs for boards, tasks, knowledge, automations and apps.
- [API reference](https://developers.playbookops.ai/reference): Every endpoint, with examples and a Try it button that uses your key.
## Two ways in
**The REST API** is JSON over HTTPS at `https://developers.playbookops.ai/v1`. Use it for code with fixed steps: syncing items with another system, a webhook handler, a dashboard, a script that files tasks.
**The MCP server** at `https://mcp.playbookops.ai` offers the same actions as tools for AI agents. The agent reads each tool's description and decides what to call: "what's overdue on the launch board?" becomes `list_projects`, then `list_items`.
## What you can reach
| Area | Read | Change |
| --- | --- | --- |
| Projects and items | Projects, groups, columns, items, updates, search | Create, update, move and complete items; post updates |
| Tasks | Your tasks across projects and personal lists | Create personal tasks; update and complete your own |
| Knowledge | Playbooks, documents, search, who knows about a topic | [Create documents in Markdown](https://developers.playbookops.ai/guides/documents) and patch them section by section |
| Automations | Automations, runs and their steps | Start automations that are started by hand |
| Apps | Apps you can open, their collections and Live records | Create and update records |
| People and KPIs | People, job roles, KPIs and their values | |
## Good to know
- **A key acts as you.** It sees the projects you're on and the apps you can open, and its changes show up in the app as yours, with notifications and automations as usual. See [API keys and scopes](https://developers.playbookops.ai/authentication).
- **Admins stay in control.** Org admins see every key in the organization, can revoke any of them, can turn the API off, and can see the organization's API and MCP traffic under **Admin → API**.
- **Most calls are free.** Knowledge search and who knows use AI credits. Each key can make 120 requests a minute. See [limits and credits](https://developers.playbookops.ai/limits-and-credits).
- **Docs for models.** Every page is available as Markdown, and [`/llms.txt`](https://developers.playbookops.ai/llms.txt) lists them all for coding agents.
---
# Quickstart
> Make an API key, check it works, and read your first project.
You'll need a PlaybookOps account. Any member can make keys, unless an admin has turned the API off for your organization.
### Make a key
Open Account → API keys in PlaybookOps and click **New key**. Name it after what will use it, like "Zapier" or "Support agent". Then choose:
- **Read-only** to look around safely. Nothing can be changed with it.
- **Full access** when your code needs to create or update things.
You can also set it to expire after 30, 90 or 365 days. Copy the key when it's shown. It starts with `pbo_live_`, and you won't see it again. Keep it in an environment variable rather than in your code:
```bash
export PLAYBOOKOPS_API_KEY="pbo_live_…"
```
### Check who you are
`GET /v1/me` tells you who the key belongs to and what it's allowed to do.
**curl**
```bash
curl https://developers.playbookops.ai/v1/me \
-H "Authorization: Bearer $PLAYBOOKOPS_API_KEY"
```
**Python**
```python
import os
import httpx
api = httpx.Client(
base_url="https://developers.playbookops.ai/v1",
headers={"Authorization": f"Bearer {os.environ['PLAYBOOKOPS_API_KEY']}"},
)
print(api.get("/me").json())
```
**JavaScript**
```javascript
const res = await fetch("https://developers.playbookops.ai/v1/me", {
headers: { Authorization: `Bearer ${process.env.PLAYBOOKOPS_API_KEY}` },
});
console.log(await res.json());
```
You'll get your name, organization and the key's scopes:
```json
{
"id": "4b1c…",
"name": "Ana Ruiz",
"organization_id": "9f20…",
"role": "member",
"scopes": ["projects:read", "tasks:read", "knowledge:read", "automations:read", "apps:read", "people:read", "kpis:read"],
"via": "api_key"
}
```
A `401` means the key is wrong, expired or revoked. See [errors](https://developers.playbookops.ai/errors) for the rest.
### Read a project
List your projects, then the open items in one of them:
**curl**
```bash
curl "https://developers.playbookops.ai/v1/projects?limit=5" \
-H "Authorization: Bearer $PLAYBOOKOPS_API_KEY"
curl "https://developers.playbookops.ai/v1/projects/PROJECT_ID/items?include_completed=false" \
-H "Authorization: Bearer $PLAYBOOKOPS_API_KEY"
```
**Python**
```python
projects = api.get("/projects", params={"limit": 5}).json()["data"]
for project in projects:
print(project["name"], project["url"])
items = api.get(f"/projects/{projects[0]['id']}/items", params={"include_completed": False}).json()
for item in items["data"]:
print(item["title"], item["status"], item["due_date"])
```
**JavaScript**
```javascript
const headers = { Authorization: `Bearer ${process.env.PLAYBOOKOPS_API_KEY}` };
const base = "https://developers.playbookops.ai/v1";
const { data: projects } = await (await fetch(`${base}/projects?limit=5`, { headers })).json();
const items = await (await fetch(`${base}/projects/${projects[0].id}/items?include_completed=false`, { headers })).json();
console.log(items.data.map((i) => i.title));
```
Everything you can open in the app has a `url`, so you can link people straight to it.
### Go further
- Follow a guide: [projects and items](https://developers.playbookops.ai/guides/projects-and-items), [tasks](https://developers.playbookops.ai/guides/tasks) or [knowledge](https://developers.playbookops.ai/guides/knowledge).
- Open the [API reference](https://developers.playbookops.ai/reference) and use **Try it** on any endpoint. It runs against your own organization, so changes made there are real.
- [Connect an AI agent](https://developers.playbookops.ai/mcp) with the same key.
> **Explore with a read-only key**
> A read-only key can't change anything, so it's safe for exploring, reports and dashboards. Make a separate Full access key for code that needs to write.
---
# Connect an AI agent
> Give Claude, Cursor, ChatGPT or your own agent access to PlaybookOps over MCP.
PlaybookOps runs a remote [Model Context Protocol](https://modelcontextprotocol.io) server. Point your client at this address and send an API key:
```text
https://mcp.playbookops.ai
```
The tools are the API's actions, like `list_projects`, `search_knowledge`, `create_item` and `update_document`, with the same inputs and answers as the [API reference](https://developers.playbookops.ai/reference). An agent only sees the tools its key's scopes allow, so with a read-only key it has no way to change anything.
> **Make a key just for the agent**
> Make a key named after the agent, with the least access that works. Every change the agent makes is recorded against that key, and you can revoke it at any time.
## Set up your client
**Claude Code**
```bash
claude mcp add --transport http playbookops https://mcp.playbookops.ai \
--header "Authorization: Bearer $PLAYBOOKOPS_API_KEY"
```
Run `/mcp` inside Claude Code to check that it's connected.
**Cursor**
Add this to `~/.cursor/mcp.json`, or to `.cursor/mcp.json` in a project, and set `PLAYBOOKOPS_API_KEY` in your environment:
```json
{
"mcpServers": {
"playbookops": {
"url": "https://mcp.playbookops.ai",
"headers": { "Authorization": "Bearer ${env:PLAYBOOKOPS_API_KEY}" }
}
}
}
```
**Claude Desktop**
Claude Desktop starts servers on your computer, so it connects through [`mcp-remote`](https://www.npmjs.com/package/mcp-remote), which needs [Node.js](https://nodejs.org). Open **Settings → Developer → Edit Config** and add:
```json
{
"mcpServers": {
"playbookops": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://mcp.playbookops.ai", "--header", "Authorization:${PLAYBOOKOPS_AUTH}"],
"env": { "PLAYBOOKOPS_AUTH": "Bearer pbo_live_…" }
}
}
}
```
Then restart Claude Desktop.
**Python**
With the official [`mcp`](https://pypi.org/project/mcp/) package:
```python
import asyncio
import os
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client
async def main():
headers = {"Authorization": f"Bearer {os.environ['PLAYBOOKOPS_API_KEY']}"}
async with streamablehttp_client("https://mcp.playbookops.ai", headers=headers) as (read, write, _):
async with ClientSession(read, write) as session:
await session.initialize()
tools = await session.list_tools()
print([t.name for t in tools.tools])
result = await session.call_tool("list_projects", {"limit": 5})
print(result.structuredContent)
asyncio.run(main())
```
**TypeScript**
With the official [`@modelcontextprotocol/sdk`](https://www.npmjs.com/package/@modelcontextprotocol/sdk) package:
```typescript
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
const transport = new StreamableHTTPClientTransport(new URL("https://mcp.playbookops.ai"), {
requestInit: { headers: { Authorization: `Bearer ${process.env.PLAYBOOKOPS_API_KEY}` } },
});
const client = new Client({ name: "my-agent", version: "1.0.0" });
await client.connect(transport);
const { tools } = await client.listTools();
const result = await client.callTool({ name: "list_projects", arguments: { limit: 5 } });
console.log(result.structuredContent);
```
Model APIs that connect to MCP servers themselves, like Anthropic's MCP connector and OpenAI's remote MCP tool, need the same two things: the address `https://mcp.playbookops.ai` and the key as a Bearer token.
## Try it out
Once connected, ask your agent something like:
- "What's due this week on my PlaybookOps tasks?"
- "Search our playbooks for how we handle refunds over $500, and link the document."
- "Who knows the most about payroll?"
- "Add an item to the Launch board for calling the venue, due Friday, assigned to me."
## What the agent gets back
- Every tool returns structured JSON (`structuredContent`) that matches its output schema, plus the same JSON as text.
- A failed call comes back with `isError: true` and a plain sentence, like "This key can't do that. It needs the projects:write scope." The agent can read it and adjust.
- Tools that change things are marked as such, so clients that ask before running them will ask.
- Calls count toward the same [rate limits and credits](https://developers.playbookops.ai/limits-and-credits) as the REST API.
> **Retried changes run again**
> MCP calls can't carry an `Idempotency-Key`, so if an agent retries a change it happens twice. Good agents look before retrying, for example by searching for an item before creating it again.
`https://developers.playbookops.ai/mcp` is the same server, if you'd rather use one address for everything.
---
# Building agents
> Patterns for agents and integrations that read and change PlaybookOps safely.
## Pick the right way in
| You're building | Use |
| --- | --- |
| An AI agent that decides what to do | The [MCP server](https://developers.playbookops.ai/mcp). The model reads each tool's description and picks what it needs. |
| Code with fixed steps: a sync job, a webhook handler, a dashboard | The REST API. Same actions, plain HTTP, and [safe retries](https://developers.playbookops.ai/idempotency). |
| A custom agent with your own model calls | Either. MCP SDKs list the tools for you; or describe a few REST calls as your own tools. |
## Give each agent its own key
One key per agent or integration, named after it, with the least access that works:
- **Read-only** for anything that answers questions or reports. It can't change anything, whatever the model decides to do.
- **Full access** only when it must make changes. Over MCP the agent then sees the tools that change things too.
Keys act as the person who made them, so an agent never sees more than its owner. Admins can see each key's traffic under **Admin → API** and revoke it there.
## Ground answers in your knowledge
For questions about how your organization works, have the agent:
1. Call `search_knowledge` with the whole question, not keywords. Search matches meaning.
2. Call `read_document` for the documents that matter, to read beyond the passage.
3. Cite the `url` of each document it used, so people can check.
4. Call `who_knows` to find someone to ask when the documents don't cover it.
A system prompt line that works well:
```text
When asked how we do something, search PlaybookOps knowledge first and answer only from what you find. Link each document you used. If nothing covers it, say so and suggest who to ask using who_knows.
```
## Make changes safely
- **Read before you write.** Call `get_project` for the board's groups and columns before setting values, and `list_people` before assigning someone.
- **Don't repeat changes.** Over REST, send an `Idempotency-Key` with every change ([how](https://developers.playbookops.ai/idempotency)). Over MCP, check whether something exists before creating it again.
- **Handle limits.** On `429`, wait `Retry-After` seconds. On `402`, tell the person their organization is out of AI credits.
- **Let the app notify people.** Changes made through the API behave like changes in the app: assignees are notified and automations run. Your agent doesn't need to send its own messages.
## Docs for models
These docs come in plain text for models and coding agents:
- [`/llms.txt`](https://developers.playbookops.ai/llms.txt) lists every page with a one-line summary.
- [`/llms-full.txt`](https://developers.playbookops.ai/llms-full.txt) has every guide in one file.
- Every page is also available as Markdown: add `.md` to its address.
- [`/v1/openapi.json`](https://developers.playbookops.ai/v1/openapi.json) describes the API in OpenAPI 3.1, for code generators.
---
# Projects and items
> Read a board, add items to it, and keep them up to date.
A project is a board of **items** arranged in **groups**, with **columns** for custom values. The API uses the same words as the app. Reading needs `projects:read`; changing needs `projects:write`.
## Read a board
### Find the project
`GET /v1/projects` lists the projects the key's owner owns or is a member of.
```bash
curl https://developers.playbookops.ai/v1/projects \
-H "Authorization: Bearer $PLAYBOOKOPS_API_KEY"
```
### Learn its groups and columns
`GET /v1/projects/PROJECT_ID` returns the groups in board order and every column with its type and, for select columns, its options.
```bash
curl https://developers.playbookops.ai/v1/projects/PROJECT_ID \
-H "Authorization: Bearer $PLAYBOOKOPS_API_KEY"
```
### Read the items
`GET /v1/projects/PROJECT_ID/items` returns items in board order. Filter by group, by title, and by whether they're done:
```bash
curl "https://developers.playbookops.ai/v1/projects/PROJECT_ID/items?group_id=GROUP_ID&include_completed=false&include_subitems=true" \
-H "Authorization: Bearer $PLAYBOOKOPS_API_KEY"
```
Built-in fields like `status`, `assignee_id`, `due_date` and `priority` are top-level fields on each item. Custom column values are in `values`, keyed by column id. Use the project's `columns` to turn ids into names, and option ids into labels.
To find an item without knowing its project, search by title with `GET /v1/items/search?query=venue`.
## Add an item
`POST /v1/projects/PROJECT_ID/items`:
**curl**
```bash
curl -X POST https://developers.playbookops.ai/v1/projects/PROJECT_ID/items \
-H "Authorization: Bearer $PLAYBOOKOPS_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"title": "Call the venue",
"group_id": "GROUP_ID",
"assignee_id": "PERSON_ID",
"due_date": "2026-12-05",
"priority": "high",
"values": { "COLUMN_ID": "Ask about parking" }
}'
```
**Python**
```python
import uuid
item = api.post(
f"/projects/{project_id}/items",
headers={"Idempotency-Key": str(uuid.uuid4())},
json={
"title": "Call the venue",
"group_id": group_id,
"assignee_id": person_id,
"due_date": "2026-12-05",
"priority": "high",
"values": {column_id: "Ask about parking"},
},
).json()
print(item["url"])
```
**JavaScript**
```javascript
const res = await fetch(`${base}/projects/${projectId}/items`, {
method: "POST",
headers: { ...headers, "Content-Type": "application/json", "Idempotency-Key": crypto.randomUUID() },
body: JSON.stringify({
title: "Call the venue",
group_id: groupId,
assignee_id: personId,
due_date: "2026-12-05",
priority: "high",
values: { [columnId]: "Ask about parking" },
}),
});
const item = await res.json();
```
- Without `group_id`, the item goes in the project's first group.
- With `parent_id`, it's a subitem, in its parent's group.
- `values` takes column ids or column keys, and each value is checked against its column's type, as in the app.
- `assignee_id` is a person's `id` from `GET /v1/people`.
## Update an item
`PATCH /v1/items/ITEM_ID` changes only the fields you send. Send `null` to clear one:
```json
{ "status": "in_progress", "due_date": null, "values": { "COLUMN_ID": null } }
```
Send `group_id` to move the item to another group in the same project.
## Move it to another project
`POST /v1/items/ITEM_ID/move` with a `project_id`, and optionally a `group_id`. Subitems go with it, and column values carry over to columns with the same name and type.
## Complete it and post an update
```bash
# Mark it done
curl -X POST https://developers.playbookops.ai/v1/items/ITEM_ID/complete \
-H "Authorization: Bearer $PLAYBOOKOPS_API_KEY" -H "Content-Type: application/json" -d '{}'
# Reopen it
curl -X POST https://developers.playbookops.ai/v1/items/ITEM_ID/complete \
-H "Authorization: Bearer $PLAYBOOKOPS_API_KEY" -H "Content-Type: application/json" -d '{"completed": false}'
# Post an update that mentions someone
curl -X POST https://developers.playbookops.ai/v1/items/ITEM_ID/comments \
-H "Authorization: Bearer $PLAYBOOKOPS_API_KEY" -H "Content-Type: application/json" \
-d '{"body": "Booked for the 5th. [@Bea](mention://user/PERSON_ID) can you confirm?"}'
```
Updates on an item are listed by `GET /v1/items/ITEM_ID/comments`.
> **Changes behave like the app's**
> Assignees and mentioned people are notified, automations watching the project run, and the item's activity shows who made the change. Project viewers can read a project but can't change it.
## Reference
| Action | Endpoint | MCP tool |
| --- | --- | --- |
| List projects | `GET /v1/projects` | `list_projects` |
| Groups and columns | `GET /v1/projects/{id}` | `get_project` |
| List items | `GET /v1/projects/{id}/items` | `list_items` |
| Search items | `GET /v1/items/search` | `search_items` |
| One item | `GET /v1/items/{id}` | `get_item` |
| Add an item | `POST /v1/projects/{id}/items` | `create_item` |
| Update an item | `PATCH /v1/items/{id}` | `update_item` |
| Move an item | `POST /v1/items/{id}/move` | `move_item` |
| Complete or reopen | `POST /v1/items/{id}/complete` | `complete_item` |
| Updates | `GET` and `POST /v1/items/{id}/comments` | `list_item_comments`, `add_item_comment` |
Every parameter is in the [API reference](https://developers.playbookops.ai/reference/projects-and-items).
---
# Tasks
> Everything assigned to you across projects, and your personal tasks.
The task endpoints work on the key owner's own work: items assigned to them in any project, plus personal tasks that aren't in a project. They're a good fit for personal assistants and daily digests, because a key only needs `tasks` scopes, not access to whole projects.
## See what's on your plate
`GET /v1/tasks/mine` needs `tasks:read`. It sorts everything assigned to you into `overdue`, `due_today`, `upcoming` and `no_due_date`:
**curl**
```bash
curl https://developers.playbookops.ai/v1/tasks/mine \
-H "Authorization: Bearer $PLAYBOOKOPS_API_KEY"
```
**Python**
```python
tasks = api.get("/tasks/mine").json()
for task in tasks["overdue"] + tasks["due_today"]:
print(f"{task['title']} (due {task['due_date']}) {task['url']}")
```
Add `include_completed=true` to include finished ones.
## Personal tasks
With `tasks:write`:
| Call | What it does |
| --- | --- |
| `POST /v1/tasks` | Creates a task outside any project. It's yours unless you pass `assignee_id`. |
| `PATCH /v1/tasks/TASK_ID` | Updates a personal task, or a project item assigned to you. |
| `POST /v1/tasks/TASK_ID/complete` | Completes it, or reopens it with `{"completed": false}`. |
```bash
curl -X POST https://developers.playbookops.ai/v1/tasks \
-H "Authorization: Bearer $PLAYBOOKOPS_API_KEY" -H "Content-Type: application/json" \
-d '{"title": "Renew the domain", "due_date": "2026-12-01", "priority": "urgent"}'
```
To change project items that aren't assigned to you, use the [item endpoints](https://developers.playbookops.ai/guides/projects-and-items) with a `projects:write` key.
## Reference
| Action | Endpoint | MCP tool |
| --- | --- | --- |
| Your tasks | `GET /v1/tasks/mine` | `my_tasks` |
| Add a task | `POST /v1/tasks` | `create_task` |
| Update a task | `PATCH /v1/tasks/{id}` | `update_task` |
| Complete or reopen | `POST /v1/tasks/{id}/complete` | `complete_task` |
Every parameter is in the [API reference](https://developers.playbookops.ai/reference/tasks).
---
# 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).
---
# Documents
> Create playbook documents from Markdown, then change them safely: replace the body or patch one section at a time.
Documents are written in Markdown, in the API and in the app. Whatever you send is what people see in the editor, with the same headings, checklists, callouts, tables and mentions. [Writing in Markdown](https://developers.playbookops.ai/guides/markdown) shows the syntax for each kind of content.
Writing needs the `knowledge:write` scope, and the key's owner needs a role above viewer and edit access to the playbook. Reading needs `knowledge:read`.
## Create a document
### Pick a playbook
Documents live in playbooks. `GET /v1/playbooks` lists the ones the key's owner can see; use the `id`.
### Post the Markdown
`POST /v1/playbooks/PLAYBOOK_ID/documents` with a title and the body in `content`.
**curl**
```bash
curl -X POST https://developers.playbookops.ai/v1/playbooks/PLAYBOOK_ID/documents \
-H "Authorization: Bearer $PLAYBOOKOPS_API_KEY" -H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d @- <<'JSON'
{
"title": "Refund policy",
"document_type": "policy",
"status": "published",
"tags": ["support"],
"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:::\n\n## How to refund\n\n1. Find the payment in Stripe\n2. Refund it to the original card\n3. Reply to the customer"
}
JSON
```
**Python**
```python
from pathlib import Path
import uuid
doc = api.post(
f"/playbooks/{playbook_id}/documents",
json={
"title": "Refund policy",
"document_type": "policy",
"status": "published",
"content": Path("refund-policy.md").read_text(),
},
headers={"Idempotency-Key": str(uuid.uuid4())},
).json()
print(doc["id"], doc["version"], doc["url"])
```
**JavaScript**
```js
import { readFile } from "node:fs/promises";
const res = await fetch(`https://developers.playbookops.ai/v1/playbooks/${playbookId}/documents`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.PLAYBOOKOPS_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": crypto.randomUUID(),
},
body: JSON.stringify({
title: "Refund policy",
content: await readFile("refund-policy.md", "utf8"),
}),
});
const doc = await res.json();
```
You get the document back with its `id`, `version` (1) and a `url` that opens it in the app.
Optional fields:
| Field | What it does |
| --- | --- |
| `description` | A one-line summary shown in lists. |
| `document_type` | `sop`, `process`, `training`, `policy`, `procedure`, `manual`, `workflow`, `internal_document`, `job_description`, `project_plan`, `proven_process` or `general` (the default). It can't change later. |
| `status` | `draft` (the default) or `published`. A label in the app; it doesn't change who can see the document. |
| `tags` | Up to 20. |
| `folder_id` | A folder in the same playbook. Leave it out for the top level. |
> **Retries are safe**
> Send an `Idempotency-Key` with every create. If the connection drops and you retry with the same key, you get the first document back instead of a duplicate. See [idempotency](https://developers.playbookops.ai/idempotency).
## Read it back
`GET /v1/documents/DOCUMENT_ID` returns the Markdown in `content` and the current `version`. Long documents are cut at 24,000 characters with `truncated: true`; add `?full=true` to get all of it.
```json
{
"id": "6f1d2c1e-…",
"title": "Refund policy",
"kind": "policy",
"content": "## Who can ask\n\nAnyone who paid in the last 30 days.\n\n…",
"truncated": false,
"version": 1,
"status": "published",
"playbook_id": "…",
"folder_id": null,
"tags": ["support"],
"updated_at": "2026-11-21T15:04:05Z",
"url": "https://app.playbookops.ai/playbooks/…?content=document&contentId=…"
}
```
## Change a document
`PATCH /v1/documents/DOCUMENT_ID` changes what you send and leaves the rest alone. Every change that touches the body or details saves a new version in the document's history.
There are two ways to change the body:
- **`content`** replaces the whole body. Use it when your system owns the document, like a policy generated from another source.
- **`edits`** change part of it: one section, one sentence, or something added at the end. Use them when people also edit the document in the app, so you don't undo their work.
### Edits
Edits find their place by heading text or by exact text, never by line numbers, so they still work after someone adds a paragraph elsewhere.
| `op` | Fields | What it does |
| --- | --- | --- |
| `replace_section` | `section`, `markdown` | Replaces everything under a heading, subsections included. The heading stays. |
| `append` | `markdown`, optional `section` | Adds to the end of the document, or to the end of that section. |
| `insert` | `markdown`, and `before` or `after` | Adds blocks just before a section's heading, or just after the section ends. |
| `remove_section` | `section` | Deletes a heading and everything under it. |
| `replace_text` | `find`, `replace`, optional `all` | Swaps exact text, including its Markdown. It must appear once unless `all` is `true`. Use it to fix a sentence or rename a heading. |
A `section` is a heading's text, with or without its `#`s, ignoring case. A section runs until the next heading of the same or a higher level, so `## Day one` includes its `### Steps`. If two headings share a name, give the path: `Day two > Steps`. Headings inside code blocks don't count.
```bash
curl -X PATCH https://developers.playbookops.ai/v1/documents/DOCUMENT_ID \
-H "Authorization: Bearer $PLAYBOOKOPS_API_KEY" -H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"base_version": 3,
"edits": [
{ "op": "replace_section", "section": "Who can ask", "markdown": "Anyone who paid in the last 60 days." },
{ "op": "insert", "after": "Who can ask", "markdown": "## Exceptions\n\n- Gift cards can'\''t be refunded" },
{ "op": "replace_text", "find": "Refund it to the original card", "replace": "Refund it to the original payment method" },
{ "op": "append", "markdown": "## Questions\n\nAsk [@Ana Ruiz](mention://user/PERSON_ID)." }
]
}'
```
Edits apply in order, each to the result of the one before, and they're all or nothing: if one can't apply, nothing changes and you get a `400` with the code `edit_failed`, saying which edit failed and why. Here the second edit misspelled a heading:
```json
{
"error": {
"code": "edit_failed",
"message": "Edit 2 (insert): There's no heading called \"Exeptions\". Headings: \"Who can ask\", \"How to refund\"."
}
}
```
### Details
The same call changes `title`, `description`, `tags` (replaces them all) and `folder_id` (`null` moves it to the top level). `status` can be `draft`, `published` or `archived`, and only the document's owner can change it. You can send details with or without a body change.
## Don't overwrite someone else's change
Send the `version` you read as `base_version`. If anyone changed the document since, nothing is saved and you get a `409`:
```json
{
"error": {
"code": "version_conflict",
"message": "The document is at version 5, not 4. Read it again, then make your change on the latest version."
}
}
```
Read the document again, check your edits still make sense, and send them with the new version. Without `base_version`, edits still apply to whatever the document says now, which is usually what you want for small appends; `content` without it replaces whatever is there.
## What happens in the app
Saves through the API work like saves in the editor:
- A new version is added to the document's history, under the key owner's name.
- Search catches up within a minute or so.
- People and groups you [mention](https://developers.playbookops.ai/guides/markdown#mentions) for the first time get a notification. Mentions already in the previous version don't notify again.
- If people had confirmed they'd reviewed the document, a body change asks them to review it again.
- A body that doesn't actually change doesn't create a version.
## With an AI agent
Over [MCP](https://developers.playbookops.ai/mcp) the same actions are the `create_document` and `update_document` tools, with the same fields. Agents do best when you ask them to read first and patch sections rather than rewrite:
```text
Read the "Refund policy" document. Change the refund window to 60 days and add
an Exceptions section after "Who can ask" saying gift cards can't be refunded.
Use update_document with edits and base_version; don't rewrite the whole document.
```
## Reference
| Action | Endpoint | MCP tool |
| --- | --- | --- |
| Create a document | `POST /v1/playbooks/{playbook_id}/documents` | `create_document` |
| Read a document | `GET /v1/documents/{id}` | `read_document` |
| Change a document | `PATCH /v1/documents/{id}` | `update_document` |
| Find a playbook | `GET /v1/playbooks` | `list_playbooks` |
| Find a document | `GET /v1/content?kinds=document` | `list_content` |
Every field is in the [API reference](https://developers.playbookops.ai/reference/knowledge).
---
# Writing in Markdown
> The Markdown PlaybookOps documents understand, for every kind of content: headings, checklists, tables, callouts, toggles, images, video, mentions and links.
PlaybookOps stores every document as Markdown. What you send to [create or change a document](https://developers.playbookops.ai/guides/documents) is exactly what the editor opens, so anything on this page round-trips: people can edit your document in the app, and you can read it back and patch it again.
It's [GitHub-flavored Markdown](https://github.github.com/gfm/) with a few additions for callouts, toggles, alignment, media and mentions. Where it differs from GitHub, this page says so.
> **Start from the app**
> The quickest way to see the Markdown for something is to make it in the editor and read the document back with `GET /v1/documents/{id}`. The `content` you get is the source.
## Structure
The document's title is its own field, so the body doesn't need to repeat it. Start with a short introduction, then use `##` headings for the main parts.
```markdown
A one-paragraph summary of what this is for and who uses it.
## Before you start
## Steps
### Taking the call
### Logging it
## If something goes wrong
```
- Headings go from `#` to `######`. The toolbar offers four levels, so stick to `##`, `###` and `####` for documents people will edit.
- `##` headings are the sections that [patches](https://developers.playbookops.ai/guides/documents#edits) and the in-app assistant work with. A section includes the smaller headings under it.
- Keep heading names unique where you can. Patches can still reach a repeated name by its path, like `Day two > Steps`.
## Paragraphs and line breaks
A blank line starts a new paragraph. A single line break is kept as a line break, unlike on GitHub, so you can write an address or a short poem line by line.
```markdown
Send returns to:
Acme Warehouse
12 Dock Road
This starts a new paragraph.
```
The editor saves a line break as two spaces at the end of the line. Both forms mean the same thing.
## Text styles
| Style | Markdown |
| --- | --- |
| Bold | `**bold**` |
| Italic | `*italic*` |
| Strikethrough | `~~struck~~` |
| Inline code | `` `code` `` |
| Underline | `underlined` |
| Highlight | `highlighted` |
| Colored highlight | `…`, also `blue`, `pink` or `purple` |
There's no font color. Emoji work as they are (✅ 🚚), but `:shortcodes:` stay as text.
## Lists and checklists
```markdown
- Bullets start with a dash
- Indent two spaces to nest
- Another point
1. Numbered steps
2. Count themselves
- Indent three spaces under a number
- [ ] An open checklist item
- [x] A done one
- [ ] Checklists nest too
```
When someone ticks an item in the editor, it's saved as `[x]`.
## Quotes
```markdown
> Every refund over $500 needs a manager's approval.
> A second line stays in the same quote.
```
## Code
Fence code with three backticks and name the language for coloring.
~~~markdown
```bash
curl https://example.com/health
```
~~~
The editor offers `bash`, `shell`, `powershell`, `python`, `javascript`, `typescript`, `jsx`, `tsx`, `json`, `yaml`, `sql`, `html`, `xml`, `css`, `scss`, `markdown`, `dockerfile`, `java`, `go`, `rust`, `c`, `cpp`, `php`, `ruby`, `swift` and `kotlin`. Use fences rather than indenting code by four spaces.
## Tables
```markdown
| Plan | Refund window | Who approves |
| --- | --- | --- |
| Monthly | 30 days | Support |
| Annual | 60 days | **Finance** |
```
Tables need a header row. Cells hold one line of text with styles, links and mentions, but not lists or several paragraphs. Column alignment (`:---:`) isn't kept once someone edits the document in the app.
## Dividers
A line with `---` on its own, with a blank line above it, draws a divider. Without the blank line it turns the line above into a heading.
## Callouts
Callouts box a note, tip or warning. Open with `:::` and the type, close with `:::` on its own line.
```markdown
:::note
Refunds go back to the original payment method.
:::
:::caution
Don't refund a payment that's still disputed in Stripe.
1. Check the Disputes tab first
2. If there's a dispute, hand it to Finance
:::
```
| Type | Use it for |
| --- | --- |
| `note` | Useful context |
| `tip` | A better way to do something |
| `info` | Background or a reference |
| `caution` | Something that can go wrong |
| `danger` | Something that can't be undone |
A callout can hold anything: paragraphs, lists, tables, code, even another callout. Other types, titles like `:::note[Heads up]` and GitHub's `> [!NOTE]` aren't supported; the title is dropped when the document is edited, and `> [!NOTE]` stays a plain quote.
## Toggles
A toggle hides detail until someone opens it. Put a blank line after `` and before ``.
```markdown
What if the customer paid by bank transfer?
Ask Finance to send the refund. It takes 3 to 5 working days.
```
`` starts it open. The summary is plain text; the body is any Markdown.
## Alignment
Center, right-align or justify paragraphs and headings by wrapping them:
```markdown
:::center
## Welcome to the team
We're glad you're here.
:::
```
Use `center`, `right`, `justify` or `left`. It applies to text, not images or tables, and works inside callouts.
## Links
```markdown
[Stripe dashboard](https://dashboard.stripe.com)
```
Links to other sites open in a new tab. Links to things in PlaybookOps open in the app and show as a chip with the item's live name. Write them as paths, without the domain:
| Link to | Markdown |
| --- | --- |
| A document | `[Refund policy](https://developers.playbookops.ai/playbooks/PLAYBOOK_ID?content=document&contentId=DOCUMENT_ID)` |
| A project | `[Spring launch](https://developers.playbookops.ai/projects/PROJECT_ID)` |
| An item or task | `[Call the venue](https://developers.playbookops.ai/projects/PROJECT_ID?task=ITEM_ID)` |
| A workflow | `[Onboarding](https://developers.playbookops.ai/workflows/WORKFLOW_ID)` |
| A course | `[New starter course](https://developers.playbookops.ai/learning/COURSE_ID)` |
| A flowchart, video or file | `/playbooks/PLAYBOOK_ID?content=flowchart&contentId=ID`, with `image`, `audio`, `video`, `pdf`, `word_document` or `powerpoint` in place of `flowchart` |
The `url` fields the API returns are full links. Drop the `https://app.playbookops.ai` part to get the path.
## Mentions
Mention a person or a group to notify them and show their name as a chip:
```markdown
Questions go to [@Ana Ruiz](mention://user/PERSON_ID) or [@Support team](mention://group/GROUP_ID).
```
- Get people's ids from `GET /v1/people`.
- The name after `@` is what people see on the chip, so use their current name. Leave out `[`, `]`, `(` and `)`.
- People are notified the first time they're mentioned in a document, when you create it or when a change adds them. They must be active members of your organization; other ids are left as text and nobody is notified.
## Images
```markdown

```
- Use a public `https` link. It shows in the app and is included when someone exports the document to PDF or Word.
- Images uploaded in the app live in private storage. When you read a document you get temporary links to them; send them back as they are and they keep working.
- There's no size or alignment option. Images fit the page width.
## Video and audio
```markdown
::media{kind="video" src="https://www.youtube.com/watch?v=VIDEO_ID" title="How to issue a refund"}
::media{kind="audio" src="https://example.com/calls/refund-call.mp3" title="A good refund call"}
```
- `kind` is `video` or `audio`, and `src` must be `https`.
- YouTube, Vimeo and Loom links play in their own player. Other links play as a file, so point them at the video or audio file itself.
- Put each one on its own line. PDF and Word exports don't play media, and show the line as text.
## Not supported
These have no Markdown in PlaybookOps yet. They're kept as text, so nothing is lost, but they won't look special:
- Diagrams, like Mermaid. A `mermaid` code block shows as code; make a flowchart in the playbook and [link to it](#links) instead.
- Math, footnotes, columns and text color.
- Embedded pages (`