Comments API

8 endpoints. Comments are a lightweight chat surface attached to a specific note — review feedback, clarifying questions, async discussion that shouldn't live in a room.

Two URL families because notes can be addressed either by id alone or by workspace + id; both routes resolve to the same handler.

By note id#

Method	Path	Purpose
`GET`	`/v1/notes/{note_id}/comments`	List comments on a note.
`POST`	`/v1/notes/{note_id}/comments`	Add a comment.
`POST`	`/v1/notes/{note_id}/comments/{comment_id}/resolve`	Mark resolved.
`DELETE`	`/v1/notes/{note_id}/comments/{comment_id}`	Delete (author or `power_level ≥ 50` on workspace).

Workspace-scoped (equivalent)#

Method	Path	Purpose
`GET`	`/v1/workspaces/{ws}/notes/{note_id}/comments`	Same.
`POST`	`/v1/workspaces/{ws}/notes/{note_id}/comments`	Same.
`POST`	`/v1/workspaces/{ws}/notes/{note_id}/comments/{comment_id}/resolve`	Same.
`DELETE`	`/v1/workspaces/{ws}/notes/{note_id}/comments/{comment_id}`	Same.

POST body#

json
{
  "body": "Should we use the new schema here?",
  "anchor": "block-id-or-line-range-optional",
  "reply_to": "comment-id-optional"
}

anchor lets you scope a comment to a specific line / block / range in the note body — clients render an inline marker.

reply_to threads the comment.

Resolve#

Resolved comments still show in the thread but with a dimmed style. A note's comment count badge shows unresolved-only.

Events#

Posting a comment emits swp.note.comment to room WebSocket listeners (note views are subscribed) so the comment count badge updates live.

Updated 2026-05-17 13:10:03 View source (.md) rev 3