Comments

Threaded comment system with inline anchoring support. Comments are organized in threads attached to specific positions within documents.

Base Path: /api/v1/comments Authentication: Required (Bearer Token) Tag: Comments

---

List Comment Threads

Retrieve all comment threads for a document.

GET /comments/documents/{documentId}/threads?status={status}

Path Parameters

Parameter	Type	Description
documentId	UUID	Document ID

Query Parameters

Parameter	Type	Required	Default	Values	Description
status	String	No	all	all, open, resolved	Filter by thread status

Response

{
  "success": true,
  "data": [
    {
      "id": "...",
      "documentId": "...",
      "workspaceId": "...",
      "anchor": {
        "blockId": "block-123",
        "startOffset": 10,
        "endOffset": 25,
        "selectedText": "highlighted text"
      },
      "status": "open",
      "resolvedAt": null,
      "resolvedBy": null,
      "comments": [
        {
          "id": "...",
          "threadId": "...",
          "userId": "...",
          "userName": "John Doe",
          "userAvatar": "https://...",
          "content": "This needs revision",
          "isEdited": false,
          "createdAt": "2025-01-15T10:00:00Z",
          "updatedAt": "2025-01-15T10:00:00Z"
        }
      ],
      "createdAt": "2025-01-15T10:00:00Z",
      "updatedAt": "2025-01-15T10:00:00Z"
    }
  ]
}

Response Type: ApiResponse<List<CommentThreadResponse>>

---

Create Comment Thread

Create a new comment thread anchored to a specific position in the document.

POST /comments/documents/{documentId}/threads

Path Parameters

Parameter	Type	Description
documentId	UUID	Document ID

Request Body

{
  "anchor": {
    "blockId": "block-123",
    "startOffset": 10,
    "endOffset": 25,
    "selectedText": "highlighted text"
  },
  "comment": {
    "content": "This section needs more detail."
  }
}

Field	Type	Required	Description
anchor	Object	Yes	Position info (blockId, offsets, text)
comment	Object	Yes	Initial comment
comment.content	String	Yes	Comment text (supports @mentions)

Response

Status: 201 Created Response Type: ApiResponse<CommentThreadResponse>

---

Resolve Thread

Mark a comment thread as resolved.

PUT /comments/threads/{threadId}/resolve

Path Parameters

Parameter	Type	Description
threadId	UUID	Thread ID

Response Type: ApiResponse<CommentThreadResponse>

---

Reopen Thread

Reopen a previously resolved thread.

PUT /comments/threads/{threadId}/reopen

Path Parameters

Parameter	Type	Description
threadId	UUID	Thread ID

Response Type: ApiResponse<CommentThreadResponse>

---

Delete Thread

Delete a comment thread and all its comments.

DELETE /comments/threads/{threadId}

Path Parameters

Parameter	Type	Description
threadId	UUID	Thread ID

Response Type: ApiResponse<Void>

---

Add Comment to Thread

Add a reply comment to an existing thread.

POST /comments/threads/{threadId}/comments

Path Parameters

Parameter	Type	Description
threadId	UUID	Thread ID

Request Body

{
  "content": "I agree, let me fix this."
}

Field	Type	Required	Validation	Description
content	String	Yes	Not blank	Comment text

Response

Status: 201 Created Response Type: ApiResponse<CommentResponse>

---

Update Comment

Edit an existing comment.

PUT /comments/{commentId}

Path Parameters

Parameter	Type	Description
commentId	UUID	Comment ID

Request Body

{
  "content": "Updated comment text"
}

Field	Type	Required	Validation	Description
content	String	Yes	Not blank	New comment text

Response Type: ApiResponse<CommentResponse>

info

Only the comment author can edit their own comments. The isEdited flag will be set to true.

---

Delete Comment

Delete a comment from a thread.

DELETE /comments/{commentId}

Path Parameters

Parameter	Type	Description
commentId	UUID	Comment ID

Response Type: ApiResponse<Void>