La API de tokidu
Lee tus proyectos y tareas, crea tareas desde un formulario o un script y ciérralas desde otra app. La API pasa por la misma puerta que la web: un token nunca hace nada que no pueda hacer su cuenta.
Es del plan Max: la puede usar quien tiene Max y quien trabaja en un proyecto que comparte alguien con Max, y solo llega a esos proyectos.
- Dirección base
https://tokidu.com/api/v1- Cabecera
Authorization: Bearer tkd_…- Límites
- 1000 peticiones por hora y cuenta · 60 por minuto y token
- Referencia completa
- /api/v1/openapi.json
Empezar
- En Cuenta → Integraciones, crea un token y marca «Ver tus proyectos y tareas» (y «Crear y cambiar tareas», si va a escribir).
- Cópialo, porque solo se enseña una vez, y guárdalo como una contraseña. En los ejemplos va en la variable
TOKIDU_TOKEN. - Pruébalo pidiendo tu cuenta:
curl https://tokidu.com/api/v1/me \
-H "Authorization: Bearer $TOKIDU_TOKEN"Llámala desde un servidor o un script, no desde una página web: la API no admite CORS y no mira las cookies.
Tokens y ámbitos
Al crear un token eliges qué puede hacer, a qué proyectos llega y cuándo caduca:
read, «Ver tus proyectos y tareas»: leer los proyectos, las tareas (con sus comentarios) y «Lo siguiente».write, «Crear y cambiar tareas»: crear proyectos y tareas, cambiarlas, terminarlas, cancelarlas, reabrirlas y borrarlas, y crear etiquetas, como en la web.- Proyectos: todos los que ves o solo los que marques. Si dejas de ver uno, el token deja de llegar a él.
- Caducidad: a los 30, 90 o 365 días. Si no eliges, al año.
El token de Madrugo (integrations:read) solo lee «Lo siguiente» para Madrugo, de todos los proyectos que ves: no abre esta API y no se puede limitar a unos proyectos.
Puedes tener 10 tokens activos. Revócalos de uno en uno o todos a la vez, y mira en cada uno sus últimos cambios: guardamos qué cambios se hicieron con cada token, sin el contenido, durante 90 días.
Límites
- 1000 peticiones por hora para toda tu cuenta y 60 por minuto para cada token.
- Cada respuesta lleva
RateLimit-Limit,RateLimit-RemainingyRateLimit-Reset: el límite, lo que queda y cuándo se renueva. - Si te pasas, la respuesta es 429
demasiadas_peticionesconRetry-After: espera esos segundos y vuelve a probar. - El cuerpo de una petición puede ocupar 64 KiB como mucho.
Crear tareas sin duplicarlas
Crear una tarea exige la cabecera Idempotency-Key: de 1 a 100 caracteres, distinta para cada tarea que quieres crear (por ejemplo, el id de la fila, del correo o del formulario de donde sale).
Si repites la petición con la misma clave, por ejemplo tras un corte de red, no se crea otra: te devuelve la que ya existe, con 200 e Idempotent-Replayed: true.
Si la tarea de esa clave se borró, no se crea otra: la respuesta es 410 tarea_borrada. Si alguien la restaura desde la papelera, la misma clave vuelve a devolver esa tarea. La misma clave en otro proyecto crea otra tarea.
Errores
Un error responde con su código HTTP y el campo error del cuerpo; con 422, también field, el campo que no vale.
- 401
token_invalido - Falta el token, no existe, está revocado o ha caducado (no se dice cuál).
- 403
ambito - Al token le falta el ámbito que pide la ruta.
- 403
proyecto_fuera_del_token - El token está limitado a otros proyectos.
- 403
max_necesario - Es del plan Max y quien comparte el proyecto no lo tiene (o tú, al crear un proyecto).
- 403
solo_lectura - En ese proyecto solo puedes ver, no cambiar.
- 403
en_pausa - El proyecto está en pausa: quien lo comparte ya no tiene el plan Pro, así que solo se puede ver.
- 404
proyecto_inexistente - El proyecto no existe o no lo ves.
- 404
tarea_inexistente - La tarea no existe o no la ves.
- 404
ruta_inexistente - Esa ruta no es de la API: revisa el método y la dirección.
- 404
webhook_inexistente - Ese aviso no existe o no lo creó este token.
- 409
id_ocupado - Esa
Idempotency-Keycorresponde a una tarea que no ves: usa otra. - 409
horas_de_otros - No se puede borrar porque tiene horas de otras personas, como en la web.
- 409
adjuntos_de_otros - No se puede borrar porque tiene archivos de otras personas, como en la web.
- 409
entrada_facturada - No se puede borrar porque tiene horas ya facturadas, como en la web.
- 409
ciclo - Esa espera cerraría un círculo: una tarea acabaría esperándose a sí misma.
- 409
webhooks_completo - Ya tienes 20 avisos: borra alguno para crear otro.
- 409
demasiadas_etiquetas - El proyecto ya tiene todas las etiquetas que caben (
maxdice cuántas): borra alguna en la web o en la app para crear otra. - 410
tarea_borrada - Esa
Idempotency-Keyes de una tarea que se borró: no se vuelve a crear. Para crear otra, usa otra clave. - 413
cuerpo_grande - El cuerpo pasa de 64 KiB.
- 415
json_necesario - El cuerpo tiene que ir en JSON, con
Content-Type: application/json. - 422
peticion_invalida - Un campo no vale:
fielddice cuál. - 422
url_no_valida - La dirección de un aviso no vale:
reasondice por qué (https,puerto,usuario,local,tokidu,dnsoip_privada). - 428
idempotencia_necesaria - Para crear una tarea falta la cabecera
Idempotency-Key. - 429
demasiadas_peticiones - Te has pasado del límite: espera lo que diga
Retry-After. - 429
demasiados_intentos - Has comprobado muchas direcciones de avisos seguidas: espera lo que diga
Retry-After. - 503
ocupado - El proyecto estaba ocupado con otro cambio: repite la petición pasado lo que diga
Retry-After. - 503
no_disponible - El servicio no ha podido responder ahora: repite la petición pasado lo que diga
Retry-After.
Referencia
Todas las rutas van detrás de la dirección base y responden en JSON. Los ids de proyectos y tareas son los que devuelve la propia API.
GET /api/v1/me
Tu cuenta, el token (nombre, ámbitos, proyectos y caducidad) y lo que te queda de la hora.
Ámbito: cualquiera
GET /api/v1/projects
Los proyectos que ves de quien tiene Max: nombre, color, icono, cliente, quién lo comparte, tu papel, semáforo, fin previsto, foto del plan y avance.
Ámbito: read
GET /api/v1/projects/{id}
Un proyecto, con sus sprints, sus etiquetas y sus repeticiones (las tareas que se repiten solas): su horario, la próxima vez y, si se saltó alguna, por qué. Las repeticiones solo se leen.
Ámbito: read
GET /api/v1/projects/{id}/tasks
Las tareas de un proyecto, sin notas: a qué esperan (y los días de más de cada espera), si están bloqueadas, si son hitos, sus etiquetas, cuánto llevan marcado de su lista de comprobación, quién las acompaña, de qué repetición salieron y cuándo se prevé que acaben. Filtra con status (open, done, cancelled o all) y updatedSince, y pasa de página 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}
Una tarea con sus notas, su lista de comprobación, a qué espera (y, si ya acabó una y faltan sus días, desde cuándo podrá empezar) y «¿Por qué esa fecha?».
Ámbito: read
GET /api/v1/tasks/{id}/comments
Los comentarios de una tarea, para leerlos: el texto, quién lo escribió y cuándo, por páginas desde los más recientes (los anteriores, con cursor). Por la API no se puede comentar.
Ámbito: read
curl https://tokidu.com/api/v1/tasks/$TASK_ID/comments \
-H "Authorization: Bearer $TOKIDU_TOKEN"GET /api/v1/next
«Lo siguiente»: lo tuyo que ya se puede empezar. Con projectId, solo lo de ese proyecto.
Ámbito: read
GET /api/v1/search
Busca tareas por título, sin mirar mayúsculas ni acentos, en lo que ves: q y, si quieres, projectId, status (open, done, cancelled o all) y limit. Primero las abiertas, en el orden de «Lo siguiente».
Ámbito: read
curl "https://tokidu.com/api/v1/search?q=logo&status=all" \
-H "Authorization: Bearer $TOKIDU_TOKEN"POST /api/v1/projects
Crea un proyecto: name y, si quieres, color, icon (un emoji) y client (el cliente con el que agruparlo). Solo si tienes Max.
Ámbito: write
POST /api/v1/projects/{id}/tasks
Crea una tarea: title y, si quieres, notes, priority, due, assignee, sprintId, estimateMin, after, labels, milestone (un hito), companions (quienes la acompañan) y checklist (su lista de comprobación). Exige 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":"Llamar a Ana","due":"2026-10-20"}'PATCH /api/v1/tasks/{id}
Cambia solo los campos que mandes; la lista de comprobación, elemento a elemento (checklist: marcar, reescribir, quitar o añadir, con los ids que da la tarea), y los acompañantes, la lista entera (companions: léela antes y manda todos los nombres que deban quedar). Responde con la tarea, las que se desbloquean y, si otra persona cambió lo mismo a la vez, lo que se quedó.
Á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 la tarea como hecha (también una cancelada) y responde con las 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
Vuelve a abrir una tarea hecha o cancelada.
Ámbito: write
POST /api/v1/tasks/{id}/cancel
Cancela la tarea: se cierra sin contar como hecha y las que la esperaban ya pueden empezar. Responde con las 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}
Hace que la tarea espere a otra del mismo proyecto o de otro proyecto del mismo dueño (afterOutside). Con days en el cuerpo, además, que pasen esos días desde que acabe la otra (de 1 a 365; 0 los quita).
Á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 la tarea, como en la web: pasa 30 días por la papelera, de donde se puede restaurar desde la web.
Ámbito: write
GET /api/v1/projects/{id}/labels
Las etiquetas del proyecto, por orden alfabético: id, nombre y color.
Ámbito: read
POST /api/v1/projects/{id}/labels
Crea una etiqueta en el proyecto: name y, si quieres, color. Si ya hay una con ese nombre, responde con esa.
Ámbito: write
GET /api/v1/webhooks
Los avisos a otras apps que ha creado este token: dirección, eventos, proyectos y estado (nunca el secreto).
Ámbito: webhooks
POST /api/v1/webhooks
Apunta una dirección https para recibir avisos firmados: url, events y, si quieres, projects (solo tuyos). Responde con el secreto, una sola vez.
Ámbito: webhooks
DELETE /api/v1/webhooks/{id}
Borra uno de los avisos que creó este token y deja de mandarlo.
Ámbito: webhooks
Avisos a otras apps (webhooks)
Cuando pasa algo en tus proyectos, tokidu manda un POST firmado a la dirección que digas. Se crean en Cuenta → Integraciones, o por la API con un token con el ámbito webhooks (lo que usan Zapier o Make). Solo el dueño con Max, y solo de sus proyectos; hasta 20 por cuenta.
Qué puedes escuchar
task.created· Se crea una tareatask.done· Se termina una tareatask.cancelled· Se cancela una tareatask.reopened· Se reabre una tareatask.unblocked· Se desbloquea una tareatask.assigned· Se asigna una tareatask.deleted· Se borra una tareacomment.created· Alguien comenta una tareaproject.status· Cambia el semáforo de un proyectoproject.duplicated· Se duplica un proyectoproject.imported· Se importa un proyecto
Cada aviso lleva el tipo, un id del hecho, la hora, el proyecto y, si es de una tarea, su título, estado, si está cancelada, si es un hito, sus etiquetas, el nombre de quien la tiene asignada y de quienes la acompañan, la fecha límite y el enlace. Las tareas que crea una repetición llegan como cualquier tarea nueva (task.created). Nunca notas, enlaces, archivos, correos ni horas. De un comentario, solo quién lo escribió: nunca el texto.
Comprobar la firma
Sigue Standard Webhooks: cabeceras webhook-id, webhook-timestamp (segundos) y webhook-signature (v1, y un HMAC-SHA256 en base64 de id.timestamp.cuerpo, con la clave que va detrás de whsec_). Compruébala con el cuerpo tal cual llega y rechaza los de más 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 y reintentos
Cualquier 2xx es bueno; las redirecciones no se siguen. Si falla, se reintenta a 1 min, 5 min, 30 min, 2 h, 6 h, 12 h y 24 h. Con 20 entregas fallidas seguidas, o 3 días sin un 2xx, el aviso se apaga y te mandamos un correo.
Solo direcciones https:// públicas, en el puerto 443 u 8443, sin usuario ni contraseña: nada de localhost, redes internas ni IP privadas (se comprueba también al enviar).
Agentes de IA (MCP)
Con MCP (Model Context Protocol), un agente de IA como Claude Code puede usar tokidu por ti: decirte qué te toca, buscar tareas, leer sus comentarios y, si el token lo deja, crearlas, cambiarlas, terminarlas y cancelarlas. Va sobre esta API y con el mismo token: el agente nunca hace nada que no pueda hacer ese token.
- Dirección
https://tokidu.com/api/mcp- Cabecera
Authorization: Bearer tkd_…
Conectar Claude Code
Crea un token en Cuenta → Integraciones y pega esto en la terminal, con tu token en lugar de tkd_…:
claude mcp add --transport http tokidu https://tokidu.com/api/mcp \
--header "Authorization: Bearer tkd_…"En cualquier otro cliente que deje poner una cabecera, usa la misma dirección y la misma cabecera.
Qué deja hacer el token
read, «Ver tus proyectos y tareas»: conectar el agente y usar las herramientas que leen.write, «Crear y cambiar tareas»: además, las que crean y cambian tareas y esperas.- Si el token llega solo a unos proyectos, el agente solo ve esos. El token de Madrugo (
integrations:read) no sirve para el MCP.
Herramientas
Cada una pide un ámbito del token. Los nombres van en inglés, como es costumbre en MCP.
list_projects- Los proyectos que ve el token, con su cliente, su semáforo, su fin previsto y la foto del plan.Ámbito:
read next_up- «Lo siguiente»: lo tuyo que ya se puede empezar, de todos los proyectos o de uno.Ámbito:
read get_project- Un proyecto, sus etiquetas, sus repeticiones y sus tareas abiertas: cuándo se prevé que acaben, si están bloqueadas, los días de más de sus esperas, cuáles son hitos, quién las acompaña y cuánto llevan marcado de su lista de comprobación.Ámbito:
read get_task- Una tarea con sus notas, su lista de comprobación, quién la acompaña, de qué repetición salió, a qué espera (y desde cuándo podrá empezar, si faltan los días de una espera) y «¿Por qué esa fecha?».Ámbito:
read list_comments- Los comentarios de una tarea, para leerlos: el texto, quién lo escribió y cuándo. Ninguna herramienta escribe comentarios.Ámbito:
read search_tasks- Busca tareas por el título en los proyectos que ve el token.Ámbito:
read create_task- Crea una tarea (o un hito), también con su lista de comprobación y quienes la acompañan. Si el cliente repite la misma petición dentro del mismo bloque de 10 minutos del reloj, no se duplica; para reintentar sin riesgo, que mande
idempotency_key.Ámbito:write update_task- Cambia solo los campos de la tarea que mande (también sus etiquetas, si es un hito, quienes la acompañan, siempre la lista entera, y, elemento a elemento, su lista de comprobación).Ámbito:
write complete_task- Marca la tarea como hecha y dice cuáles se desbloquean.Ámbito:
write cancel_task- Cancela una tarea que ya no se va a hacer: no cuenta como hecha y dice cuáles se desbloquean.Ámbito:
write add_wait- Hace que una tarea espere a otra y, con
days, que pasen además unos días desde que acabe.Ámbito:write remove_wait- Quita una espera.Ámbito:
write
Lo que conviene saber
- No hay herramientas para borrar tareas ni proyectos, ni para comentar, ni para crear o cambiar repeticiones, ni para personas, invitaciones, horas, archivos o avisos a otras apps. Pero
update_taskpuede cambiar o vaciar los campos de una tarea (las notas no guardan versiones anteriores),add_waitcondayscambia o quita los días de una espera yremove_waitquita esperas: dawriteal token solo si quieres eso. - Comparte los límites de la API (1000 peticiones por hora y cuenta, 60 por minuto y token): cada herramienta es una llamada a la API (
get_project, dos) y gasta de los dos; lo demás que manda el cliente (initialize,tools/list,ping,server/discover, las notificaciones y las herramientas que no llegan a la API porque un dato no vale) gasta uno del minuto, pero no de la hora. - En «Últimos cambios con este token» salen, marcados con MCP, los cambios que hace y los intentos rechazados (401, 403 y 429, uno por minuto como mucho); lo que solo lee, no.
- Los títulos, las notas, los elementos de las listas de comprobación, los comentarios y los nombres los escriben personas: tokidu se los da al agente como datos, en sus propios campos y, dentro de las frases de «¿Por qué esa fecha?» y del semáforo, entre comillas «», y le dice que nunca son instrucciones.
- Todavía no hay OAuth, así que tokidu no se puede añadir como conector en claude.ai. Funciona en Claude Code y en cualquier cliente que deje poner una cabecera.
- Sin sesión: cada petición es un
POSTcon JSON-RPC y la respuesta va siempre en JSON. - Versiones del protocolo: la moderna y, para los clientes de antes, las que empiezan con
initialize:2026-07-28,2025-11-25,2025-06-18,2025-03-26.
OpenAPI
Todos los campos de cada petición y de cada respuesta, en formato OpenAPI, para generar un cliente o importarlos en tu herramienta: /api/v1/openapi.json.