Document comments

Documents can carry threaded comments that are pinned to a position on the document canvas. A thread has a position and one or more comments (the first comment plus replies). Comments can mention team members, who are notified by email.

Comments live under a document, so all routes are relative to a document:

…/api/v1/users/id/documents/doc/comments

Reading comment threads only requires read access to the document. Posting new threads, replies, and moving threads also only require read access. Deleting requires write access, and the document must belong to a team or organization.

Data model

A comment thread has these fields:

Name	Type	Description
`id`	string	Unique identifier of the thread.
`author_id`	number	ID of the user who created the thread.
`document_id`	string	ID of the document the thread belongs to.
`created`	string	Timestamp (RFC 3339) of when the thread was created.
`position`	object	Position on the canvas (see below).
`comments`	array of objects	The comments of this thread (see below).
`team_members`	array of objects	Optional: The document’s team members (used to resolve mentions).

A comment has these fields:

Name	Type	Description
`id`	string	Unique identifier of the comment.
`thread_id`	string	ID of the thread this comment belongs to.
`author_id`	number	ID of the comment’s author.
`author_displayname`	string	Display name of the author.
`author_avatar_url`	string	Avatar URL of the author.
`content`	array	The message content (see below).
`created`	string	Timestamp (RFC 3339) of when the comment was created.
`updated`	string	Optional: Timestamp (RFC 3339) of the last edit, if the comment was edited.

A position is an object with x and y (numbers) giving the canvas coordinates of the thread.

The content of a comment is an array of message parts. Each part is either plain text or a user mention:

A text part: { "type": "text", "text": "Hello " }
A mention: { "type": "user", "id": 123, "name": "Jane Doe", "avatar_url": "…" }

When posting content, a mention part only needs its id (the user ID of a team member); the name and avatar_url are filled in by the server on output. Mentions of users who are not team members are turned into plain text.

Listing all threads of a document

Route

GET /api/v1/users/id/documents/doc/comments

Return value

{
  "threads": [
    {
      "id": "…",
      "author_id": 123,
      "document_id": "…",
      "created": "2026-01-01T12:00:00Z",
      "position": { "x": 100, "y": 200 },
      "comments": [ … ]
    }
  ],
  "team_members": [
    { "id": 123, "name": "Jane Doe", "email": "jane@example.com", "avatar_url": "…" }
  ]
}

Getting a single thread

Route

GET /api/v1/users/id/documents/doc/comments/threadID

Return value

A single comment thread object (including its comments and team_members).

Creating a new thread

Creates a new thread with its first comment at the given canvas position.

Route

POST /api/v1/users/id/documents/doc/comments

Request payload

{
  "position": { "x": 100, "y": 200 },
  "content": [
    { "type": "text", "text": "What about " },
    { "type": "user", "id": 123 },
    { "type": "text", "text": "'s numbers here?" }
  ]
}

Return value

The newly created comment thread object.

Adding a reply to a thread

Route

POST /api/v1/users/id/documents/doc/comments/threadID

Request payload

{
  "content": [{ "type": "text", "text": "Good point, fixed." }]
}

Return value

The newly created comment object.

Moving a thread

Updates the canvas position of a thread.

Route

PUT /api/v1/users/id/documents/doc/comments/threadID

Request payload

{
  "position": { "x": 320, "y": 240 }
}

Return value

The updated comment thread object.

Editing a comment

Updates the content of a single comment.

Route

PUT /api/v1/users/id/documents/doc/comments/threadID/commentID

Request payload

{
  "content": [{ "type": "text", "text": "Edited text." }]
}

Return value

The updated comment object (its updated field is now set).

Deleting a thread

Deletes an entire thread and all its comments. Requires write access to the document, and the document must belong to a team or organization.

Route

DELETE /api/v1/users/id/documents/doc/comments/threadID

Return value

No content (HTTP status code 204) upon success.

Deleting a single comment

Deletes one comment from a thread. Requires write access to the document, the document must belong to a team or organization, and the current user must be the author of the comment.

Route

DELETE /api/v1/users/id/documents/doc/comments/threadID/commentID

Return value

No content (HTTP status code 204) upon success.