A API de tokidu
Le os teus proxectos e tarefas, crea tarefas desde un formulario ou un script e péchaas desde outra app. A API pasa pola mesma porta ca a web: un token nunca fai nada que non poida facer a súa conta.
É do plan Max: pode usala quen ten Max e quen traballa nun proxecto que comparte alguén con Max, e só chega a eses proxectos.
- Enderezo base
https://tokidu.com/api/v1- Cabeceira
Authorization: Bearer tkd_…- Límites
- 1000 peticións por hora e conta · 60 por minuto e token
- Referencia completa
- /api/v1/openapi.json
Comezar
- En Conta → Integracións, crea un token e marca «Ver os teus proxectos e tarefas» (e «Crear e cambiar tarefas», se vai escribir).
- Cópiao, porque só se amosa unha vez, e gárdao como un contrasinal. Nos exemplos vai na variable
TOKIDU_TOKEN. - Próbao pedindo a túa conta:
curl https://tokidu.com/api/v1/me \
-H "Authorization: Bearer $TOKIDU_TOKEN"Chámaa desde un servidor ou un script, non desde unha páxina web: a API non admite CORS e non mira as cookies.
Tokens e ámbitos
Ao crear un token escolles que pode facer, a que proxectos chega e cando caduca:
read, «Ver os teus proxectos e tarefas»: ler os proxectos, as tarefas (cos seus comentarios) e «O seguinte».write, «Crear e cambiar tarefas»: crear proxectos e tarefas, cambialas, rematalas, cancelalas, reabrilas e borralas, e crear etiquetas, como na web.- Proxectos: todos os que ves ou só os que marques. Se deixas de ver un, o token deixa de chegar a el.
- Caducidade: aos 30, 90 ou 365 días. Se non escolles, ao ano.
O token de Madrugo (integrations:read) só le «O seguinte» para Madrugo, de todos os proxectos que ves: non abre esta API e non se pode limitar a uns proxectos.
Podes ter 10 tokens activos. Revógaos dun en un ou todos á vez, e mira en cada un os seus últimos cambios: gardamos que cambios se fixeron con cada token, sen o contido, durante 90 días.
Límites
- 1000 peticións por hora para toda a túa conta e 60 por minuto para cada token.
- Cada resposta leva
RateLimit-Limit,RateLimit-RemainingeRateLimit-Reset: o límite, o que queda e cando se renova. - Se te pasas, a resposta é 429
demasiadas_peticionesconRetry-After: espera eses segundos e volve probar. - O corpo dunha petición pode ocupar 64 KiB como moito.
Crear tarefas sen duplicalas
Crear unha tarefa esixe a cabeceira Idempotency-Key: de 1 a 100 caracteres, distinta para cada tarefa que queres crear (por exemplo, o id da fila, do correo ou do formulario de onde sae).
Se repites a petición coa mesma clave, por exemplo despois dun corte de rede, non se crea outra: devólveche a que xa existe, con 200 e Idempotent-Replayed: true.
Se a tarefa desa clave se borrou, non se crea outra: a resposta é 410 tarea_borrada. Se alguén a restaura desde a papeleira, a mesma clave volve devolver esa tarefa. A mesma clave noutro proxecto crea outra tarefa.
Erros
Un erro responde co seu código HTTP e o campo error do corpo; con 422, tamén field, o campo que non vale.
- 401
token_invalido - Falta o token, non existe, está revogado ou caducou (non se di cal).
- 403
ambito - Ao token fáltalle o ámbito que pide a ruta.
- 403
proyecto_fuera_del_token - O token está limitado a outros proxectos.
- 403
max_necesario - É do plan Max e quen comparte o proxecto non o ten (ou ti, ao crear un proxecto).
- 403
solo_lectura - Nese proxecto só podes ver, non cambiar.
- 403
en_pausa - O proxecto está en pausa: quen o comparte xa non ten o plan Pro, así que só se pode ver.
- 404
proyecto_inexistente - O proxecto non existe ou non o ves.
- 404
tarea_inexistente - A tarefa non existe ou non a ves.
- 404
ruta_inexistente - Esa ruta non é da API: revisa o método e o enderezo.
- 404
webhook_inexistente - Ese aviso non existe ou non o creou este token.
- 409
id_ocupado - Esa
Idempotency-Keycorresponde a unha tarefa que non ves: usa outra. - 409
horas_de_otros - Non se pode borrar porque ten horas doutras persoas, como na web.
- 409
adjuntos_de_otros - Non se pode borrar porque ten ficheiros doutras persoas, como na web.
- 409
entrada_facturada - Non se pode borrar porque ten horas xa facturadas, coma na web.
- 409
ciclo - Esa espera pecharía un círculo: unha tarefa acabaría esperando por si mesma.
- 409
webhooks_completo - Xa tes 20 avisos: borra algún para crear outro.
- 409
demasiadas_etiquetas - O proxecto xa ten todas as etiquetas que caben (
maxdi cantas): borra algunha na web ou na app para crear outra. - 410
tarea_borrada - Esa
Idempotency-Keyé dunha tarefa que se borrou: non se volve crear. Para crear outra, usa outra clave. - 413
cuerpo_grande - O corpo pasa de 64 KiB.
- 415
json_necesario - O corpo ten que ir en JSON, con
Content-Type: application/json. - 422
peticion_invalida - Un campo non vale:
fielddi cal. - 422
url_no_valida - O enderezo dun aviso non vale:
reasondi por que (https,puerto,usuario,local,tokidu,dnsouip_privada). - 428
idempotencia_necesaria - Para crear unha tarefa falta a cabeceira
Idempotency-Key. - 429
demasiadas_peticiones - Pasácheste do límite: espera o que diga
Retry-After. - 429
demasiados_intentos - Comprobaches moitos enderezos de avisos seguidos: agarda o que diga
Retry-After. - 503
ocupado - O proxecto estaba ocupado con outro cambio: repite a petición pasado o que diga
Retry-After. - 503
no_disponible - O servizo non puido responder agora: repite a petición pasado o que diga
Retry-After.
Referencia
Todas as rutas van detrás do enderezo base e responden en JSON. Os ids de proxectos e tarefas son os que devolve a propia API.
GET /api/v1/me
A túa conta, o token (nome, ámbitos, proxectos e caducidade) e o que che queda da hora.
Ámbito: calquera
GET /api/v1/projects
Os proxectos que ves de quen ten Max: nome, cor, icona, cliente, quen o comparte, o teu papel, semáforo, final previsto, foto do plan e avance.
Ámbito: read
GET /api/v1/projects/{id}
Un proxecto, cos seus sprints, as súas etiquetas e as súas repeticións (as tarefas que se repiten soas): o seu horario, a próxima vez e, se se saltou algunha, por que. As repeticións só se len.
Ámbito: read
GET /api/v1/projects/{id}/tasks
As tarefas dun proxecto, sen notas: por que esperan (e os días de máis de cada espera), se están bloqueadas, se son fitos, as súas etiquetas, canto levan marcado da súa lista de comprobación, quen as acompaña, de que repetición saíron e cando se prevé que rematen. Filtra con status (open, done, cancelled ou all) e updatedSince, e pasa de páxina con cursor.
Ámbito: read
curl "https://tokidu.com/api/v1/projects/$PROJECT_ID/tasks?status=open" \
-H "Authorization: Bearer $TOKIDU_TOKEN"GET /api/v1/tasks/{id}
Unha tarefa coas súas notas, a súa lista de comprobación, por que espera (e, se xa rematou unha e faltan os seus días, desde cando poderá empezar) e «Por que esa data?».
Ámbito: read
GET /api/v1/tasks/{id}/comments
Os comentarios dunha tarefa, para lelos: o texto, quen o escribiu e cando, por páxinas desde os máis recentes (os anteriores, con cursor). Pola API non se pode comentar.
Ámbito: read
curl https://tokidu.com/api/v1/tasks/$TASK_ID/comments \
-H "Authorization: Bearer $TOKIDU_TOKEN"GET /api/v1/next
«O seguinte»: o teu que xa se pode comezar. Con projectId, só o dese proxecto.
Ámbito: read
GET /api/v1/search
Busca tarefas polo título, sen mirar maiúsculas nin acentos, no que ves: q e, se queres, projectId, status (open, done, cancelled ou all) e limit. Primeiro as abertas, na orde de «O seguinte».
Ámbito: read
curl "https://tokidu.com/api/v1/search?q=logo&status=all" \
-H "Authorization: Bearer $TOKIDU_TOKEN"POST /api/v1/projects
Crea un proxecto: name e, se queres, color, icon (un emoji) e client (o cliente co que agrupalo). Só se tes Max.
Ámbito: write
POST /api/v1/projects/{id}/tasks
Crea unha tarefa: title e, se queres, notes, priority, due, assignee, sprintId, estimateMin, after, labels, milestone (un fito), companions (quen a acompaña) e checklist (a súa lista de comprobación). Esixe Idempotency-Key.
Ámbito: 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":"Chamar a Ana","due":"2026-10-20"}'PATCH /api/v1/tasks/{id}
Cambia só os campos que mandes; a lista de comprobación, elemento a elemento (checklist: marcar, reescribir, quitar ou engadir, cos ids que dá a tarefa), e os acompañantes, a lista enteira (companions: léa antes e manda todos os nomes que deban quedar). Responde coa tarefa, as que se desbloquean e, se outra persoa cambiou o mesmo á vez, o que quedou.
Ámbito: 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 a tarefa como feita (tamén unha cancelada) e responde coas que se desbloquean.
Ámbito: write
curl -X POST https://tokidu.com/api/v1/tasks/$TASK_ID/done \
-H "Authorization: Bearer $TOKIDU_TOKEN"POST /api/v1/tasks/{id}/reopen
Volve abrir unha tarefa feita ou cancelada.
Ámbito: write
POST /api/v1/tasks/{id}/cancel
Cancela a tarefa: péchase sen contar como feita e as que a esperaban xa poden comezar. Responde coas que se desbloquean.
Ámbito: 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}
Fai que a tarefa espere por outra do mesmo proxecto ou doutro proxecto do mesmo dono (afterOutside). Con days no corpo, ademais, que pasen eses días desde que remate a outra (de 1 a 365; 0 quítaos).
Ámbito: 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}
Quita esa espera.
Ámbito: write
DELETE /api/v1/tasks/{id}
Borra a tarefa, como na web: pasa 30 días pola papeleira, de onde se pode restaurar desde a web.
Ámbito: write
GET /api/v1/projects/{id}/labels
As etiquetas do proxecto, por orde alfabética: id, nome e cor.
Ámbito: read
POST /api/v1/projects/{id}/labels
Crea unha etiqueta no proxecto: name e, se queres, color. Se xa hai unha con ese nome, responde con esa.
Ámbito: write
GET /api/v1/webhooks
Os avisos a outras apps que creou este token: enderezo, eventos, proxectos e estado (nunca o segredo).
Ámbito: webhooks
POST /api/v1/webhooks
Rexistra un enderezo https para recibir avisos asinados: url, events e, se queres, projects (só teus). Responde co segredo, unha soa vez.
Ámbito: webhooks
DELETE /api/v1/webhooks/{id}
Borra un dos avisos que creou este token e deixa de mandalo.
Ámbito: webhooks
Avisos a outras apps (webhooks)
Cando pasa algo nos teus proxectos, tokidu manda un POST asinado ao enderezo que digas. Créanse en Conta → Integracións, ou pola API cun token co ámbito webhooks (o que usan Zapier ou Make). Só o dono con Max, e só dos seus proxectos; ata 20 por conta.
Que podes escoitar
task.created· Créase unha tarefatask.done· Remátase unha tarefatask.cancelled· Cancélase unha tarefatask.reopened· Reábrese unha tarefatask.unblocked· Desbloquéase unha tarefatask.assigned· Asígnase unha tarefatask.deleted· Bórrase unha tarefacomment.created· Alguén comenta unha tarefaproject.status· Cambia o semáforo dun proxectoproject.duplicated· Duplícase un proxectoproject.imported· Impórtase un proxecto
Cada aviso leva o tipo, un id do feito, a hora, o proxecto e, se é dunha tarefa, o seu título, estado, se está cancelada, se é un fito, as súas etiquetas, o nome de quen a ten asignada e de quen a acompaña, a data límite e a ligazón. As tarefas que crea unha repetición chegan coma calquera tarefa nova (task.created). Nunca notas, ligazóns, ficheiros, correos nin horas. Dun comentario, só quen o escribiu: nunca o texto.
Comprobar a sinatura
Segue Standard Webhooks: cabeceiras webhook-id, webhook-timestamp (segundos) e webhook-signature (v1, e un HMAC-SHA256 en base64 de id.timestamp.corpo, coa clave que vai detrás de whsec_). Compróbaa co corpo tal como chega e rexeita os de máis de 5 minutos. En 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);
});
}Envíos e reintentos
Calquera 2xx é bo; as redireccións non se seguen. Se falla, reinténtase a 1 min, 5 min, 30 min, 2 h, 6 h, 12 h e 24 h. Con 20 entregas falladas seguidas, ou 3 días sen un 2xx, o aviso apágase e mandámosche un correo.
Só enderezos https:// públicos, no porto 443 ou 8443, sen usuario nin contrasinal: nada de localhost, redes internas nin IP privadas (compróbase tamén ao enviar).
Axentes de IA (MCP)
Con MCP (Model Context Protocol), un axente de IA como Claude Code pode usar tokidu por ti: dicirche que che toca, buscar tarefas, ler os seus comentarios e, se o token o deixa, crealas, cambialas, rematalas e cancelalas. Vai sobre esta API e co mesmo token: o axente nunca fai nada que non poida facer ese token.
- Enderezo
https://tokidu.com/api/mcp- Cabeceira
Authorization: Bearer tkd_…
Conectar Claude Code
Crea un token en Conta → Integracións e pega isto no terminal, co teu token no canto de tkd_…:
claude mcp add --transport http tokidu https://tokidu.com/api/mcp \
--header "Authorization: Bearer tkd_…"En calquera outro cliente que deixe poñer unha cabeceira, usa o mesmo enderezo e a mesma cabeceira.
Que deixa facer o token
read, «Ver os teus proxectos e tarefas»: conectar o axente e usar as ferramentas que len.write, «Crear e cambiar tarefas»: ademais, as que crean e cambian tarefas e esperas.- Se o token chega só a uns proxectos, o axente só ve eses. O token de Madrugo (
integrations:read) non serve para o MCP.
Ferramentas
Cada unha pide un ámbito do token. Os nomes van en inglés, como é costume en MCP.
list_projects- Os proxectos que ve o token, co seu cliente, o seu semáforo, o final previsto e a foto do plan.Ámbito:
read next_up- «O seguinte»: o teu que xa se pode comezar, de todos os proxectos ou dun.Ámbito:
read get_project- Un proxecto, as súas etiquetas, as súas repeticións e as súas tarefas abertas: cando se prevé que rematen, se están bloqueadas, os días de máis das súas esperas, cales son fitos, quen as acompaña e canto levan marcado da súa lista de comprobación.Ámbito:
read get_task- Unha tarefa coas súas notas, a súa lista de comprobación, quen a acompaña, de que repetición saíu, por que espera (e desde cando poderá empezar, se faltan os días dunha espera) e «Por que esa data?».Ámbito:
read list_comments- Os comentarios dunha tarefa, para lelos: o texto, quen o escribiu e cando. Ningunha ferramenta escribe comentarios.Ámbito:
read search_tasks- Busca tarefas polo título nos proxectos que ve o token.Ámbito:
read create_task- Crea unha tarefa (ou un fito), tamén coa súa lista de comprobación e quen a acompaña. Se o cliente repite a mesma petición dentro do mesmo bloque de 10 minutos do reloxo, non se duplica; para reintentar sen risco, que mande
idempotency_key.Ámbito:write update_task- Cambia só os campos da tarefa que mande (tamén as súas etiquetas, se é un fito, quen a acompaña, sempre a lista enteira, e, elemento a elemento, a súa lista de comprobación).Ámbito:
write complete_task- Marca a tarefa como feita e di cales se desbloquean.Ámbito:
write cancel_task- Cancela unha tarefa que xa non se vai facer: non conta como feita e di cales se desbloquean.Ámbito:
write add_wait- Fai que unha tarefa espere por outra e, con
days, que pasen ademais uns días desde que remate.Ámbito:write remove_wait- Quita unha espera.Ámbito:
write
O que convén saber
- Non hai ferramentas para borrar tarefas nin proxectos, nin para comentar, nin para crear ou cambiar repeticións, nin para persoas, invitacións, horas, ficheiros ou avisos a outras apps. Pero
update_taskpode cambiar ou baleirar os campos dunha tarefa (as notas non gardan versións anteriores),add_waitcondayscambia ou quita os días dunha espera eremove_waitquita esperas: dállewriteao token só se queres iso. - Comparte os límites da API (1000 peticións por hora e conta, 60 por minuto e token): cada ferramenta é unha chamada á API (
get_project, dúas) e gasta dos dous; o resto do que manda o cliente (initialize,tools/list,ping,server/discover, as notificacións e as ferramentas que non chegan á API porque un dato non vale) gasta un do minuto, pero non da hora. - En «Últimos cambios con este token» saen, marcados con MCP, os cambios que fai e os intentos rexeitados (401, 403 e 429, un por minuto como moito); o que só le, non.
- Os títulos, as notas, os elementos das listas de comprobación, os comentarios e os nomes escríbenos persoas: tokidu dállelos ao axente como datos, nos seus propios campos e, dentro das frases de «Por que esa data?» e do semáforo, entre comiñas «», e dille que nunca son instrucións.
- Aínda non hai OAuth, así que tokidu non se pode engadir como conector en claude.ai. Funciona en Claude Code e en calquera cliente que deixe poñer unha cabeceira.
- Sen sesión: cada petición é un
POSTcon JSON-RPC e a resposta vai sempre en JSON. - Versións do protocolo: a moderna e, para os clientes de antes, as que empezan con
initialize:2026-07-28,2025-11-25,2025-06-18,2025-03-26.
OpenAPI
Todos os campos de cada petición e de cada resposta, en formato OpenAPI, para xerar un cliente ou importalos na túa ferramenta: /api/v1/openapi.json.