Notes: Comments

The Comments API lets you create, edit, delete, resolve, and re-anchor comment threads on document nodes within a notebook. Each comment is anchored to either the entire document, a specific block, or a text range, and tracks its resolution state for collaborative review workflows.

List comment anchors

Returns lightweight thread anchor metadata for comment decorations. Use this endpoint to render comment decorations on the client without fetching full comment bodies.

`GET /api/v1/notes/notebooks/{notebookId}/nodes/{nodeId}/comment-anchors`

Parameters

Name	In	Type	Required	Description
`limit`	query	integer	No	Maximum number of anchors to return. Default: `500`.
`offset`	query	integer	No	Number of anchors to skip. Default: `0`.
`cursor`	query	string	No	Pagination cursor returned by a previous call.
`notebookId`	path	string	Yes	Identifier of the notebook that owns the document node.
`nodeId`	path	string	Yes	Identifier of the document node whose anchors are being listed.

Response

{
  "anchors": [
    {
      "threadId": "cm_7a4f31c2",
      "anchor": {
        "anchorType": "text-range",
        "anchorBlockId": "blk_d3a1f8c2",
        "startBlockId": "blk_d3a1f8c2",
        "startOffset": 124,
        "endBlockId": "blk_d3a1f8c2",
        "endOffset": 168,
        "anchorQuote": "the new pricing model is finalized",
        "anchorContextBefore": "After reviewing the spec,",
        "anchorContextAfter": "and we should ship it next sprint.",
        "anchorStatus": "active",
        "anchorUpdatedAt": "2025-04-12T18:33:07Z"
      },
      "anchorStatus": "active",
      "resolvedAt": null,
      "version": 3
    },
    {
      "threadId": "cm_b92e01d4",
      "anchor": {
        "anchorType": "block",
        "anchorBlockId": "blk_7c2aa1f0",
        "startBlockId": null,
        "startOffset": null,
        "endBlockId": null,
        "endOffset": null,
        "anchorQuote": null,
        "anchorContextBefore": null,
        "anchorContextAfter": null,
        "anchorStatus": "orphaned",
        "anchorUpdatedAt": "2025-04-10T09:14:22Z"
      },
      "anchorStatus": "orphaned",
      "resolvedAt": "2025-04-11T12:01:50Z",
      "version": 5
    }
  ],
  "nextCursor": "eyJ0aWQiOiJjbV9iOTJlMDFkNCJ9",
  "hasMore": false
}

{
  "message": "Invalid query parameter: limit must be a positive integer",
  "code": "INVALID_QUERY_PARAM",
  "details": [
    {
      "path": "limit",
      "message": "Expected a positive integer"
    }
  ]
}

{
  "message": "You do not have access to this notebook",
  "code": "FORBIDDEN_NOTEBOOK_ACCESS",
  "details": []
}

{
  "message": "Document node not found",
  "code": "NODE_NOT_FOUND",
  "details": []
}

{
  "message": "Notebook is in a conflicting state",
  "code": "NOTEBOOK_CONFLICT",
  "details": []
}

SDK

const { anchors, hasMore, nextCursor } = await client.notes.comments.listAnchors(
  "nb_8f3a1c2e",
  "nd_42b1e7",
  { limit: 200 }
);

List comments

Returns all comments for a document node, including the comment body, anchor metadata, author information, and resolution state.

`GET /api/v1/notes/notebooks/{notebookId}/nodes/{nodeId}/comments`

Parameters

Name	In	Type	Required	Description
`limit`	query	integer	No	Maximum number of comments to return. Default: `100`.
`offset`	query	integer	No	Number of comments to skip. Default: `0`.
`cursor`	query	string	No	Pagination cursor returned by a previous call.
`notebookId`	path	string	Yes	Identifier of the notebook that owns the document node.
`nodeId`	path	string	Yes	Identifier of the document node whose comments are being listed.

Response

{
  "comments": [
    {
      "id": "cm_7a4f31c2",
      "documentId": "nd_42b1e7",
      "parentId": null,
      "anchorBlockId": "blk_d3a1f8c2",
      "anchorType": "text-range",
      "startBlockId": "blk_d3a1f8c2",
      "startOffset": 124,
      "endBlockId": "blk_d3a1f8c2",
      "endOffset": 168,
      "anchorQuote": "the new pricing model is finalized",
      "anchorContextBefore": "After reviewing the spec,",
      "anchorContextAfter": "and we should ship it next sprint.",
      "anchorStatus": "active",
      "anchorUpdatedAt": "2025-04-12T18:33:07Z",
      "version": 3,
      "content": "Should this reference the legal team before we ship?",
      "createdAt": "2025-04-12T18:33:07Z",
      "createdBy": "u_a1b2c3d4",
      "createdByName": "Avery Chen",
      "updatedAt": null,
      "resolvedAt": null,
      "resolvedBy": null
    }
  ],
  "nextCursor": null,
  "hasMore": false
}

{
  "message": "Invalid cursor value",
  "code": "INVALID_CURSOR",
  "details": [
    {
      "path": "cursor",
      "message": "Cursor is malformed or expired"
    }
  ]
}

{
  "message": "You do not have access to this notebook",
  "code": "FORBIDDEN_NOTEBOOK_ACCESS",
  "details": []
}

{
  "message": "Document node not found",
  "code": "NODE_NOT_FOUND",
  "details": []
}

{
  "message": "Notebook is in a conflicting state",
  "code": "NOTEBOOK_CONFLICT",
  "details": []
}

SDK

const { comments, hasMore } = await client.notes.comments.list(
  "nb_8f3a1c2e",
  "nd_42b1e7",
  { limit: 50 }
);

Create a comment

Creates a new comment on a document node. Provide an anchor to attach the comment to a specific block or text range; omit it to comment on the entire document.

`POST /api/v1/notes/notebooks/{notebookId}/nodes/{nodeId}/comments`

Parameters

Name	In	Type	Required	Description
`notebookId`	path	string	Yes	Identifier of the notebook that owns the document node.
`nodeId`	path	string	Yes	Identifier of the document node to comment on.

Request Body

Field	Type	Required	Description
`content`	string	Yes	Comment body. Between 1 and 10000 characters.
`parentId`	string	No	Identifier of a parent comment when creating a reply.
`anchorBlockId`	string	No	Block identifier the comment is attached to.
`anchor`	object	No	Anchor descriptor (see variants below).

The anchor field is a discriminated union by type:

Type	Required Fields	Optional Fields
`document`	`type`	—
`block`	`type`, `blockId`	—
`text-range`	`type`, `startBlockId`, `startOffset`, `endBlockId`, `endOffset`	`quote`, `contextBefore`, `contextAfter`

Response

{
  "id": "cm_7a4f31c2",
  "documentId": "nd_42b1e7",
  "parentId": null,
  "anchorBlockId": "blk_d3a1f8c2",
  "anchorType": "text-range",
  "startBlockId": "blk_d3a1f8c2",
  "startOffset": 124,
  "endBlockId": "blk_d3a1f8c2",
  "endOffset": 168,
  "anchorQuote": "the new pricing model is finalized",
  "anchorContextBefore": "After reviewing the spec,",
  "anchorContextAfter": "and we should ship it next sprint.",
  "anchorStatus": "active",
  "anchorUpdatedAt": "2025-04-12T18:33:07Z",
  "version": 1,
  "content": "Should this reference the legal team before we ship?",
  "createdAt": "2025-04-12T18:33:07Z",
  "createdBy": "u_a1b2c3d4",
  "createdByName": "Avery Chen",
  "updatedAt": null,
  "resolvedAt": null,
  "resolvedBy": null
}

{
  "message": "Invalid anchor payload",
  "code": "INVALID_ANCHOR",
  "details": [
    {
      "path": "anchor.startOffset",
      "message": "startOffset must be greater than or equal to endOffset"
    }
  ]
}

{
  "message": "You do not have permission to comment on this document",
  "code": "FORBIDDEN_COMMENT_CREATE",
  "details": []
}

{
  "message": "Document node not found",
  "code": "NODE_NOT_FOUND",
  "details": []
}

{
  "message": "Comment thread is locked",
  "code": "COMMENT_THREAD_LOCKED",
  "details": []
}

{
  "message": "Failed to persist comment",
  "code": "COMMENT_PERSIST_FAILED",
  "details": []
}

SDK

const comment = await client.notes.comments.create("nb_8f3a1c2e", "nd_42b1e7", {
  content: "Should this reference the legal team before we ship?",
  anchor: {
    type: "text-range",
    startBlockId: "blk_d3a1f8c2",
    startOffset: 124,
    endBlockId: "blk_d3a1f8c2",
    endOffset: 168,
    quote: "the new pricing model is finalized",
    contextBefore: "After reviewing the spec,",
    contextAfter: "and we should ship it next sprint.",
  },
});

Edit a comment

Edits the content of an existing comment. Only the comment body can be modified; anchor information is updated through the re-anchor endpoint.

`PATCH /api/v1/notes/notebooks/{notebookId}/nodes/{nodeId}/comments/{commentId}`

Parameters

Name	In	Type	Required	Description
`notebookId`	path	string	Yes	Identifier of the notebook that owns the document node.
`nodeId`	path	string	Yes	Identifier of the document node the comment belongs to.
`commentId`	path	string	Yes	Identifier of the comment to edit.

Request Body

Field	Type	Required	Description
`content`	string	Yes	New comment body. Between 1 and 10000 characters.
`expectedVersion`	integer	No	Version number expected on the server for optimistic concurrency control.

Response

{
  "id": "cm_7a4f31c2",
  "documentId": "nd_42b1e7",
  "parentId": null,
  "anchorBlockId": "blk_d3a1f8c2",
  "anchorType": "text-range",
  "startBlockId": "blk_d3a1f8c2",
  "startOffset": 124,
  "endBlockId": "blk_d3a1f8c2",
  "endOffset": 168,
  "anchorQuote": "the new pricing model is finalized",
  "anchorContextBefore": "After reviewing the spec,",
  "anchorContextAfter": "and we should ship it next sprint.",
  "anchorStatus": "active",
  "anchorUpdatedAt": "2025-04-12T18:33:07Z",
  "version": 4,
  "content": "Should this reference the legal team before we ship next quarter?",
  "createdAt": "2025-04-12T18:33:07Z",
  "createdBy": "u_a1b2c3d4",
  "createdByName": "Avery Chen",
  "updatedAt": "2025-04-13T09:02:11Z",
  "resolvedAt": null,
  "resolvedBy": null
}

{
  "message": "You do not have permission to edit this comment",
  "code": "FORBIDDEN_COMMENT_EDIT",
  "details": []
}

{
  "message": "Comment not found",
  "code": "COMMENT_NOT_FOUND",
  "details": []
}

{
  "message": "Comment version does not match expectedVersion",
  "code": "COMMENT_VERSION_MISMATCH",
  "details": []
}

SDK

const updated = await client.notes.comments.edit(
  "nb_8f3a1c2e",
  "nd_42b1e7",
  "cm_7a4f31c2",
  {
    content: "Should this reference the legal team before we ship next quarter?",
    expectedVersion: 3,
  }
);

Re-anchor a comment thread

Updates the root comment anchor for a comment thread. Use this when the original anchor becomes orphaned (for example, the referenced block was deleted) and you want to reattach the thread to a new location.

`POST /api/v1/notes/notebooks/{notebookId}/nodes/{nodeId}/comments/{commentId}/reanchor`

Parameters

Name	In	Type	Required	Description
`notebookId`	path	string	Yes	Identifier of the notebook that owns the document node.
`nodeId`	path	string	Yes	Identifier of the document node the comment belongs to.
`commentId`	path	string	Yes	Identifier of the comment thread to re-anchor.

Request Body

Field	Type	Required	Description
`anchor`	object	Yes	New anchor descriptor (see variants below).
`expectedVersion`	integer	No	Version number expected on the server for optimistic concurrency control.

The anchor field is a discriminated union by type:

Type	Required Fields	Optional Fields
`document`	`type`	—
`block`	`type`, `blockId`	—
`text-range`	`type`, `startBlockId`, `startOffset`, `endBlockId`, `endOffset`	`quote`, `contextBefore`, `contextAfter`

Response

{
  "id": "cm_7a4f31c2",
  "documentId": "nd_42b1e7",
  "parentId": null,
  "anchorBlockId": "blk_e91a8b40",
  "anchorType": "block",
  "startBlockId": null,
  "startOffset": null,
  "endBlockId": null,
  "endOffset": null,
  "anchorQuote": null,
  "anchorContextBefore": null,
  "anchorContextAfter": null,
  "anchorStatus": "active",
  "anchorUpdatedAt": "2025-04-13T11:48:55Z",
  "version": 5,
  "content": "Should this reference the legal team before we ship next quarter?",
  "createdAt": "2025-04-12T18:33:07Z",
  "createdBy": "u_a1b2c3d4",
  "createdByName": "Avery Chen",
  "updatedAt": "2025-04-13T11:48:55Z",
  "resolvedAt": null,
  "resolvedBy": null
}

{
  "message": "Invalid anchor payload",
  "code": "INVALID_ANCHOR",
  "details": [
    {
      "path": "anchor.blockId",
      "message": "blockId does not exist in this document"
    }
  ]
}

{
  "message": "You do not have permission to re-anchor this comment",
  "code": "FORBIDDEN_COMMENT_REANCHOR",
  "details": []
}

{
  "message": "Comment not found",
  "code": "COMMENT_NOT_FOUND",
  "details": []
}

{
  "message": "Comment version does not match expectedVersion",
  "code": "COMMENT_VERSION_MISMATCH",
  "details": []
}

SDK

const reanchored = await client.notes.comments.reanchor(
  "nb_8f3a1c2e",
  "nd_42b1e7",
  "cm_7a4f31c2",
  {
    anchor: { type: "block", blockId: "blk_e91a8b40" },
    expectedVersion: 4,
  }
);

Resolve a comment

Marks a comment as resolved. The resolvedAt and resolvedBy fields are populated on the returned comment.

`POST /api/v1/notes/notebooks/{notebookId}/nodes/{nodeId}/comments/{commentId}/resolve`

Parameters

Name	In	Type	Required	Description
`notebookId`	path	string	Yes	Identifier of the notebook that owns the document node.
`nodeId`	path	string	Yes	Identifier of the document node the comment belongs to.
`commentId`	path	string	Yes	Identifier of the comment to resolve.

Request Body

Field	Type	Required	Description
`expectedVersion`	integer	No	Version number expected on the server for optimistic concurrency control.

Response

{
  "id": "cm_7a4f31c2",
  "documentId": "nd_42b1e7",
  "parentId": null,
  "anchorBlockId": "blk_d3a1f8c2",
  "anchorType": "text-range",
  "startBlockId": "blk_d3a1f8c2",
  "startOffset": 124,
  "endBlockId": "blk_d3a1f8c2",
  "endOffset": 168,
  "anchorQuote": "the new pricing model is finalized",
  "anchorContextBefore": "After reviewing the spec,",
  "anchorContextAfter": "and we should ship it next sprint.",
  "anchorStatus": "active",
  "anchorUpdatedAt": "2025-04-12T18:33:07Z",
  "version": 5,
  "content": "Should this reference the legal team before we ship next quarter?",
  "createdAt": "2025-04-12T18:33:07Z",
  "createdBy": "u_a1b2c3d4",
  "createdByName": "Avery Chen",
  "updatedAt": "2025-04-14T08:21:44Z",
  "resolvedAt": "2025-04-14T08:21:44Z",
  "resolvedBy": "u_f7e8d9c0"
}

{
  "message": "You do not have permission to resolve this comment",
  "code": "FORBIDDEN_COMMENT_RESOLVE",
  "details": []
}

{
  "message": "Comment not found",
  "code": "COMMENT_NOT_FOUND",
  "details": []
}

{
  "message": "Comment version does not match expectedVersion",
  "code": "COMMENT_VERSION_MISMATCH",
  "details": []
}

SDK

const resolved = await client.notes.comments.resolve(
  "nb_8f3a1c2e",
  "nd_42b1e7",
  "cm_7a4f31c2",
  { expectedVersion: 4 }
);

Delete a comment

Deletes a comment and its replies. This operation is irreversible.

`DELETE /api/v1/notes/notebooks/{notebookId}/nodes/{nodeId}/comments/{commentId}`

Parameters

Name	In	Type	Required	Description
`expectedVersion`	query	integer	No	Version number expected on the server for optimistic concurrency control.
`notebookId`	path	string	Yes	Identifier of the notebook that owns the document node.
`nodeId`	path	string	Yes	Identifier of the document node the comment belongs to.
`commentId`	path	string	Yes	Identifier of the comment to delete.

Response

{
  "success": true
}

{
  "message": "You do not have permission to delete this comment",
  "code": "FORBIDDEN_COMMENT_DELETE",
  "details": []
}

{
  "message": "Comment not found",
  "code": "COMMENT_NOT_FOUND",
  "details": []
}

{
  "message": "Comment version does not match expectedVersion",
  "code": "COMMENT_VERSION_MISMATCH",
  "details": []
}

SDK

const result = await client.notes.comments.delete(
  "nb_8f3a1c2e",
  "nd_42b1e7",
  "cm_7a4f31c2",
  { expectedVersion: 5 }
);