L’API de tokidu
Llegeix els teus projectes i tasques, crea tasques des d’un formulari o un script i tanca-les des d’una altra app. L’API passa per la mateixa porta que el web: un token mai fa res que no pugui fer el seu compte.
És del pla Max: la pot fer servir qui té Max i qui treballa en un projecte que comparteix algú amb Max, i només arriba a aquests projectes.
- Adreça base
https://tokidu.com/api/v1- Capçalera
Authorization: Bearer tkd_…- Límits
- 1000 peticions per hora i compte · 60 per minut i token
- Referència completa
- /api/v1/openapi.json
Començar
- A Compte → Integracions, crea un token i marca «Veure els teus projectes i tasques» (i «Crear i canviar tasques», si ha d’escriure).
- Copia’l, perquè només es mostra una vegada, i guarda’l com una contrasenya. Als exemples va a la variable
TOKIDU_TOKEN. - Prova’l demanant el teu compte:
curl https://tokidu.com/api/v1/me \
-H "Authorization: Bearer $TOKIDU_TOKEN"Crida-la des d’un servidor o un script, no des d’una pàgina web: l’API no admet CORS i no mira les galetes.
Tokens i àmbits
En crear un token tries què pot fer, a quins projectes arriba i quan caduca:
read, «Veure els teus projectes i tasques»: llegir els projectes, les tasques (amb els seus comentaris) i «El següent».write, «Crear i canviar tasques»: crear projectes i tasques, canviar-les, acabar-les, cancel·lar-les, reobrir-les i esborrar-les, i crear etiquetes, com al web.- Projectes: tots els que veus o només els que marquis. Si en deixes de veure un, el token deixa d’arribar-hi.
- Caducitat: als 30, 90 o 365 dies. Si no tries, a l’any.
El token de Madrugo (integrations:read) només llegeix «El següent» per a Madrugo, de tots els projectes que veus: no obre aquesta API i no es pot limitar a uns quants projectes.
Pots tenir 10 tokens actius. Revoca’ls d’un en un o tots alhora, i mira a cadascun els últims canvis: guardem quins canvis s’han fet amb cada token, sense el contingut, durant 90 dies.
Límits
- 1000 peticions per hora per a tot el teu compte i 60 per minut per a cada token.
- Cada resposta porta
RateLimit-Limit,RateLimit-RemainingiRateLimit-Reset: el límit, el que queda i quan es renova. - Si te’n passes, la resposta és 429
demasiadas_peticionesambRetry-After: espera aquests segons i torna a provar. - El cos d’una petició pot ocupar 64 KiB com a molt.
Crear tasques sense duplicar-les
Crear una tasca exigeix la capçalera Idempotency-Key: d’1 a 100 caràcters, diferent per a cada tasca que vols crear (per exemple, l’id de la fila, del correu o del formulari d’on surt).
Si repeteixes la petició amb la mateixa clau, per exemple després d’un tall de xarxa, no se’n crea una altra: et torna la que ja existeix, amb 200 i Idempotent-Replayed: true.
Si la tasca d’aquesta clau es va esborrar, no se’n crea cap altra: la resposta és 410 tarea_borrada. Si algú la restaura des de la paperera, la mateixa clau torna a retornar aquesta tasca. La mateixa clau en un altre projecte crea una altra tasca.
Errors
Un error respon amb el seu codi HTTP i el camp error del cos; amb 422, també field, el camp que no és vàlid.
- 401
token_invalido - Falta el token, no existeix, està revocat o ha caducat (no es diu quin cas és).
- 403
ambito - Al token li falta l’àmbit que demana la ruta.
- 403
proyecto_fuera_del_token - El token està limitat a altres projectes.
- 403
max_necesario - És del pla Max i qui comparteix el projecte no el té (o tu, en crear un projecte).
- 403
solo_lectura - En aquest projecte només pots veure, no canviar.
- 403
en_pausa - El projecte està en pausa: qui el comparteix ja no té el pla Pro, així que només es pot veure.
- 404
proyecto_inexistente - El projecte no existeix o no el veus.
- 404
tarea_inexistente - La tasca no existeix o no la veus.
- 404
ruta_inexistente - Aquesta ruta no és de l'API: revisa el mètode i l'adreça.
- 404
webhook_inexistente - Aquest avís no existeix o no el va crear aquest token.
- 409
id_ocupado - Aquesta
Idempotency-Keycorrespon a una tasca que no veus: fes-ne servir una altra. - 409
horas_de_otros - No es pot esborrar perquè té hores d’altres persones, com al web.
- 409
adjuntos_de_otros - No es pot esborrar perquè té fitxers d’altres persones, com al web.
- 409
entrada_facturada - No es pot esborrar perquè té hores ja facturades, com a la web.
- 409
ciclo - Aquesta espera tancaria un cercle: una tasca acabaria esperant-se a si mateixa.
- 409
webhooks_completo - Ja tens 20 avisos: esborra'n algun per crear-ne un altre.
- 409
demasiadas_etiquetas - El projecte ja té totes les etiquetes que hi caben (
maxdiu quantes): esborra’n alguna al web o a l’app per crear-ne una altra. - 410
tarea_borrada - Aquesta
Idempotency-Keyés d’una tasca que es va esborrar: no es torna a crear. Per crear-ne una altra, fes servir una altra clau. - 413
cuerpo_grande - El cos passa de 64 KiB.
- 415
json_necesario - El cos ha d’anar en JSON, amb
Content-Type: application/json. - 422
peticion_invalida - Un camp no és vàlid:
fielddiu quin. - 422
url_no_valida - L'adreça d'un avís no és vàlida:
reasondiu per què (https,puerto,usuario,local,tokidu,dnsoip_privada). - 428
idempotencia_necesaria - Per crear una tasca falta la capçalera
Idempotency-Key. - 429
demasiadas_peticiones - Has passat del límit: espera el que digui
Retry-After. - 429
demasiados_intentos - Has comprovat moltes adreces d'avisos seguides: espera el que digui
Retry-After. - 503
ocupado - El projecte estava ocupat amb un altre canvi: repeteix la petició passat el que digui
Retry-After. - 503
no_disponible - El servei no ha pogut respondre ara: repeteix la petició passat el que digui
Retry-After.
Referència
Totes les rutes van darrere de l’adreça base i responen en JSON. Els ids de projectes i tasques són els que torna la mateixa API.
GET /api/v1/me
El teu compte, el token (nom, àmbits, projectes i caducitat) i el que et queda de l’hora.
Àmbit: qualsevol
GET /api/v1/projects
Els projectes que veus de qui té Max: nom, color, icona, client, qui el comparteix, el teu paper, semàfor, final previst, foto del pla i avanç.
Àmbit: read
GET /api/v1/projects/{id}
Un projecte, amb els seus sprints, les seves etiquetes i les seves repeticions (les tasques que es repeteixen soles): l’horari, la propera vegada i, si se n’ha saltat alguna, per què. Les repeticions només es llegeixen.
Àmbit: read
GET /api/v1/projects/{id}/tasks
Les tasques d’un projecte, sense notes: què esperen (i els dies de més de cada espera), si estan bloquejades, si són fites, les seves etiquetes, quant porten marcat de la seva llista de comprovació, qui les acompanya, de quina repetició han sortit i quan es preveu que acabin. Filtra amb status (open, done, cancelled o all) i updatedSince, i passa de pàgina amb cursor.
Àmbit: read
curl "https://tokidu.com/api/v1/projects/$PROJECT_ID/tasks?status=open" \
-H "Authorization: Bearer $TOKIDU_TOKEN"GET /api/v1/tasks/{id}
Una tasca amb les seves notes, la seva llista de comprovació, què espera (i, si ja n’ha acabat una i en falten els dies, des de quan podrà començar) i «Per què aquesta data?».
Àmbit: read
GET /api/v1/tasks/{id}/comments
Els comentaris d’una tasca, per llegir-los: el text, qui l’ha escrit i quan, per pàgines des dels més recents (els anteriors, amb cursor). Per l’API no es pot comentar.
Àmbit: read
curl https://tokidu.com/api/v1/tasks/$TASK_ID/comments \
-H "Authorization: Bearer $TOKIDU_TOKEN"GET /api/v1/next
«El següent»: el que és teu i ja es pot començar. Amb projectId, només el d’aquest projecte.
Àmbit: read
GET /api/v1/search
Cerca tasques pel títol, sense mirar majúscules ni accents, en el que veus: q i, si vols, projectId, status (open, done, cancelled o all) i limit. Primer les obertes, en l’ordre d’«El següent».
Àmbit: read
curl "https://tokidu.com/api/v1/search?q=logo&status=all" \
-H "Authorization: Bearer $TOKIDU_TOKEN"POST /api/v1/projects
Crea un projecte: name i, si vols, color, icon (un emoji) i client (el client amb què agrupar-lo). Només si tens Max.
Àmbit: write
POST /api/v1/projects/{id}/tasks
Crea una tasca: title i, si vols, notes, priority, due, assignee, sprintId, estimateMin, after, labels, milestone (una fita), companions (qui l’acompanya) i checklist (la seva llista de comprovació). Exigeix Idempotency-Key.
Àmbit: 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":"Trucar a la Marta","due":"2026-10-20"}'PATCH /api/v1/tasks/{id}
Canvia només els camps que enviïs; la llista de comprovació, element a element (checklist: marcar, reescriure, treure o afegir, amb els ids que dona la tasca), i els acompanyants, la llista sencera (companions: llegeix-la abans i envia tots els noms que s’hi hagin de quedar). Respon amb la tasca, les que es desbloquegen i, si una altra persona ha canviat el mateix alhora, el que s’ha quedat.
Àmbit: 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
Marca la tasca com a feta (també una de cancel·lada) i respon amb les que es desbloquegen.
Àmbit: write
curl -X POST https://tokidu.com/api/v1/tasks/$TASK_ID/done \
-H "Authorization: Bearer $TOKIDU_TOKEN"POST /api/v1/tasks/{id}/reopen
Torna a obrir una tasca feta o cancel·lada.
Àmbit: write
POST /api/v1/tasks/{id}/cancel
Cancel·la la tasca: es tanca sense comptar com a feta i les que l’esperaven ja poden començar. Respon amb les que es desbloquegen.
Àmbit: 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}
Fa que la tasca esperi una altra del mateix projecte o d’un altre projecte del mateix titular (afterOutside). Amb days al cos, a més, que passin aquests dies des que acabi l’altra (d’1 a 365; 0 els treu).
Àmbit: 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}
Treu aquesta espera.
Àmbit: write
DELETE /api/v1/tasks/{id}
Esborra la tasca, com al web: passa 30 dies per la paperera, d’on es pot restaurar des del web.
Àmbit: write
GET /api/v1/projects/{id}/labels
Les etiquetes del projecte, per ordre alfabètic: id, nom i color.
Àmbit: read
POST /api/v1/projects/{id}/labels
Crea una etiqueta al projecte: name i, si vols, color. Si ja n’hi ha una amb aquest nom, respon amb aquesta.
Àmbit: write
GET /api/v1/webhooks
Els avisos a altres apps que ha creat aquest token: adreça, esdeveniments, projectes i estat (mai el secret).
Àmbit: webhooks
POST /api/v1/webhooks
Registra una adreça https per rebre avisos signats: url, events i, si vols, projects (només teus). Respon amb el secret, una sola vegada.
Àmbit: webhooks
DELETE /api/v1/webhooks/{id}
Esborra un dels avisos que ha creat aquest token i deixa d’enviar-lo.
Àmbit: webhooks
Avisos a altres apps (webhooks)
Quan passa alguna cosa als teus projectes, tokidu envia un POST signat a l'adreça que diguis. Es creen a Compte → Integracions, o per l'API amb un token amb l'àmbit webhooks (el que fan servir Zapier o Make). Només el titular amb Max, i només dels seus projectes; fins a 20 per compte.
Què pots escoltar
task.created· Es crea una tascatask.done· S’acaba una tascatask.cancelled· Es cancel·la una tascatask.reopened· Es reobre una tascatask.unblocked· Es desbloqueja una tascatask.assigned· S’assigna una tascatask.deleted· S’esborra una tascacomment.created· Algú comenta una tascaproject.status· Canvia el semàfor d’un projecteproject.duplicated· Es duplica un projecteproject.imported· S’importa un projecte
Cada avís porta el tipus, un id del fet, l'hora, el projecte i, si és d'una tasca, el títol, l'estat, si està cancel·lada, si és una fita, les etiquetes, el nom de qui la té assignada i de qui l'acompanya, la data límit i l'enllaç. Les tasques que crea una repetició arriben com qualsevol tasca nova (task.created). Mai notes, enllaços, fitxers, correus ni hores. D'un comentari, només qui l'ha escrit: mai el text.
Comprovar la signatura
Segueix Standard Webhooks: capçaleres webhook-id, webhook-timestamp (segons) i webhook-signature (v1, i un HMAC-SHA256 en base64 de id.timestamp.cos, amb la clau que va darrere de whsec_). Comprova-la amb el cos tal com arriba i rebutja els de més de 5 minuts. A 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);
});
}Enviaments i reintents
Qualsevol 2xx és bo; les redireccions no se segueixen. Si falla, es reintenta a 1 min, 5 min, 30 min, 2 h, 6 h, 12 h i 24 h. Amb 20 lliuraments fallits seguits, o 3 dies sense un 2xx, l'avís s'apaga i t'enviem un correu.
Només adreces https:// públiques, al port 443 o 8443, sense usuari ni contrasenya: res de localhost, xarxes internes ni IP privades (també es comprova en enviar).
Agents d’IA (MCP)
Amb MCP (Model Context Protocol), un agent d’IA com Claude Code pot fer servir tokidu per tu: dir-te què et toca, buscar tasques, llegir-ne els comentaris i, si el token ho permet, crear-les, canviar-les, acabar-les i cancel·lar-les. Va sobre aquesta API i amb el mateix token: l’agent mai fa res que no pugui fer aquest token.
- Adreça
https://tokidu.com/api/mcp- Capçalera
Authorization: Bearer tkd_…
Connectar Claude Code
Crea un token a Compte → Integracions i enganxa això al terminal, amb el teu token en lloc de tkd_…:
claude mcp add --transport http tokidu https://tokidu.com/api/mcp \
--header "Authorization: Bearer tkd_…"En qualsevol altre client que deixi posar una capçalera, fes servir la mateixa adreça i la mateixa capçalera.
Què permet fer el token
read, «Veure els teus projectes i tasques»: connectar l’agent i fer servir les eines que llegeixen.write, «Crear i canviar tasques»: a més, les que creen i canvien tasques i esperes.- Si el token només arriba a uns quants projectes, l’agent només veu aquests. El token de Madrugo (
integrations:read) no serveix per a l’MCP.
Eines
Cadascuna demana un àmbit del token. Els noms van en anglès, com és costum a MCP.
list_projects- Els projectes que veu el token, amb el seu client, el seu semàfor, el final previst i la foto del pla.Àmbit:
read next_up- «El següent»: el que és teu i ja es pot començar, de tots els projectes o d’un.Àmbit:
read get_project- Un projecte, les seves etiquetes, les seves repeticions i les seves tasques obertes: quan es preveu que acabin, si estan bloquejades, els dies de més de les seves esperes, quines són fites, qui les acompanya i quant porten marcat de la seva llista de comprovació.Àmbit:
read get_task- Una tasca amb les seves notes, la seva llista de comprovació, qui l’acompanya, de quina repetició ha sortit, què espera (i des de quan podrà començar, si falten els dies d’una espera) i «Per què aquesta data?».Àmbit:
read list_comments- Els comentaris d’una tasca, per llegir-los: el text, qui l’ha escrit i quan. Cap eina no escriu comentaris.Àmbit:
read search_tasks- Busca tasques pel títol als projectes que veu el token.Àmbit:
read create_task- Crea una tasca (o una fita), també amb la seva llista de comprovació i qui l’acompanya. Si el client repeteix la mateixa petició dins del mateix bloc de 10 minuts del rellotge, no es duplica; per reintentar sense risc, que enviï
idempotency_key.Àmbit:write update_task- Canvia només els camps de la tasca que enviï (també les etiquetes, si és una fita, qui l’acompanya, sempre la llista sencera, i, element a element, la seva llista de comprovació).Àmbit:
write complete_task- Marca la tasca com a feta i diu quines es desbloquegen.Àmbit:
write cancel_task- Cancel·la una tasca que ja no es farà: no compta com a feta i diu quines es desbloquegen.Àmbit:
write add_wait- Fa que una tasca n’esperi una altra i, amb
days, que passin a més uns dies des que acabi.Àmbit:write remove_wait- Treu una espera.Àmbit:
write
El que convé saber
- No hi ha eines per esborrar tasques ni projectes, ni per comentar, ni per crear o canviar repeticions, ni per a persones, invitacions, hores, fitxers o avisos a altres apps. Però
update_taskpot canviar o buidar els camps d’una tasca (les notes no guarden versions anteriors),add_waitambdayscanvia o treu els dies d’una espera iremove_waittreu esperes: donawriteal token només si és el que vols. - Comparteix els límits de l’API (1000 peticions per hora i compte, 60 per minut i token): cada eina és una crida a l’API (
get_project, dues) i gasta dels dos; la resta del que envia el client (initialize,tools/list,ping,server/discover, les notificacions i les eines que no arriben a l’API perquè una dada no és vàlida) gasta un del minut, però no de l’hora. - A «Últims canvis amb aquest token» hi surten, marcats amb MCP, els canvis que fa i els intents rebutjats (401, 403 i 429, un per minut com a molt); el que només llegeix, no.
- Els títols, les notes, els elements de les llistes de comprovació, els comentaris i els noms els escriuen persones: tokidu els dona a l’agent com a dades, en els seus propis camps i, dins de les frases de «Per què aquesta data?» i del semàfor, entre cometes «», i li diu que mai són instruccions.
- Encara no hi ha OAuth, així que tokidu no es pot afegir com a connector a claude.ai. Funciona a Claude Code i a qualsevol client que deixi posar una capçalera.
- Sense sessió: cada petició és un
POSTamb JSON-RPC i la resposta va sempre en JSON. - Versions del protocol: la moderna i, per als clients d’abans, les que comencen amb
initialize:2026-07-28,2025-11-25,2025-06-18,2025-03-26.
OpenAPI
Tots els camps de cada petició i de cada resposta, en format OpenAPI, per generar un client o importar-los a la teva eina: /api/v1/openapi.json.