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

  1. 1

    Find the project

    GET /v1/projects lists 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. 2

    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.

    curl https://developers.playbookops.ai/v1/projects/PROJECT_ID \
      -H "Authorization: Bearer $PLAYBOOKOPS_API_KEY"
    
  3. 3

    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:

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

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

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

ActionEndpointMCP tool
List projectsGET /v1/projectslist_projects
Groups and columnsGET /v1/projects/{id}get_project
List itemsGET /v1/projects/{id}/itemslist_items
Search itemsGET /v1/items/searchsearch_items
One itemGET /v1/items/{id}get_item
Add an itemPOST /v1/projects/{id}/itemscreate_item
Update an itemPATCH /v1/items/{id}update_item
Move an itemPOST /v1/items/{id}/movemove_item
Complete or reopenPOST /v1/items/{id}/completecomplete_item
UpdatesGET and POST /v1/items/{id}/commentslist_item_comments, add_item_comment

Every parameter is in the API reference.