Comment on selected document text or reply to a comment thread
/v1/knowledge/{libraryId}/documents/{documentId}/commentsRequires knowledge write permission and the library documents-manage capability. The authenticated principal is always the author. New threads require an anchor for the current saved revision; replies inherit their root comment's anchor. Repeating an identical id and payload is idempotent; reusing an id with different content returns 409. Comments do not change document content or create library versions. Mentions are stored references; this operation does not launch agent runs.
How to call this endpoint
Every ACP API request uses bearer authentication. The examples here show the actual request path, auth header, and body shape that the platform expects.
Path, query, and header parameters
These parameters control which ACP object the endpoint acts on and how the request is processed.
| Name | Location | Type | Required | Description |
|---|---|---|---|---|
| libraryId | path | string | Yes | Knowledge library ID |
| documentId | path | string | Yes | Stable Knowledge document ID |
Body schema
Content type: application/json · Required
What the API returns
Each response code below includes the documented payload shape for the ACP API.
| Field | Type | Required | Description |
|---|---|---|---|
| comment | object | Yes | — |
| comment.id | string | Yes | Unique identifier. |
| comment.libraryId | string | Yes | — |
| comment.documentId | string | Yes | Document ID. |
| comment.threadId | string | Yes | Root comment id; equal to id on root comments. |
| comment.authorUserId | string | Yes | — |
| comment.author | object | Yes | — |
| comment.author.id | string | Yes | Unique identifier. |
| comment.author.name | string | Yes | Human-readable name. |
| comment.author.email | string | Yes | — |
| comment.author.avatarUrl | string | Yes | — |
| comment.body | string | Yes | — |
| comment.anchor | object | Yes | — |
| comment.anchor.revisionId | string | Yes | — |
| comment.anchor.start | integer | Yes | UTF-16 offset into rendered text with one newline between text blocks. |
| comment.anchor.end | integer | Yes | Exclusive UTF-16 offset; end minus start equals quote length. |
| comment.anchor.quote | string | Yes | — |
| comment.anchor.prefix | string | Yes | — |
| comment.anchor.suffix | string | Yes | — |
| comment.mentions | object[] | Yes | — |
| comment.mentions[].kind | human | agent | Yes | — |
| comment.mentions[].id | string | Yes | Unique identifier. |
| comment.mentions[].label | string | Yes | — |
| comment.createdAt | string | Yes | ISO 8601 timestamp. |