comments

5 endpoints at a glance

Method	Path	Summary
GET	/comments/	List Comments
POST	/comments/	Create Comment
DELETE	/comments/{comment_id}	Delete Comment
PATCH	/comments/{comment_id}	Update Comment
POST	/comments/counts/	Counts For Targets

comments

---

List Comments

GET

/comments/

Authenticated list, newest-first, scoped to one
(collection, doc_id) pair.

The viewer's username gates the privacy filter — public comments
return for everyone authenticated, private comments only to their
author. Anonymous callers get 401 from
:func:api.auth.get_current_user.

Parameters

Header Parameters

authorization

x-api-key

Query Parameters

collection*

Type

string

Required

doc_id*

Required

Responses

Successful Response

Content-Type

application/json

[

  

{

  

  

"additionalProperties": "string"

  

}

]

GET

/comments/

Playground

Headers

authorization

x-api-key

Variables

Key

Value

collection*

doc_id*

Samples

---

Create Comment

POST

/comments/

Authenticated. Validates the target row exists in its collection
so a typo can't create an orphan comment.

Parameters

Header Parameters

authorization

x-api-key

Request Body

application/json

{

  

"target": {

  

  

"collection": "string",

  

  

"doc_id": 0

  

},

  

"body": "string",

  

"private": false

}

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

POST

/comments/

Playground

Headers

authorization

x-api-key

Body

Samples

---

Counts For Targets

POST

/comments/counts/

Batched {<collection>:<doc_id>: <count>} map for the
per-row "N comments" badge. Privacy-filtered against the viewer
— counts reflect what they would see in
:func:list_comments.

Parameters

Header Parameters

authorization

x-api-key

Request Body

application/json

{

  

"targets": [

  

  

{

  

  

  

"collection": "string",

  

  

  

"doc_id": 0

  

  

}

  

]

}

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": 0

}

POST

/comments/counts/

Playground

Headers

authorization

x-api-key

Body

Samples

---

Delete Comment

DELETE

/comments/{comment_id}

Author OR admin. Hard-delete; no tombstone.

Parameters

Header Parameters

authorization

x-api-key

Path Parameters

comment_id*

Type

string

Required

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

DELETE

/comments/{comment_id}

Playground

Headers

authorization

x-api-key

Variables

Key

Value

comment_id*

Samples

---

Update Comment

PATCH

/comments/{comment_id}

Author-only edit. Patches body and/or private —
model_fields_set lets the caller change either independently.
edited flips on body changes only.

Parameters

Header Parameters

authorization

x-api-key

Path Parameters

comment_id*

Type

string

Required

Request Body

application/json

{

  

"body": "string",

  

"private": true

}

Responses

Successful Response

Content-Type

application/json

{

  

"additionalProperties": "string"

}

PATCH

/comments/{comment_id}

Playground

Headers

authorization

x-api-key

Variables

Key

Value

comment_id*

Body

Samples

---