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
- 1
Find the project
GET /v1/projectslists the projects the key's owner owns or is a member of.curl https://developers.playbookops.ai/v1/projects \ -H "Authorization: Bearer $PLAYBOOKOPS_API_KEY" - 2
Learn its groups and columns
GET /v1/projects/PROJECT_IDreturns the groups in board order and every column with its type and, for select columns, its options.curl https://developers.playbookops.ai/v1/projects/PROJECT_ID \ -H "Authorization: Bearer $PLAYBOOKOPS_API_KEY" - 3
Read the items
GET /v1/projects/PROJECT_ID/itemsreturns items in board order. Filter by group, by title, and by whether they're done: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_dateandpriorityare top-level fields on each item. Custom column values are invalues, keyed by column id. Use the project'scolumnsto 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 -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" }
}'
- Without
group_id, the item goes in the project's first group. - With
parent_id, it's a subitem, in its parent's group. valuestakes column ids or column keys, and each value is checked against its column's type, as in the app.assignee_idis a person'sidfromGET /v1/people.
Update an item
PATCH /v1/items/ITEM_ID changes only the fields you send. Send null to clear one:
{ "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
# 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.
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.
Archive or delete it
POST /v1/items/ITEM_ID/archive archives an item and its subitems. They drop out of the project's lists, and the item's archived_at is set. List them with GET /v1/projects/PROJECT_ID/items?archived=true, and bring one back with POST /v1/items/ITEM_ID/restore.
DELETE /v1/items/ITEM_ID removes the item, its subitems and its updates for good. The answer is {"id": "ITEM_ID", "deleted": true}.
Archive unless the item should be gone completely. Send an Idempotency-Key with deletes too: a retry with the same key gets the first answer instead of a 404. Over MCP, delete_item is marked as destructive, so clients that ask before running such tools will ask.
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 |
| Archive an item | POST /v1/items/{id}/archive | archive_item |
| Restore an item | POST /v1/items/{id}/restore | restore_item |
| Delete an item | DELETE /v1/items/{id} | delete_item |
Every parameter is in the API reference.