API Documentation

Decknote REST API, version 1

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.

Endpoints

get`/api/v1/me`

Rate limit: 120 requests/minute

Returns the user the token belongs to. Useful to verify a token works.

{
  "user": { "id": "clx…", "name": "Jodie", "email": "jodie@example.com" }
}

get`/api/v1/boards`

Rate limit: 120 requests/minute

Every board you can access, each with its lists in display order. This is how you discover the listId values you need to create cards.

{
  "boards": [
    {
      "id": "clx…",
      "title": "Returns",
      "lists": [
        { "id": "cly…", "title": "Requested" },
        { "id": "clz…", "title": "Refunded" }
      ]
    }
  ]
}

post`/api/v1/cards`

Rate limit: 30 requests/minute

Creates a card. Send a JSON body:

listId — the list to create it in. Alternatively send boardIdand the card lands in that board's first list. One of the two is required.
title — required, up to 500 characters.
description — optional plain text, up to 20,000 characters. Line breaks become paragraphs.
dueDate — optional ISO 8601 datetime, e.g. 2026-09-01T15:00:00Z.

curl -X POST https://decknote.app/api/v1/cards \
  -H "Authorization: Bearer ntrl_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "listId": "cly…",
    "title": "Refund #1042",
    "description": "Customer reported a damaged item.",
    "dueDate": "2026-09-01T15:00:00Z"
  }'

Returns the created card:

{
  "card": {
    "id": "cm…",
    "title": "Refund #1042",
    "listId": "cly…",
    "boardId": "clx…",
    "dueDate": "2026-09-01T15:00:00Z",
    "url": "/board/clx…?card=cm…"
  }
}

On success returns 201. Creating a card writes to the board activity log and shows up live for anyone viewing it, exactly like creating one in the app.

Card-specific errors:

400 — invalid body (missing title, or neither listId nor boardId).
403 — the token owner is not an editor or owner of that board.
404 — the list or board was not found.

CLI login (get a token from the browser)

Instead of pasting a token, a CLI or an agent can obtain one through the browser — the same device-authorization flow as gh auth login. It works over SSH and in containers, where there is no browser to redirect back to.

npx decknote login          # opens a URL and prints a short code
# approve it in the browser (you must be signed in)
# the token is saved to ~/.config/decknote.json

npx decknote mcp-config     # prints the MCP config, ready to paste

Under the hood: POST /api/v1/cli/auth starts a flow and returns a device code (kept by the CLI) and a short user code (shown to you). You open /cli, check the code matches, and approve. The CLI polls POST /api/v1/cli/auth/tokenand receives the token exactly once. Codes expire after ten minutes, and the token counts against your plan's limit (Free includes one).

Only approve a code you generated yourself — approving someone else's hands them a token on your account.

MCP server (for AI agents)

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).
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.
update_task — edit title, description or due date.
complete_task / reopen_task — mark done or reopen.
move_task — move a task to another list.
add_comment — leave a progress note a human will read.

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, not a broken connection. Requests share a single rate limit per token — a few hundred calls per minute — with 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.