API: comments

Status: GA Access: token required API contract: 0.3.0 · capability 2026-09-03.1 View as Markdown Open in Claude Open in ChatGPT

`GET /api/v1/comments`

List Comments

: list filtered by target.

Auth: Authorization: Bearer <token> required

Parameter	In	Required	Type
`target_kind`	query	no	`string \| null`
`target_guid`	query	no	`integer \| null`
`include_deleted`	query	no	`boolean`
`limit`	query	no	`integer`
`offset`	query	no	`integer`

Responses:

Code	Meaning	Body
`200`	Successful Response	`CommentList`
`401`	Missing or invalid authentication credentials	`ErrorResponse`
`422`	Validation Error	`HTTPValidationError`

Create Comment

: create a comment, resolve @mentions, record agent mentions as an agent action.

Auth: Authorization: Bearer <token> required

Parameter	In	Required	Type	Description
`Idempotency-Key`	header	no	`string`	Optional.

Request body: application/json — schema CommentCreate

Field	Type	Required
`body_markdown`	`string`	yes
`target_guid`	`integer`	yes
`target_kind`	`string`	yes

Responses:

Code	Meaning	Body
`201`	Successful Response	`CommentRead`
`401`	Missing or invalid authentication credentials	`ErrorResponse`
`422`	Validation Error	`HTTPValidationError`

Delete Comment

: soft-delete.

Auth: Authorization: Bearer <token> required

Parameter	In	Required	Type	Description
`guid`	path	yes	`integer`
`Idempotency-Key`	header	no	`string`	Optional.

Responses:

Code	Meaning	Body
`200`	Successful Response	`object`
`401`	Missing or invalid authentication credentials	`ErrorResponse`
`422`	Validation Error	`HTTPValidationError`

Get Comment

Auth: Authorization: Bearer <token> required

Parameter	In	Required	Type	Description
`guid`	path	yes	`integer`

Responses:

Code	Meaning	Body
`200`	Successful Response	`CommentRead`
`401`	Missing or invalid authentication credentials	`ErrorResponse`
`422`	Validation Error	`HTTPValidationError`

Patch Comment

: PATCH only by author (or superuser).

Auth: Authorization: Bearer <token> required

Parameter	In	Required	Type	Description
`guid`	path	yes	`integer`
`Idempotency-Key`	header	no	`string`	Optional.

Request body: application/json — schema CommentUpdate

Field	Type	Required	Description
`body_markdown`	`string \| null`	no

Example:

{
  "body_markdown": "Edited: the figure is confirmed by the source."
}

Responses:

Code	Meaning	Body
`200`	Successful Response	`CommentRead`
`401`	Missing or invalid authentication credentials	`ErrorResponse`
`422`	Validation Error	`HTTPValidationError`