---
audience: developer
summary: Comment threads scoped to a note.
title: Comments API
path: reference/api/comments
status: published
---

# 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.