La API te deja leer tus tableros y crear tarjetas desde scripts, automatizaciones o agentes, sin iniciar sesión. Creá un token en Ajustes → Tokens de API. El token se muestra una sola vez, así que guardalo en un lugar seguro.
Autenticación
Mandá el token en el header Authorization. Todos los endpoints de abajo lo piden.
curl https://decknote.app/api/v1/me \
-H "Authorization: Bearer ntrl_your_token_here"
Si el token falta o no es válido, la respuesta es 401. Cada token tiene los permisos de quien lo creó: podés leer cualquier tablero al que tengas acceso y escribir en cualquiera donde seas editor o dueño.
Errores
Los errores vuelven con el status HTTP que corresponde y un cuerpo JSON de la forma { "error": "message" }. Si te pasás de un límite de pedidos, la respuesta es 429 con un header Retry-After.
La forma más simple de conseguir un token es Ajustes → Tokens de API: creá uno y pegalo en la configuración del MCP, más abajo. Para un CLI o un agente que puede manejar un navegador, Decknote también ofrece un flujo de autorización de dispositivo (con la misma forma que gh auth login), que anda por SSH y en contenedores donde no hay un navegador al que volver.
POST /api/v1/cli/auth arranca un flujo y devuelve un código de dispositivo (que se queda quien llama) y un código de usuario corto (el que ve la persona). La persona abre /cli, se fija que el código coincida y lo aprueba con la sesión iniciada. Quien llama consulta POST /api/v1/cli/auth/token cada tanto y recibe el token una sola vez — 202 mientras está pendiente, 200 con { token } cuando se aprueba, 410 cuando el código venció. Los códigos duran diez minutos, y el token que se emite cuenta para el límite de tu plan (el gratis incluye uno).
Hay un cliente de referencia para este flujo en cli/ (el paquete decknote).
Aprobá solo un código que generaste vos — si aprobás el de otra persona, le das un token de tu cuenta.
Decknote tiene un servidor de Model Context Protocol para que un agente de IA use un tablero como lista de tareas: agrega tareas, las completa y las vuelve a buscar — una memoria compartida entre tus agentes y tu equipo. Habla MCP sobre Streamable HTTP (protocolo 2025-06-18) y se autentica con el mismo token Authorization: Bearer que la API REST.
Endpoint
POST https://decknote.app/api/v1/mcp
Conectate desde un cliente MCP
Apuntá cualquier cliente MCP al endpoint y pasale tu token como header Bearer. Por ejemplo, en la configuración MCP de Claude / Claude Code:
{
"mcpServers": {
"decknote": {
"type": "http",
"url": "https://decknote.app/api/v1/mcp",
"headers": { "Authorization": "Bearer ntrl_your_token_here" }
}
}
}
Una llamada directa a tools/list, para comprobar que anda:
curl -X POST https://decknote.app/api/v1/mcp \
-H "Authorization: Bearer ntrl_your_token_here" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
Herramientas
list_boards — descubrir tableros y listas (empezá por acá).create_board — crear un tablero, opcionalmente a partir de una plantilla (blank, kanban, content, personal).create_list — agregar una lista (columna) al final de un tablero.search_tasks — recordar: buscar tareas por texto, estado y vencimiento.get_task — leer una tarea completa.create_task — agregar una tarea a una lista. La descripción acepta Markdown.update_task — editar el título, la descripción (Markdown) o el vencimiento.complete_task / reopen_task — marcar como hecha o reabrir.move_task — mover una tarea a otra lista.archive_task — archivar una tarea (borrado lógico); las tareas recurrentes con fecha programan su próxima repetición.add_comment — dejar una nota de avance para que la lea una persona.
Cada herramienta devuelve su resultado como JSON dentro de un bloque de contenido de texto: result.content[0].text es un string JSON que tenés que parsear. Una tarea tiene la forma { id, title, listId, boardId, dueDate, completed, description, url }; las herramientas que escriben devuelven { task }, search_tasks devuelve { tasks: [...] } y list_boards devuelve { boards: [{ id, title, lists }] }.
Cada herramienta se limita a los tableros a los que accede tu token, con los mismos permisos que la API REST: puede leer cualquier tablero del que seas miembro y escribir en cualquiera donde seas editor o dueño. Los errores de las herramientas (sin acceso, datos inválidos) vuelven como un resultado de error de MCP (un bloque de contenido de texto con isError: true), no como una conexión cortada. Las llamadas MCP tienen su propio límite de pedidos — unas 200 por minuto por token, aparte de lo que uses de la API REST.
Exportar tus datos
La API es para automatizar, no para hacer backups. Para llevarte todo — tableros, listas, tarjetas, checklists, comentarios y los datos de los adjuntos — usá Ajustes → Tus datos, o pedí /api/export con la sesión iniciada. Devuelve un solo archivo JSON y está disponible en todos los planes.