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