Lists

Shopping and to-do lists and their items.

List lists#

GET/workspaces/{workspaceId}/listsscope lists:readMCP 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#

Shell

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/workspaces/{workspaceId}/listsscope lists:writeMCP 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#

Shell

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/workspaces/{workspaceId}/lists/{listId}scope lists:writeMCP 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#

Shell

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/workspaces/{workspaceId}/lists/{listId}scope lists:writeMCP delete_list

Deletes the list with all its items.

Path#

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

Request#

Shell

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/workspaces/{workspaceId}/lists/{listId}/itemsscope lists:readMCP 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#

Shell

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/workspaces/{workspaceId}/lists/{listId}/itemsscope lists:writeMCP 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#

Shell

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/workspaces/{workspaceId}/lists/{listId}/items/{itemId}scope lists:writeMCP 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#

Shell

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/workspaces/{workspaceId}/lists/{listId}/items/{itemId}scope lists:writeMCP delete_item

Removes the item from the list.

Path#

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

Request#

Shell

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
}

Lists

List lists#

Path#

Request#

Response 200#

Create a list#

Path#

Body#

Request#

Response 201#

Rename a list#

Path#

Body#

Request#

Response 200#

Delete a list#

Path#

Request#

Response 200#

List items#

Path#

Query#

Request#

Response 200#

Add items#

Path#

Body#

Request#

Response 201#

Change or tick off an item#

Path#

Body#

Request#

Response 200#

Remove an item#

Path#

Request#

Response 200#

Response `200`#

Response `201`#

Response `200`#

Response `200`#

Response `200`#

Response `201`#

Response `200`#

Response `200`#