Cómo funcionaPreciosDemoNoticiasAyuda
ES
  • Español
  • Català
  • English
  • Galego
EntrarEmpezar gratis

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

  1. En Cuenta → Integraciones, crea un token y marca «Ver tus proyectos y tareas» (y «Crear y cambiar tareas», si va a escribir).
  2. 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.
  3. 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-Remaining y RateLimit-Reset: el límite, lo que queda y cuándo se renueva.
  • Si te pasas, la respuesta es 429 demasiadas_peticiones con Retry-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-Key corresponde 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 (max dice cuántas): borra alguna en la web o en la app para crear otra.
410 tarea_borrada
Esa Idempotency-Key es 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: field dice cuál.
422 url_no_valida
La dirección de un aviso no vale: reason dice por qué (https, puerto, usuario, local, tokidu, dns o ip_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 tarea
  • task.done · Se termina una tarea
  • task.cancelled · Se cancela una tarea
  • task.reopened · Se reabre una tarea
  • task.unblocked · Se desbloquea una tarea
  • task.assigned · Se asigna una tarea
  • task.deleted · Se borra una tarea
  • comment.created · Alguien comenta una tarea
  • project.status · Cambia el semáforo de un proyecto
  • project.duplicated · Se duplica un proyecto
  • project.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_task puede cambiar o vaciar los campos de una tarea (las notas no guardan versiones anteriores), add_wait con days cambia o quita los días de una espera y remove_wait quita esperas: da write al 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 POST con 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.

© 2026 tokidu
  • Precios
  • Demo
  • Noticias
  • Ayuda
  • API
  • Sobre tokidu
  • Privacidad
  • Términos
  • Español
  • Català
  • English
  • Galego
Un producto de Sinergia, agencia de diseño web en Barcelona