# Lists – API reference

> Shopping and to-do lists and their items.

Shopping and to-do lists and their items.

## List lists

**`GET https://api.lifebutler.io/v1/workspaces/{workspaceId}/lists`** · scope `lists:read` · MCP tool `list_lists`

All shopping and to-do lists of the workspace, oldest first (like in the app).

### Path

| Field | Type | Description |
|---|---|---|
| `workspaceId` | string | Workspace id (from list_workspaces). |

### Request

```bash
curl "https://api.lifebutler.io/v1/workspaces/f8Hn3wQz0a/lists" \
  -H "Authorization: Bearer $LIFEBUTLER_KEY"
```

### Response `200`

| Field | Type | Description |
|---|---|---|
| `data` | array of List |  |
| `data[].id` | string |  |
| `data[].name` | string |  |
| `data[].type` | `shopping` \| `todo` |  |
| `data[].openCount` | integer | Items not ticked off yet. |
| `data[].createdAt` | string or null |  |

```json
{
  "data": [
    {
      "id": "Ab3Cd5Ef7G",
      "name": "Einkauf",
      "type": "shopping",
      "openCount": 3,
      "createdAt": "2026-11-20T19:30:00+01:00"
    }
  ]
}
```

## Create a list

**`POST https://api.lifebutler.io/v1/workspaces/{workspaceId}/lists`** · scope `lists:write` · MCP tool `create_list`

A new, empty list.

### Path

| Field | Type | Description |
|---|---|---|
| `workspaceId` | string | Workspace id (from list_workspaces). |

### Body

| Field | Type | Description |
|---|---|---|
| `name` *(required)* | string |  |
| `type` | `shopping` \| `todo` | Default: `"shopping"`. |

### Request

```bash
curl -X POST "https://api.lifebutler.io/v1/workspaces/f8Hn3wQz0a/lists" \
  -H "Authorization: Bearer $LIFEBUTLER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Einkauf"}'
```

### Response `201`

| Field | Type | Description |
|---|---|---|
| `id` | string |  |
| `name` | string |  |
| `type` | `shopping` \| `todo` |  |
| `openCount` | integer | Items not ticked off yet. |
| `createdAt` | string or null |  |

```json
{
  "id": "Ab3Cd5Ef7G",
  "name": "Einkauf",
  "type": "shopping",
  "openCount": 3,
  "createdAt": "2026-11-20T19:30:00+01:00"
}
```

## Rename a list

**`PATCH https://api.lifebutler.io/v1/workspaces/{workspaceId}/lists/{listId}`** · scope `lists:write` · MCP tool `update_list`

Changes the list's name.

### Path

| Field | Type | Description |
|---|---|---|
| `workspaceId` | string | Workspace id (from list_workspaces). |
| `listId` | string |  |

### Body

| Field | Type | Description |
|---|---|---|
| `name` *(required)* | string |  |

### Request

```bash
curl -X PATCH "https://api.lifebutler.io/v1/workspaces/f8Hn3wQz0a/lists/Ls2Wq7Hd5N" \
  -H "Authorization: Bearer $LIFEBUTLER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Einkauf"}'
```

### Response `200`

| Field | Type | Description |
|---|---|---|
| `id` | string |  |
| `name` | string |  |
| `type` | `shopping` \| `todo` |  |
| `openCount` | integer | Items not ticked off yet. |
| `createdAt` | string or null |  |

```json
{
  "id": "Ab3Cd5Ef7G",
  "name": "Einkauf",
  "type": "shopping",
  "openCount": 3,
  "createdAt": "2026-11-20T19:30:00+01:00"
}
```

## Delete a list

**`DELETE https://api.lifebutler.io/v1/workspaces/{workspaceId}/lists/{listId}`** · scope `lists:write` · MCP tool `delete_list`

Deletes the list with all its items.

### Path

| Field | Type | Description |
|---|---|---|
| `workspaceId` | string | Workspace id (from list_workspaces). |
| `listId` | string |  |

### Request

```bash
curl -X DELETE "https://api.lifebutler.io/v1/workspaces/f8Hn3wQz0a/lists/Ls2Wq7Hd5N" \
  -H "Authorization: Bearer $LIFEBUTLER_KEY"
```

### Response `200`

| Field | Type | Description |
|---|---|---|
| `id` | string |  |
| `deleted` | `true` |  |

```json
{
  "id": "Ab3Cd5Ef7G",
  "deleted": false
}
```

## List items

**`GET https://api.lifebutler.io/v1/workspaces/{workspaceId}/lists/{listId}/items`** · scope `lists:read` · MCP tool `list_items`

The items of a list, newest first. Ticked-off items only with includeChecked.

### Path

| Field | Type | Description |
|---|---|---|
| `workspaceId` | string | Workspace id (from list_workspaces). |
| `listId` | string |  |

### Query

| Field | Type | Description |
|---|---|---|
| `includeChecked` | boolean or `true` \| `false` | Also return ticked-off items. |

### Request

```bash
curl "https://api.lifebutler.io/v1/workspaces/f8Hn3wQz0a/lists/Ls2Wq7Hd5N/items" \
  -H "Authorization: Bearer $LIFEBUTLER_KEY"
```

### Response `200`

| Field | Type | Description |
|---|---|---|
| `list` | List | A shared list (shopping or to-do). |
| `list.id` | string |  |
| `list.name` | string |  |
| `list.type` | `shopping` \| `todo` |  |
| `list.openCount` | integer | Items not ticked off yet. |
| `list.createdAt` | string or null |  |
| `data` | array of ListItem |  |
| `data[].id` | string |  |
| `data[].text` | string |  |
| `data[].checked` | boolean |  |
| `data[].category` | string | Shopping aisle (dairy, produce, …) or other. |
| `data[].createdBy` | string or null |  |
| `data[].checkedBy` | string or null |  |
| `data[].createdAt` | string or null |  |

```json
{
  "list": {
    "id": "Ab3Cd5Ef7G",
    "name": "Einkauf",
    "type": "shopping",
    "openCount": 3,
    "createdAt": "2026-11-20T19:30:00+01:00"
  },
  "data": [
    {
      "id": "Ab3Cd5Ef7G",
      "text": "Milch",
      "checked": false,
      "category": "string",
      "createdBy": "string",
      "checkedBy": "string",
      "createdAt": "2026-11-20T19:30:00+01:00"
    }
  ]
}
```

## Add items

**`POST https://api.lifebutler.io/v1/workspaces/{workspaceId}/lists/{listId}/items`** · scope `lists:write` · MCP tool `add_items`

Adds one or more items, e.g. ["Milch", "Eier (10)"].

### Path

| Field | Type | Description |
|---|---|---|
| `workspaceId` | string | Workspace id (from list_workspaces). |
| `listId` | string |  |

### Body

| Field | Type | Description |
|---|---|---|
| `items` *(required)* | array of string |  |

### Request

```bash
curl -X POST "https://api.lifebutler.io/v1/workspaces/f8Hn3wQz0a/lists/Ls2Wq7Hd5N/items" \
  -H "Authorization: Bearer $LIFEBUTLER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items": ["string"]}'
```

### Response `201`

| Field | Type | Description |
|---|---|---|
| `data` | array of ListItem |  |
| `data[].id` | string |  |
| `data[].text` | string |  |
| `data[].checked` | boolean |  |
| `data[].category` | string | Shopping aisle (dairy, produce, …) or other. |
| `data[].createdBy` | string or null |  |
| `data[].checkedBy` | string or null |  |
| `data[].createdAt` | string or null |  |

```json
{
  "data": [
    {
      "id": "Ab3Cd5Ef7G",
      "text": "Milch",
      "checked": false,
      "category": "string",
      "createdBy": "string",
      "checkedBy": "string",
      "createdAt": "2026-11-20T19:30:00+01:00"
    }
  ]
}
```

## Change or tick off an item

**`PATCH https://api.lifebutler.io/v1/workspaces/{workspaceId}/lists/{listId}/items/{itemId}`** · scope `lists:write` · MCP tool `update_item`

Send checked: true to tick an item off (false to untick), text to rename it.

### Path

| Field | Type | Description |
|---|---|---|
| `workspaceId` | string | Workspace id (from list_workspaces). |
| `listId` | string |  |
| `itemId` | string |  |

### Body

| Field | Type | Description |
|---|---|---|
| `text` | string |  |
| `checked` | boolean |  |

### Request

```bash
curl -X PATCH "https://api.lifebutler.io/v1/workspaces/f8Hn3wQz0a/lists/Ls2Wq7Hd5N/items/It9Fv3Jb6M" \
  -H "Authorization: Bearer $LIFEBUTLER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"checked": false}'
```

### Response `200`

| Field | Type | Description |
|---|---|---|
| `id` | string |  |
| `text` | string |  |
| `checked` | boolean |  |
| `category` | string | Shopping aisle (dairy, produce, …) or other. |
| `createdBy` | string or null |  |
| `checkedBy` | string or null |  |
| `createdAt` | string or null |  |

```json
{
  "id": "Ab3Cd5Ef7G",
  "text": "Milch",
  "checked": false,
  "category": "string",
  "createdBy": "string",
  "checkedBy": "string",
  "createdAt": "2026-11-20T19:30:00+01:00"
}
```

## Remove an item

**`DELETE https://api.lifebutler.io/v1/workspaces/{workspaceId}/lists/{listId}/items/{itemId}`** · scope `lists:write` · MCP tool `delete_item`

Removes the item from the list.

### Path

| Field | Type | Description |
|---|---|---|
| `workspaceId` | string | Workspace id (from list_workspaces). |
| `listId` | string |  |
| `itemId` | string |  |

### Request

```bash
curl -X DELETE "https://api.lifebutler.io/v1/workspaces/f8Hn3wQz0a/lists/Ls2Wq7Hd5N/items/It9Fv3Jb6M" \
  -H "Authorization: Bearer $LIFEBUTLER_KEY"
```

### Response `200`

| Field | Type | Description |
|---|---|---|
| `id` | string |  |
| `deleted` | `true` |  |

```json
{
  "id": "Ab3Cd5Ef7G",
  "deleted": false
}
```