Comments API

GET /boards/:id/comments lists a board's comment threads in one list, the ones on the canvas and the ones inside its docs and notes, each with its replies and who wrote what. POST adds a comment on a card, a group, a spot, the whole board or words in a doc, or a reply in any thread. PATCH resolves or reopens threads, and DELETE removes your own comment.

Updated October 25, 2026

A board's comments are read and written here: the bubbles on its canvas, and the threads inside its docs and notes. Everything runs as you, so the API lets you do with a comment exactly what the app does.

GET /boards/:id/comments

Every comment thread on the board, in one list: on the canvas, and inside its docs and notes.

{
  "board_id": "9f1c…", "status": "open", "counts": { "open": 2, "resolved": 5 },
  "threads": [
    { "id": "cm_k3v8x0q2", "on": "doc", "card_id": "d-4", "card_title": "Treatment",
      "page_title": "Opening", "quote": "at night",
      "body": "Too slow?", "author_name": "Sam Park", "by_you": false, "resolved": false, "replies": [] },
    { "id": "6a0e…", "on": "card", "card_id": "c-3", "card_title": "Hero still",
      "body": "Too dark", "author_name": "Ana Ruiz", "by_you": true, "resolved": false,
      "replies": [{ "id": "41bd…", "body": "Agreed", "author_name": "Sam Park", "by_you": false }] }
  ],
  "has_more": false, "next_cursor": null
}

Every thread and reply also carries author_id and created_at, and every thread a url that opens it in the app.

The liveliest thread comes first: one moves up when someone replies to it. counts tells you how many are open and resolved, whichever you asked for.

Each thread says what it is on, and carries only the fields that go with it:

quote is the text the thread is on, up to 300 characters. A name is the one the person set, else one made from their email, as the app shows it. by_you marks what you wrote. A thread someone hid on the canvas carries hidden: true. When the threads inside docs and notes can't be read just then, the list holds the board's own and a note says so.

POST /boards/:id/comments

A comment, in your name.

{ "body": "Warmer grade?", "card_id": "c-3" }

Send one of card_id, group_id, or x and y, or none of them for a comment about the board as a whole. The bubble is placed as the app places one: beside its card or group, on the side where it covers least, and a comment on the whole board beside everything on it.

A reply takes no place of its own: it goes into its thread, wherever the thread is, so it stays with the card when the card moves. reply_to can name the thread or any reply in it.

It answers 201 with the comment as the list has it, or a reply as a thread's replies are, with reply_to naming its thread.

On words in a doc

With a doc's card_id and quote, the comment starts a thread on those words, highlighted as a selection is when you comment in the app. Quote them as reading the doc gives them (spacing, curly quotes and Markdown marks don't matter), up to 2000 characters. Words that aren't there, or are there more than once, answer 400 saying so: quote more of the words around them, or name the page with page_id. A note's words take a comment in the app.

PATCH /boards/:id/comments/:commentId

{ "resolved": true }

Resolves a thread, as its Resolve button does, or reopens it with false. Name the thread: a reply answers 400, naming its thread.

PATCH /boards/:id/comments

{ "comment_ids": ["cm_k3v8x0q2", "6a0e…"], "resolved": true }

Up to 50 threads of either kind at once, each checked on its own. The answer lists them as changed (one already so counts), not_found, or refused, each refusal with a code and a reason.

DELETE /boards/:id/comments/:commentId

Deletes a comment you wrote. On the canvas its replies go with it, and come back with it. Like every delete, it needs a token with the delete scope. It can be restored for 30 days:

POST /boards/:id/comments/:commentId/restore

Brings a deleted comment back. Restoring one that isn't deleted changes nothing.

A thread of yours inside a doc can be deleted until someone else replies in it (409 after that: resolve it instead). Its highlight goes with it, for good.

Who can do what

An editor is anyone who can edit the board. Anything else answers 403. A board you can't open, or a comment that isn't on it, answers 404.

Threads inside docs and notes

Their ids start cm_, and their replies' cr_. They live in the doc itself and are written through the board's live room, so everyone with it open sees them at once. When the room can't be reached nothing is written, and the answer is 503 room_unavailable: try again. As in the app, a resolved thread takes no reply until it is reopened (409).

Machine-readable: /docs/api/comments.md · /llms.txt
What changed and when: /changelog