API & MCP

The app itself runs on this API. Base URL: https://listful.reformtools.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

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 }

MCP server

Connect Claude, ChatGPT, Cursor or any MCP client to https://listful.reformtools.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.

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