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