Developer documentation

REST API and MCP tools for building with ListBot.

Just connecting your AI assistant?

Follow the setup guide

API reference

The app itself runs on this API. Base URL: https://listbot.uk/api/public/v1. Responses are { data } or { error }.

Your lists

Send Authorization: Bearer <access token> — an OAuth access token issued to your account.

GET/lists?archived=true|falseList your lists with done/total counts

POST/listsCreate a list — { "title": "Groceries", "notes"?: "..." }

GET/lists/:idGet a list with its todos and share_token

PATCH/lists/:id{ "title"?, "archived"?: true|false, "regenerate_share_token"?: true, "notes"?: "..." }

DELETE/lists/:idDelete a list and its todos

POST/lists/:id/todosAdd an entry — { "title": "Milk", "row_type"?: "task"|"header"|"note", "notes"?: "...", "sort_order"?: number }

PATCH/todos/:id{ "title"?, "done"?: true|false, "row_type"?, "notes"?, "sort_order"? }

DELETE/todos/:idDelete a todo

GET/encryptionAccount encryption status and remaining legacy payload count

POST/encryption{ "action": "enable", "passphrase": "..." } | { "action": "rotate", "current": "...", "passphrase": "..." } | { "action": "migrate" }

Account encryption uses server-managed AES-256-GCM payloads. REST and MCP still return authorised plaintext. Passphrases require 12–256 characters and protect a wrapped account key; rotation leaves content ciphertext unchanged. Enable, then call migrate until remaining is zero. Password-locked lists must be unlocked to migrate. Operational metadata and historical backups are not covered by the application-content encryption claim.

Set a password with PATCH /lists/:id using password and password_scope (shared or all). Send password: null to remove it. All-access protection applies to owner reads, edits and deletes too. Supply the current password in the X-List-Password header; missing or incorrect passwords return 423. Password settings updates return only id and password_scope. Locked catalog entries redact content. Passwords are never returned.

Entries stay in sort_order, then creation order. Omit sort_order to append, or use a number between neighbours to insert. Only task entries count toward progress and can be completed. Headers and notes retain their position when tasks are ticked off. Notes may contain up to 10,000 characters; entry text up to 500.

Shared lists — no auth

The token is the last part of a share link (/s/:token). Archived lists are read-only.

GET/shared/:tokenRead a shared list

POST/shared/:token/todosAdd a todo — { "title": "..." }

PATCH/shared/:token/todos/:todoId{ "done": true|false }

Protected shared links require X-List-Password on every read or edit. Never put a password in the URL.

MCP tool reference

Connect Claude, ChatGPT, Cursor or any MCP client to https://listbot.uk/mcp. You'll sign in and approve access; the assistant then works with your lists.

Tools: list_lists, get_list, create_list, update_list (rename / archive), delete_list, add_todo, update_todo (mark done, edit notes / headers / order), delete_todo, set_list_password. All-access protected tools accept password; set_list_password takes new_password (null removes it) and password_scope (shared or all).

curl https://listbot.uk/api/public/v1/shared/<token>