The API lets you read your boards and create cards from scripts, automations or agents, without logging in. Create a token in Settings → API Tokens. The token is shown once, so store it somewhere safe.
Authentication
Send the token in the Authorization header. Every endpoint below requires it.
curl https://decknote.app/api/v1/me \
-H "Authorization: Bearer ntrl_your_token_here"
A missing or invalid token returns 401. Tokens carry the permissions of the user who created them: you can read any board you have access to, and write to any board where you are an editor or the owner.
Errors
Errors return the matching HTTP status and a JSON body of the form { "error": "message" }. Exceeding a rate limit returns 429 with a Retry-After header.
The simplest way to get a token is Settings → API Tokens — create one and paste it into the config above. For a CLI or an agent that can drive a browser, Decknote also exposes a device-authorization flow (the same shape as gh auth login), which works over SSH and in containers where there is no browser to redirect back to.
POST /api/v1/cli/auth starts a flow and returns a device code (kept by the caller) and a short user code (shown to the human). The human opens /cli, checks the code matches, and approves while signed in. The caller polls POST /api/v1/cli/auth/token and receives the token exactly once — 202 while pending, 200 with { token } once approved, 410when the code has expired. Codes last ten minutes, and the minted token counts against your plan's limit (Free includes one).
A reference client for this flow lives in cli/ (the decknote package).
Only approve a code you generated yourself — approving someone else's hands them a token on your account.
Decknote runs a Model Context Protocol server so an AI agent can use a board as a task list it adds to, completes and recalls from — a shared memory between your agents and your team. It speaks MCP over Streamable HTTP (protocol 2025-06-18), authenticated with the same Authorization: Bearer token as the REST API.
Endpoint
POST https://decknote.app/api/v1/mcp
Connect from an MCP client
Point any MCP client at the endpoint and pass your token as a Bearer header. For example, in a Claude / Claude Code MCP config:
{
"mcpServers": {
"decknote": {
"type": "http",
"url": "https://decknote.app/api/v1/mcp",
"headers": { "Authorization": "Bearer ntrl_your_token_here" }
}
}
}
A raw tools/list call, to check it works:
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"}'
Tools
list_boards — discover boards and lists (start here).create_board — create a board, optionally from a template (blank, kanban, content, personal).create_list — add a list (column) at the end of a board.search_tasks — recall: find tasks by text, status and due date.get_task — read one task in full.create_task — add a task to a list. The description accepts Markdown.update_task — edit title, description (Markdown) or due date.complete_task / reopen_task — mark done or reopen.move_task — move a task to another list.archive_task — archive (soft-delete) a task; recurring dated tasks schedule their next occurrence.add_comment — leave a progress note a human will read.
Each tool returns its result as JSON inside a text content block —result.content[0].text is a JSON string you parse. A task looks like { id, title, listId, boardId, dueDate, completed, description, url }; the write tools return { task }, search_tasks returns { tasks: [...] }, and list_boards returns { boards: [{ id, title, lists }] }.
Every tool is scoped to the boards your token can access, with the same permissions as the REST API: it can read any board you belong to and write to any board where you are an editor or owner. Tool errors (no access, invalid input) come back as an MCP error result (a text content block with isError: true), not a broken connection. MCP calls have their own rate limit — about 200 per minute per token, separate from your REST usage.
Exporting your data
The API is for automation, not for backups. To take everything with you — boards, lists, cards, checklists, comments and attachment metadata — use Settings → Your data, or request /api/export while signed in. It returns a single JSON file and is not restricted by plan.