Como funcionaPrezosDemoNovasAxuda
GL
  • Español
  • Català
  • English
  • Galego
EntrarEmpezar gratis

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

  1. En Conta → Integracións, crea un token e marca «Ver os teus proxectos e tarefas» (e «Crear e cambiar tarefas», se vai escribir).
  2. Cópiao, porque só se amosa unha vez, e gárdao como un contrasinal. Nos exemplos vai na variable TOKIDU_TOKEN.
  3. 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-Remaining e RateLimit-Reset: o límite, o que queda e cando se renova.
  • Se te pasas, a resposta é 429 demasiadas_peticiones con Retry-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-Key corresponde 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 (max di 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: field di cal.
422 url_no_valida
O enderezo dun aviso non vale: reason di por que (https, puerto, usuario, local, tokidu, dns ou ip_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 tarefa
  • task.done · Remátase unha tarefa
  • task.cancelled · Cancélase unha tarefa
  • task.reopened · Reábrese unha tarefa
  • task.unblocked · Desbloquéase unha tarefa
  • task.assigned · Asígnase unha tarefa
  • task.deleted · Bórrase unha tarefa
  • comment.created · Alguén comenta unha tarefa
  • project.status · Cambia o semáforo dun proxecto
  • project.duplicated · Duplícase un proxecto
  • project.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_task pode cambiar ou baleirar os campos dunha tarefa (as notas non gardan versións anteriores), add_wait con days cambia ou quita os días dunha espera e remove_wait quita esperas: dálle write ao 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 POST con 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.

© 2026 tokidu
  • Prezos
  • Demo
  • Novas
  • Axuda
  • API
  • Sobre tokidu
  • Privacidade
  • Termos
  • Español
  • Català
  • English
  • Galego
Un produto de Sinergia, axencia de deseño web en Barcelona