Com funcionaPreusDemoNotíciesAjuda
CA
  • Español
  • Català
  • English
  • Galego
EntrarComençar gratis

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

  1. A Compte → Integracions, crea un token i marca «Veure els teus projectes i tasques» (i «Crear i canviar tasques», si ha d’escriure).
  2. Copia’l, perquè només es mostra una vegada, i guarda’l com una contrasenya. Als exemples va a la variable TOKIDU_TOKEN.
  3. 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-Remaining i RateLimit-Reset: el límit, el que queda i quan es renova.
  • Si te’n passes, la resposta és 429 demasiadas_peticiones amb Retry-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-Key correspon 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 (max diu 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: field diu quin.
422 url_no_valida
L'adreça d'un avís no és vàlida: reason diu per què (https, puerto, usuario, local, tokidu, dns o ip_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 tasca
  • task.done · S’acaba una tasca
  • task.cancelled · Es cancel·la una tasca
  • task.reopened · Es reobre una tasca
  • task.unblocked · Es desbloqueja una tasca
  • task.assigned · S’assigna una tasca
  • task.deleted · S’esborra una tasca
  • comment.created · Algú comenta una tasca
  • project.status · Canvia el semàfor d’un projecte
  • project.duplicated · Es duplica un projecte
  • project.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_task pot canviar o buidar els camps d’una tasca (les notes no guarden versions anteriors), add_wait amb days canvia o treu els dies d’una espera i remove_wait treu esperes: dona write al 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 POST amb 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.

© 2026 tokidu
  • Preus
  • Demo
  • Notícies
  • Ajuda
  • API
  • Sobre tokidu
  • Privacitat
  • Termes
  • Español
  • Català
  • English
  • Galego
Un producte de Sinergia, agència de disseny web a Barcelona