The tokidu API
Read your projects and tasks, create tasks from a form or a script and close them from another app. The API goes through the same door as the web: a token never does anything its account couldn't do.
It's part of the Max plan: anyone with Max can use it, and so can anyone working in a project shared by someone with Max. It only reaches those projects.
- Base URL
https://tokidu.com/api/v1- Header
Authorization: Bearer tkd_…- Limits
- 1000 requests per hour per account · 60 per minute per token
- Full reference
- /api/v1/openapi.json
Getting started
- In Account → Integrations, create a token and tick “See your projects and tasks” (and “Create and change tasks”, if it's going to write).
- Copy it, because it's only shown once, and keep it like a password. In the examples it lives in the
TOKIDU_TOKENvariable. - Try it by asking for your account:
curl https://tokidu.com/api/v1/me \
-H "Authorization: Bearer $TOKIDU_TOKEN"Call it from a server or a script, not from a web page: the API doesn't allow CORS and ignores cookies.
Tokens and scopes
When you create a token you choose what it can do, which projects it reaches and when it expires:
read, “See your projects and tasks”: read projects, tasks (with their comments) and “Up next”.write, “Create and change tasks”: create projects and tasks, change them, finish them, cancel them, reopen them and delete them, and create labels, as on the web.- Projects: all you can see or only the ones you tick. If you stop seeing one, the token stops reaching it.
- Expiry: after 30, 90 or 365 days. If you don't choose, after a year.
The Madrugo token (integrations:read) only reads “Up next” for Madrugo, across all the projects you can see: it doesn't open this API and can't be limited to some projects.
You can have 10 active tokens. Revoke them one by one or all at once, and see the latest changes for each one: we keep what changes were made with each token, without the content, for 90 days.
Limits
- 1000 requests per hour for your whole account and 60 per minute for each token.
- Every response carries
RateLimit-Limit,RateLimit-RemainingandRateLimit-Reset: the limit, what's left and when it renews. - If you go over, the response is 429
demasiadas_peticioneswithRetry-After: wait that many seconds and try again. - A request body can take up 64 KiB at most.
Creating tasks without duplicates
Creating a task requires the Idempotency-Key header: 1 to 100 characters, different for each task you want to create (for instance, the id of the row, email or form it comes from).
If you repeat the request with the same key, say after a network drop, no new task is created: you get the one that already exists, with 200 and Idempotent-Replayed: true.
If the task for that key was deleted, no new one is created: the answer is 410 tarea_borrada. If someone restores it from the trash, the same key returns that task again. The same key in another project creates another task.
Errors
An error answers with its HTTP status and the error field in the body; with 422, also field, the field that isn't valid.
- 401
token_invalido - The token is missing, doesn't exist, has been revoked or has expired (it doesn't say which).
- 403
ambito - The token lacks the scope the route asks for.
- 403
proyecto_fuera_del_token - The token is limited to other projects.
- 403
max_necesario - It's part of the Max plan and whoever shares the project doesn't have it (or you don't, when creating a project).
- 403
solo_lectura - In that project you can only look, not change.
- 403
en_pausa - The project is paused: whoever shares it no longer has the Pro plan, so it can only be viewed.
- 404
proyecto_inexistente - The project doesn't exist or you can't see it.
- 404
tarea_inexistente - The task doesn't exist or you can't see it.
- 404
ruta_inexistente - That route isn't part of the API: check the method and the address.
- 404
webhook_inexistente - That notification doesn't exist or this token didn't create it.
- 409
id_ocupado - That
Idempotency-Keybelongs to a task you can't see: use another one. - 409
horas_de_otros - It can't be deleted because it has other people's hours, as on the web.
- 409
adjuntos_de_otros - It can't be deleted because it has other people's files, as on the web.
- 409
entrada_facturada - It can't be deleted because it has hours that were already billed, as in the web app.
- 409
ciclo - That wait would close a loop: a task would end up waiting for itself.
- 409
webhooks_completo - You already have 20 notifications: delete one to create another.
- 409
demasiadas_etiquetas - The project already has as many labels as it can hold (
maxsays how many): delete one on the web or in the app to create another. - 410
tarea_borrada - That
Idempotency-Keybelongs to a task that was deleted: it isn't created again. To create another one, use another key. - 413
cuerpo_grande - The body is over 64 KiB.
- 415
json_necesario - The body has to be JSON, with
Content-Type: application/json. - 422
peticion_invalida - A field isn't valid:
fieldsays which. - 422
url_no_valida - A notification's address isn't valid:
reasonsays why (https,puerto,usuario,local,tokidu,dnsorip_privada). - 428
idempotencia_necesaria - Creating a task needs the
Idempotency-Keyheader. - 429
demasiadas_peticiones - You've gone over the limit: wait as long as
Retry-Aftersays. - 429
demasiados_intentos - You've checked lots of notification addresses in a row: wait for what
Retry-Aftersays. - 503
ocupado - The project was busy with another change: repeat the request after what
Retry-Aftersays. - 503
no_disponible - The service couldn't answer right now: repeat the request after what
Retry-Aftersays.
Reference
Every route hangs off the base URL and answers in JSON. Project and task ids are the ones the API itself returns.
GET /api/v1/me
Your account, the token (name, scopes, projects and expiry) and what's left of the hour.
Scope: any
GET /api/v1/projects
The projects you see from people with Max: name, colour, icon, client, who shares it, your role, traffic light, expected finish, plan snapshot and progress.
Scope: read
GET /api/v1/projects/{id}
One project, with its sprints, its labels and its repeats (tasks that repeat on their own): their schedule, the next time and, if one was skipped, why. Repeats are read-only.
Scope: read
GET /api/v1/projects/{id}/tasks
A project's tasks, without notes: what they wait for (and the extra days of each wait), whether they're blocked, whether they're milestones, their labels, how much of their checklist is ticked, who accompanies them, which repeat they came from and when they're expected to finish. Filter with status (open, done, cancelled or all) and updatedSince, and page with cursor.
Scope: read
curl "https://tokidu.com/api/v1/projects/$PROJECT_ID/tasks?status=open" \
-H "Authorization: Bearer $TOKIDU_TOKEN"GET /api/v1/tasks/{id}
One task with its notes, its checklist, what it waits for (and, if one is done but its extra days haven't passed, when it can start) and “Why that date?”.
Scope: read
GET /api/v1/tasks/{id}/comments
A task's comments, to read: the text, who wrote it and when, in pages starting with the most recent (older ones with cursor). You can't comment through the API.
Scope: read
curl https://tokidu.com/api/v1/tasks/$TASK_ID/comments \
-H "Authorization: Bearer $TOKIDU_TOKEN"GET /api/v1/next
“Up next”: your tasks that can start now. With projectId, only that project's.
Scope: read
GET /api/v1/search
Finds tasks by title, ignoring case and accents, in what you can see: q and, if you like, projectId, status (open, done, cancelled or all) and limit. Open ones first, in “Up next” order.
Scope: read
curl "https://tokidu.com/api/v1/search?q=logo&status=all" \
-H "Authorization: Bearer $TOKIDU_TOKEN"POST /api/v1/projects
Creates a project: name and, if you like, color, icon (one emoji) and client (the client to group it under). Only if you have Max.
Scope: write
POST /api/v1/projects/{id}/tasks
Creates a task: title and, if you like, notes, priority, due, assignee, sprintId, estimateMin, after, labels, milestone, companions (the people who accompany it) and checklist. Requires Idempotency-Key.
Scope: write
curl https://tokidu.com/api/v1/projects/$PROJECT_ID/tasks \
-H "Authorization: Bearer $TOKIDU_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: form-42" \
-d '{"title":"Call Ana","due":"2026-10-20"}'PATCH /api/v1/tasks/{id}
Changes only the fields you send; the checklist, item by item (checklist: tick, rewrite, remove or add, with the ids the task gives), and its companions, always the whole list (companions: read it first and send every name that should stay). Answers with the task, the ones that unlock and, if someone else changed the same thing at the same time, what was kept.
Scope: write
curl -X PATCH https://tokidu.com/api/v1/tasks/$TASK_ID \
-H "Authorization: Bearer $TOKIDU_TOKEN" \
-H "Content-Type: application/json" \
-d '{"due":"2026-10-24"}'POST /api/v1/tasks/{id}/done
Marks the task as done (a cancelled one too) and answers with the ones that unlock.
Scope: write
curl -X POST https://tokidu.com/api/v1/tasks/$TASK_ID/done \
-H "Authorization: Bearer $TOKIDU_TOKEN"POST /api/v1/tasks/{id}/reopen
Reopens a finished or cancelled task.
Scope: write
POST /api/v1/tasks/{id}/cancel
Cancels the task: it's closed without counting as done, and the ones waiting for it can start. Answers with the ones that unlock.
Scope: write
curl -X POST https://tokidu.com/api/v1/tasks/$TASK_ID/cancel \
-H "Authorization: Bearer $TOKIDU_TOKEN"PUT /api/v1/tasks/{id}/after/{otherId}
Makes the task wait for another one in the same project or in another project of the same owner (afterOutside). With days in the body, it also waits that many days after the other one is done (1 to 365; 0 removes them).
Scope: write
curl -X PUT https://tokidu.com/api/v1/tasks/$TASK_ID/after/$OTHER_ID \
-H "Authorization: Bearer $TOKIDU_TOKEN" \
-H "Content-Type: application/json" \
-d '{"days":2}'DELETE /api/v1/tasks/{id}/after/{otherId}
Removes that wait.
Scope: write
DELETE /api/v1/tasks/{id}
Deletes the task, as on the web: it spends 30 days in the trash, where it can be restored from the web.
Scope: write
GET /api/v1/projects/{id}/labels
The project's labels, in alphabetical order: id, name and colour.
Scope: read
POST /api/v1/projects/{id}/labels
Creates a label in the project: name and, if you like, color. If there's already one with that name, answers with that one.
Scope: write
GET /api/v1/webhooks
The notifications to other apps this token has created: address, events, projects and status (never the secret).
Scope: webhooks
POST /api/v1/webhooks
Registers an https address to receive signed notifications: url, events and, optionally, projects (your own only). Answers with the secret, just once.
Scope: webhooks
DELETE /api/v1/webhooks/{id}
Deletes one of the notifications this token created and stops sending it.
Scope: webhooks
Notifications to other apps (webhooks)
When something happens in your projects, tokidu sends a signed POST to the address you give. Create them in Account → Integrations, or through the API with a token with the webhooks scope (what Zapier or Make use). Only the owner with Max, and only for their own projects; up to 20 per account.
What you can listen to
task.created· A task is createdtask.done· A task is donetask.cancelled· A task is cancelledtask.reopened· A task is reopenedtask.unblocked· A task is unlockedtask.assigned· A task is assignedtask.deleted· A task is deletedcomment.created· Someone comments on a taskproject.status· A project's traffic light changesproject.duplicated· A project is duplicatedproject.imported· A project is imported
Each notification carries the type, an id for the event, the time, the project and, for a task, its title, status, whether it was cancelled, whether it's a milestone, its labels, the names of its assignee and of the people who accompany it, its deadline and link. Tasks created by a repeat arrive like any new task (task.created). Never notes, links, files, emails or hours. For a comment, only who wrote it: never the text.
Checking the signature
It follows Standard Webhooks: headers webhook-id, webhook-timestamp (seconds) and webhook-signature (v1, and a base64 HMAC-SHA256 of id.timestamp.body, with the key after whsec_). Check it against the body exactly as it arrives and reject anything older than 5 minutes. In Node:
import { createHmac, timingSafeEqual } from "node:crypto";
export function verifyTokidu(secret, headers, body, toleranceSeconds = 300) {
const id = headers["webhook-id"], ts = headers["webhook-timestamp"], sigs = headers["webhook-signature"];
if (!id || !ts || !sigs) return false;
if (Math.abs(Date.now() / 1000 - Number(ts)) > toleranceSeconds) return false;
const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
const expected = createHmac("sha256", key).update(`${id}.${ts}.${body}`).digest();
return sigs.split(" ").some((s) => {
const [version, sig] = s.split(",");
const given = Buffer.from(sig ?? "", "base64");
return version === "v1" && given.length === expected.length && timingSafeEqual(given, expected);
});
}Delivery and retries
Any 2xx is fine; redirects aren't followed. If it fails, it's retried after 1 min, 5 min, 30 min, 2 h, 6 h, 12 h and 24 h. After 20 failed deliveries in a row, or 3 days without a 2xx, the notification is turned off and we email you.
Only public https:// addresses, on port 443 or 8443, with no user or password: no localhost, internal networks or private IPs (also checked when sending).
AI agents (MCP)
With MCP (Model Context Protocol), an AI agent such as Claude Code can use tokidu for you: tell you what's yours to do, find tasks, read their comments and, if the token allows it, create, change, finish and cancel them. It runs on this API with the same token: the agent never does anything that token couldn't do.
- URL
https://tokidu.com/api/mcp- Header
Authorization: Bearer tkd_…
Connecting Claude Code
Create a token in Account → Integrations and paste this into the terminal, with your token instead of tkd_…:
claude mcp add --transport http tokidu https://tokidu.com/api/mcp \
--header "Authorization: Bearer tkd_…"In any other client that lets you set a header, use the same URL and the same header.
What the token allows
read, “See your projects and tasks”: connect the agent and use the tools that read.write, “Create and change tasks”: also the ones that create and change tasks and waits.- If the token only reaches some projects, the agent only sees those. The Madrugo token (
integrations:read) doesn't work for MCP.
Tools
Each one needs a token scope. The names are in English, as is usual in MCP.
list_projects- The projects the token can see, with their client, traffic light, expected finish and plan snapshot.Scope:
read next_up- “Up next”: your tasks that can start now, across all projects or in one.Scope:
read get_project- One project, its labels, its repeats and its open tasks: when they're expected to finish, whether they're blocked, the extra days of their waits, which ones are milestones, who accompanies them and how much of their checklist is ticked.Scope:
read get_task- One task with its notes, its checklist, who accompanies it, which repeat it came from, what it waits for (and when it can start, if a wait's extra days haven't passed) and “Why that date?”.Scope:
read list_comments- A task's comments, to read: the text, who wrote it and when. No tool writes comments.Scope:
read search_tasks- Finds tasks by title in the projects the token can see.Scope:
read create_task- Creates a task (or a milestone), with its checklist and companions too. If the client repeats the same request within the same 10-minute block of the clock, it isn't duplicated; to retry safely, it should send
idempotency_key.Scope:write update_task- Changes only the task fields it sends (its labels too, whether it's a milestone, its companions, always the whole list, and, item by item, its checklist).Scope:
write complete_task- Marks the task as done and says which ones unlock.Scope:
write cancel_task- Cancels a task that won't be done: it doesn't count as done, and it says which ones unlock.Scope:
write add_wait- Makes one task wait for another and, with
days, also wait a few days after it's done.Scope:write remove_wait- Removes a wait.Scope:
write
Good to know
- There are no tools to delete tasks or projects or to write comments, nor to create or change repeats, nor for people, invitations, hours, files or notifications to other apps. But
update_taskcan change or empty a task's fields (notes don't keep earlier versions),add_waitwithdayschanges or removes a wait's extra days andremove_waitremoves waits: only give the tokenwriteif you want that. - It shares the API's limits (1000 requests per hour per account, 60 per minute per token): each tool is one API call (
get_project, two) and counts towards both; everything else the client sends (initialize,tools/list,ping,server/discover, notifications and tool calls that don't reach the API because some data isn't valid) counts towards the minute, but not the hour. - “Latest changes with this token” shows, marked MCP, the changes it makes and refused attempts (401, 403 and 429, at most one a minute); not what it only reads.
- Titles, notes, checklist items, comments and names are written by people: tokidu gives them to the agent as data, in their own fields and, inside the “Why that date?” and traffic light sentences, between “” quotes, and tells it they're never instructions.
- There's no OAuth yet, so tokidu can't be added as a connector in claude.ai. It works in Claude Code and in any client that lets you set a header.
- No session: each request is a
POSTwith JSON-RPC and the answer is always JSON. - Protocol versions: the modern one and, for older clients, the ones that start with
initialize:2026-07-28,2025-11-25,2025-06-18,2025-03-26.
OpenAPI
Every field of every request and response, in OpenAPI format, to generate a client or import them into your tool: /api/v1/openapi.json.