Developer access
Your workspace, connected.
Read your personal tasks, projects and bookmarks from your own scripts or an MCP client.
Get started
- Sign in and open Settings → API & MCP access.
- Name the key, choose read permissions and an expiry of 7, 30 or 90 days.
- Copy the secret once and send it in the
Authorization: Bearerheader. Keep it out of URLs and source control.
Keys can only read records you personally own. Group workspaces are excluded. Revocation takes effect on subsequent requests. At most 10 active keys per account.
REST reference
| Request | Permission | Result |
|---|---|---|
| GET /api/v1/tasks | tasks:read | Task title, status, dates, project and description |
| GET /api/v1/projects | projects:read | Project name, status, dates and description |
| GET /api/v1/bookmarks | bookmarks:read | Bookmark title, URL and description |
Use limit (1–100; default 25) and offset (0–10,000; default 0). Records are sorted by ID. Read next_offset until it is null. A final page can be empty.
Titles are limited to 500 characters and descriptions to 4,000. Bookmark URLs are limited to 4,000. This API returns record summaries.
curl 'https://todolisthelper.com/api/v1/tasks?limit=25' \ -H "Authorization: Bearer $TODOLISTHELPER_API_KEY"
Download the OpenAPI 3.1 specification to import into Swagger UI, Postman or another API client.
Try a read request
Your key stays in this page’s memory and is sent only to this site. Results show your private data. Clear the form when finished.
Connect an MCP client
Use a client that supports Streamable HTTP and a manually configured bearer header. Enter the server URL below and use the same API key as for REST. OAuth discovery and a sign-in flow for MCP clients are not available in this release.
URL: https://todolisthelper.com/api/mcp Authorization: Bearer <your API key> Transport: Streamable HTTP (JSON responses)
Available tools are list_tasks, list_projects and list_bookmarks, filtered by your key’s permissions. Each accepts optional limit and offset.
Protocol details
Supported versions: 2025-11-25, 2025-06-18 and 2025-03-26. Send initialization first, then notifications/initialized. POST requests need application/json Content-Type and Accept: application/json, text/event-stream. Later requests should carry the negotiated MCP-Protocol-Version header. Methods: initialize, ping, tools/list, tools/call. This stateless server returns JSON; GET streaming and DELETE sessions return 405. Requests with a foreign Origin are rejected.
Limits and errors
Each key allows 60 authenticated operations per minute, shared across REST and MCP. Retry HTTP 429 after the number of seconds in Retry-After.
400: invalid input. 401: missing, expired, revoked or invalid key, or disabled account. 403: missing permission or invalid Origin. 503: access temporarily unavailable. Responses use {"error":"code"}; MCP protocol errors use JSON-RPC and permission failures in a tool call use isError.
Successful operations update last-used time. An audit records key, operation and status, without record bodies or secrets. Entries older than 30 days are removed when the account next uses a key. Revoked/expired credentials never expose data.