Skip to main content
POST
/
v2
/
commentannotations
/
get
Get Comment Annotations
curl --request POST \
  --url https://api.velt.dev/v2/commentannotations/get \
  --header 'Content-Type: application/json' \
  --header 'x-velt-api-key: <x-velt-api-key>' \
  --header 'x-velt-auth-token: <x-velt-auth-token>' \
  --data '
{
  "data": {
    "organizationId": "<string>",
    "documentId": "<string>",
    "documentIds": [
      "<string>"
    ],
    "groupByDocumentId": true,
    "locationIds": [
      "<string>"
    ],
    "folderId": "<string>",
    "annotationIds": [
      "<string>"
    ],
    "userIds": [
      "<string>"
    ],
    "mentionedUserIds": [
      "<string>"
    ],
    "resolvedBy": "<string>",
    "agentId": "<string>",
    "executionId": "<string>",
    "agentType": "<string>",
    "agentSource": "<string>",
    "agentSuggestions": true,
    "agentComments": true,
    "order": "<string>",
    "statusIds": [
      "<string>"
    ],
    "updatedAfter": 123,
    "updatedBefore": 123,
    "createdAfter": 123,
    "createdBefore": 123,
    "pageSize": 123,
    "pageToken": "<string>"
  }
}
'
{
  "result": {
    "status": "success",
    "message": "Annotation(s) fetched successfully.",
    "data": [
      {
        "annotationId": "yourAnnotationId",
        "annotationNumber": 2,
        "annotationIndex": 1,
        "type": "comment",
        "createdAt": 1777973713421,
        "lastUpdated": 1777978714209,
        "hasDraftComments": false,
        "locationId": 5509827173770816,
        "location": {
          "version": {
            "id": "v1",
            "name": "Version 1"
          }
        },
        "context": {
          "access": {
            "default": "velt"
          },
          "accessFields": [
            "default:velt"
          ]
        },
        "visibilityConfig": {
          "type": "public"
        },
        "metadata": {
          "apiKey": "yourApiKey",
          "organizationId": "yourOrganizationId",
          "documentId": "yourDocumentId",
          "sdkVersion": "5.0.2-beta.45"
        },
        "pageInfo": {
          "deviceInfo": {
            "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/147.0.0.0 Safari/537.36",
            "browserName": "Chrome",
            "browserVersion": "147",
            "deviceType": "Tablet",
            "orientation": "landscape",
            "osName": "Macintosh",
            "osVersion": "10.15.7",
            "screenWidth": 1512,
            "screenHeight": 982
          },
          "url": "https://example.com/document?id=yourDocumentId&version=v1",
          "path": "/document",
          "queryParams": "?id=yourDocumentId&version=v1",
          "baseUrl": "https://example.com",
          "title": "Document Title",
          "screenWidth": 1131,
          "commentUrl": "https://example.com/document?id=yourDocumentId&version=v1&scommentId=yourAnnotationId"
        },
        "from": {
          "userId": "user123",
          "organizationId": "d448b95936703db7d0923122172fb13c",
          "userSnippylyId": "1174701858709696",
          "photoUrl": "",
          "initial": "J",
          "clientUserName": "John Doe",
          "name": "John Doe",
          "name_lowercase": "johndoe",
          "clientOrganizationId": "yourOrganizationId",
          "clientGroupId": "yourClientGroupId",
          "groupId": "yourGroupId",
          "type": "signedIn",
          "contacts": [],
          "email": "john.doe@example.com",
          "email_lowercase": "john.doe@example.com",
          "color": "#a259fe",
          "textColor": "#FFFFFF",
          "isAdmin": false
        },
        "subscribedUsers": {
          "061a01a98f80f415b1431236b62bb10b": {
            "user": {
              "userId": "user123"
            },
            "type": "auto"
          }
        },
        "unsubscribedUsers": {},
        "subscribedGroups": {},
        "customList": [],
        "comments": [
          {
            "commentId": 123456,
            "type": "text",
            "status": "updated",
            "isDraft": false,
            "isCommentTextAvailable": true,
            "commentText": "This is a sample comment text.",
            "commentHtml": "<p>This is a sample comment text.</p>",
            "createdAt": 1777973714914,
            "lastUpdated": "2026-05-05T09:35:15.048Z",
            "to": [],
            "toOrganizationUserGroup": [],
            "taggedUserContacts": [],
            "attachments": [],
            "recorders": [],
            "customList": [],
            "reactionAnnotationIds": [
              "reactionAnnotationId1",
              "reactionAnnotationId2"
            ],
            "reactionAnnotations": [
              {
                "annotationId": "reactionAnnotationId1",
                "type": "reaction",
                "icon": "RAISED_HANDS",
                "commentAnnotationId": "yourAnnotationId",
                "locationId": 5509827173770816,
                "location": {
                  "version": {
                    "id": "v1",
                    "name": "Version 1"
                  }
                },
                "context": {
                  "access": {
                    "default": "velt"
                  },
                  "accessFields": [
                    "default:velt"
                  ]
                },
                "lastUpdated": 1777978712656,
                "fromUsers": [
                  {
                    "lastUpdated": 1777978709472,
                    "from": {
                      "userId": "user123",
                      "organizationId": "d448b95936703db7d0923122172fb13c",
                      "userSnippylyId": "1174701858709696",
                      "photoUrl": "",
                      "initial": "J",
                      "clientUserName": "John Doe",
                      "name": "John Doe",
                      "name_lowercase": "johndoe",
                      "clientOrganizationId": "yourOrganizationId",
                      "clientGroupId": "yourClientGroupId",
                      "groupId": "yourGroupId",
                      "type": "signedIn",
                      "contacts": [],
                      "email": "john.doe@example.com",
                      "email_lowercase": "john.doe@example.com",
                      "color": "#a259fe",
                      "textColor": "#FFFFFF",
                      "isAdmin": false
                    }
                  },
                  {
                    "lastUpdated": 1777978712656,
                    "from": {
                      "userId": "guestUser456",
                      "organizationId": "d448b95936703db7d0923122172fb13c",
                      "userSnippylyId": "8810801459478142",
                      "isGuest": true,
                      "initial": "P",
                      "clientUserName": "Powerful Panda",
                      "name": "Powerful Panda",
                      "name_lowercase": "powerfulpanda",
                      "clientOrganizationId": "yourOrganizationId",
                      "type": "signedIn",
                      "contacts": [],
                      "email": "guest@example.com",
                      "email_lowercase": "guest@example.com",
                      "photoUrl": "https://example.com/avatars/powerful_panda.svg",
                      "color": "#67DBF4",
                      "textColor": "#FFFFFF",
                      "isAdmin": false
                    }
                  }
                ]
              },
              {
                "annotationId": "reactionAnnotationId2",
                "type": "reaction",
                "icon": "HEART_FACE",
                "commentAnnotationId": "yourAnnotationId",
                "locationId": 5509827173770816,
                "location": {
                  "version": {
                    "id": "v1",
                    "name": "Version 1"
                  }
                },
                "context": {
                  "access": {
                    "default": "velt"
                  },
                  "accessFields": [
                    "default:velt"
                  ]
                },
                "lastUpdated": 1777978714205,
                "fromUsers": [
                  {
                    "lastUpdated": 1777978714205,
                    "from": {
                      "userId": "guestUser456",
                      "organizationId": "d448b95936703db7d0923122172fb13c",
                      "userSnippylyId": "8810801459478142",
                      "isGuest": true,
                      "initial": "P",
                      "clientUserName": "Powerful Panda",
                      "name": "Powerful Panda",
                      "name_lowercase": "powerfulpanda",
                      "clientOrganizationId": "yourOrganizationId",
                      "type": "signedIn",
                      "contacts": [],
                      "email": "guest@example.com",
                      "email_lowercase": "guest@example.com",
                      "photoUrl": "https://example.com/avatars/powerful_panda.svg",
                      "color": "#67DBF4",
                      "textColor": "#FFFFFF",
                      "isAdmin": false
                    }
                  }
                ]
              }
            ],
            "from": {
              "userId": "user123",
              "organizationId": "d448b95936703db7d0923122172fb13c",
              "userSnippylyId": "1174701858709696",
              "photoUrl": "",
              "initial": "J",
              "clientUserName": "John Doe",
              "name": "John Doe",
              "name_lowercase": "johndoe",
              "clientOrganizationId": "yourOrganizationId",
              "clientGroupId": "yourClientGroupId",
              "groupId": "yourGroupId",
              "type": "signedIn",
              "contacts": [],
              "email": "john.doe@example.com",
              "email_lowercase": "john.doe@example.com",
              "color": "#a259fe",
              "textColor": "#FFFFFF",
              "isAdmin": false
            }
          }
        ],
        "status": {
          "id": "OPEN",
          "name": "Open",
          "color": "var(--velt-accent, #625DF5)",
          "lightColor": "var(--velt-accent-light, #E7E8FA)",
          "type": "default",
          "svg": "\n      <svg\n        width=\"16\"\n        height=\"16\"\n        viewBox=\"0 0 16 16\"\n        fill=\"none\"\n        xmlns=\"http://www.w3.org/2000/svg\"\n      >\n        <path\n          fill-rule=\"evenodd\"\n          clip-rule=\"evenodd\"\n          d=\"M8.00016 13.3333C10.9457 13.3333 13.3335 10.9455 13.3335 8.00001C13.3335 5.05449 10.9457 2.66668 8.00016 2.66668C5.05464 2.66668 2.66683 5.05449 2.66683 8.00001C2.66683 10.9455 5.05464 13.3333 8.00016 13.3333ZM8.00016 14.6667C11.6821 14.6667 14.6668 11.6819 14.6668 8.00001C14.6668 4.31811 11.6821 1.33334 8.00016 1.33334C4.31826 1.33334 1.3335 4.31811 1.3335 8.00001C1.3335 11.6819 4.31826 14.6667 8.00016 14.6667Z\"\n          fill=\"currentColor\"\n        />\n      </svg>\n      "
        }
      },
      null // null is returned only if you provided an annotationId that doesn't exist
    ],
    "nextPageToken": "pageToken"
  }
}
Use this API to retrieve comment annotations from a document within an organization. Additional filters can be applied using location IDs, annotation IDs, or user IDs.
Prior to using this API, you must:
  • Enable advanced queries option in the console
  • Deploy v4 series of the Velt SDK.

​
Endpoint

POST https://api.velt.dev/v2/commentannotations/get

​
Headers

​
x-velt-api-key
string
required
Your API key.
​
x-velt-auth-token
string
required
Your Auth Token.

​
Body

​
Params

​
data
object
required

​
Example Requests

​
1. Get annotations by organizationId and documentId

{
  "data": {
    "organizationId": "yourOrganizationId",
    "documentId": "yourDocumentId",
    "pageSize": 10,
    "pageToken": "1720441573192",
    "statusId": "OPEN"
  }
}

​
2. Get annotations by organizationId and documentIds grouped by documentId

{
  "data": {
    "organizationId": "yourOrganizationId",
    "documentIds": ["yourDocumentId1", "yourDocumentId2"],
    "groupByDocumentId": true
  }
}

​
3. Get annotations by organizationId, documentId, and locationIds

{
  "data": {
    "organizationId": "yourOrganizationId",
    "documentId": "yourDocumentId",
    "locationIds": [
      "locationx"
    ],
    "pageSize": 10,
    "pageToken": "1720441573192",
    "statusId": "OPEN"
  }
}

​
4. Get annotations by organizationId, documentId, locationIds, and userIds

{
  "data": {
    "organizationId": "yourOrganizationId",
    "documentId": "yourDocumentId",
    "locationIds": [
      "locationx"
    ],
    "userIds": [
      "yourUserId"
    ],
    "pageSize": 10,
    "pageToken": "1720441573192",
    "statusId": "OPEN"
  }
}

​
5. Get annotations by organizationId, documentId, and userIds

{
  "data": {
    "organizationId": "yourOrganizationId",
    "documentId": "yourDocumentId",
    "userIds": [
      "yourUserId"
    ],
    "pageSize": 10,
    "pageToken": "1720441573192",
    "statusId": "OPEN"
  }
}

​
6. Get annotations by organizationId, documentId, and annotationIds

{
  "data": {
    "organizationId": "yourOrganizationId",
    "documentId": "yourDocumentId",
    "annotationIds": [
      "yourAnnotationId1",
      "yourAnnotationId2"
    ],
    "pageSize": 10,
    "pageToken": "1720441573192",
    "statusId": "OPEN"
  }
}

​
7. Get annotations by organizationId, documentId, locationIds, and annotationIds

{
  "data": {
    "organizationId": "yourOrganizationId",
    "documentId": "yourDocumentId",
    "locationIds": [
      "locationx"
    ],
    "annotationIds": [
      "yourAnnotationId1",
      "yourAnnotationId2"
    ],
    "pageSize": 10,
    "pageToken": "1720441573192",
    "statusId": "OPEN"
  }
}

​
8. Get annotations by organizationId, statusIds, updatedAfter, and updatedBefore

{
   "data": {
       "organizationId": "myorg1",
       "statusIds": ["OPEN"],
       "updatedAfter": 1720441573192,
       "updatedBefore": 1720441573192,
   }
}

​
9. Get annotations by organizationId, folderId

{
   "data": {
       "organizationId": "myorg1",
       "folderId": "folderId1"
   }
}

​
10. Get agent annotations by organizationId, documentId, and agentId

{
  "data": {
    "organizationId": "yourOrganizationId",
    "documentId": "yourDocumentId",
    "agentId": "spell-check"
  }
}
Agent annotations in the response carry type: "suggestion" and sourceType: "agent" at the annotation root, the annotation-root agent block, and the agent block on the agent-authored comment (comments[].agent). Both agent blocks are returned lean — only the internal agentFields filter tokens are omitted (see Response Field Notes below).

​
Response

Response Field Notes:
  • reactionAnnotationIds: Array of reaction annotation IDs (strings) attached to a comment.
  • reactionAnnotations: Array of full reaction annotation objects attached to a comment. Each reaction includes the icon, fromUsers (the users who reacted), location, locationId, commentAnnotationId, context, type, annotationId, and lastUpdated.
  • viewedBy: This field is not currently returned by this endpoint.
  • createdAt and lastUpdated: Timestamps are returned in milliseconds since epoch for annotations and reactions, and in ISO 8601 format for comments.
  • type: Annotation kind, either comment (a regular collaboration comment) or suggestion (an agent-produced finding).
  • sourceType: How the annotation/comment was created. rest-api for annotations created via this REST API, or agent for agent-authored annotations and comments.
  • agent: Returned at the annotation root (for agent-authored annotations) and on each agent-authored comment (comments[].agent). Contains agentId, agentType (built-in / custom / external), agentSource (velt / external), executionId, agentName, url, and the reason finding object (title, description, severity, findingType, etc.). The internal agentFields filter tokens are not returned on either block.
  • suggestion: Lifecycle object present only when type is suggestion, e.g. { "status": "pending" }. status is one of pending, accepted, or rejected.
  • visibilityConfig: Visibility of the annotation, e.g. { "type": "public" }. type is one of public, organizationPrivate, or restricted.
  • context.access / context.accessFields: Access control metadata for the annotation (e.g. { "default": "velt" }). When visibility is set on creation, the resolved access tokens appear in context.accessFields.
  • hasDraftComments: Boolean indicating whether the annotation has any draft comments.

​
Success Response with single documentId

{
  "result": {
    "status": "success",
    "message": "Annotation(s) fetched successfully.",
    "data": [
      {
        "annotationId": "yourAnnotationId",
        "annotationNumber": 2,
        "annotationIndex": 1,
        "type": "comment",
        "createdAt": 1777973713421,
        "lastUpdated": 1777978714209,
        "hasDraftComments": false,
        "locationId": 5509827173770816,
        "location": {
          "version": {
            "id": "v1",
            "name": "Version 1"
          }
        },
        "context": {
          "access": {
            "default": "velt"
          },
          "accessFields": [
            "default:velt"
          ]
        },
        "visibilityConfig": {
          "type": "public"
        },
        "metadata": {
          "apiKey": "yourApiKey",
          "organizationId": "yourOrganizationId",
          "documentId": "yourDocumentId",
          "sdkVersion": "5.0.2-beta.45"
        },
        "pageInfo": {
          "deviceInfo": {
            "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/147.0.0.0 Safari/537.36",
            "browserName": "Chrome",
            "browserVersion": "147",
            "deviceType": "Tablet",
            "orientation": "landscape",
            "osName": "Macintosh",
            "osVersion": "10.15.7",
            "screenWidth": 1512,
            "screenHeight": 982
          },
          "url": "https://example.com/document?id=yourDocumentId&version=v1",
          "path": "/document",
          "queryParams": "?id=yourDocumentId&version=v1",
          "baseUrl": "https://example.com",
          "title": "Document Title",
          "screenWidth": 1131,
          "commentUrl": "https://example.com/document?id=yourDocumentId&version=v1&scommentId=yourAnnotationId"
        },
        "from": {
          "userId": "user123",
          "organizationId": "d448b95936703db7d0923122172fb13c",
          "userSnippylyId": "1174701858709696",
          "photoUrl": "",
          "initial": "J",
          "clientUserName": "John Doe",
          "name": "John Doe",
          "name_lowercase": "johndoe",
          "clientOrganizationId": "yourOrganizationId",
          "clientGroupId": "yourClientGroupId",
          "groupId": "yourGroupId",
          "type": "signedIn",
          "contacts": [],
          "email": "john.doe@example.com",
          "email_lowercase": "john.doe@example.com",
          "color": "#a259fe",
          "textColor": "#FFFFFF",
          "isAdmin": false
        },
        "subscribedUsers": {
          "061a01a98f80f415b1431236b62bb10b": {
            "user": {
              "userId": "user123"
            },
            "type": "auto"
          }
        },
        "unsubscribedUsers": {},
        "subscribedGroups": {},
        "customList": [],
        "comments": [
          {
            "commentId": 123456,
            "type": "text",
            "status": "updated",
            "isDraft": false,
            "isCommentTextAvailable": true,
            "commentText": "This is a sample comment text.",
            "commentHtml": "<p>This is a sample comment text.</p>",
            "createdAt": 1777973714914,
            "lastUpdated": "2026-05-05T09:35:15.048Z",
            "to": [],
            "toOrganizationUserGroup": [],
            "taggedUserContacts": [],
            "attachments": [],
            "recorders": [],
            "customList": [],
            "reactionAnnotationIds": [
              "reactionAnnotationId1",
              "reactionAnnotationId2"
            ],
            "reactionAnnotations": [
              {
                "annotationId": "reactionAnnotationId1",
                "type": "reaction",
                "icon": "RAISED_HANDS",
                "commentAnnotationId": "yourAnnotationId",
                "locationId": 5509827173770816,
                "location": {
                  "version": {
                    "id": "v1",
                    "name": "Version 1"
                  }
                },
                "context": {
                  "access": {
                    "default": "velt"
                  },
                  "accessFields": [
                    "default:velt"
                  ]
                },
                "lastUpdated": 1777978712656,
                "fromUsers": [
                  {
                    "lastUpdated": 1777978709472,
                    "from": {
                      "userId": "user123",
                      "organizationId": "d448b95936703db7d0923122172fb13c",
                      "userSnippylyId": "1174701858709696",
                      "photoUrl": "",
                      "initial": "J",
                      "clientUserName": "John Doe",
                      "name": "John Doe",
                      "name_lowercase": "johndoe",
                      "clientOrganizationId": "yourOrganizationId",
                      "clientGroupId": "yourClientGroupId",
                      "groupId": "yourGroupId",
                      "type": "signedIn",
                      "contacts": [],
                      "email": "john.doe@example.com",
                      "email_lowercase": "john.doe@example.com",
                      "color": "#a259fe",
                      "textColor": "#FFFFFF",
                      "isAdmin": false
                    }
                  },
                  {
                    "lastUpdated": 1777978712656,
                    "from": {
                      "userId": "guestUser456",
                      "organizationId": "d448b95936703db7d0923122172fb13c",
                      "userSnippylyId": "8810801459478142",
                      "isGuest": true,
                      "initial": "P",
                      "clientUserName": "Powerful Panda",
                      "name": "Powerful Panda",
                      "name_lowercase": "powerfulpanda",
                      "clientOrganizationId": "yourOrganizationId",
                      "type": "signedIn",
                      "contacts": [],
                      "email": "guest@example.com",
                      "email_lowercase": "guest@example.com",
                      "photoUrl": "https://example.com/avatars/powerful_panda.svg",
                      "color": "#67DBF4",
                      "textColor": "#FFFFFF",
                      "isAdmin": false
                    }
                  }
                ]
              },
              {
                "annotationId": "reactionAnnotationId2",
                "type": "reaction",
                "icon": "HEART_FACE",
                "commentAnnotationId": "yourAnnotationId",
                "locationId": 5509827173770816,
                "location": {
                  "version": {
                    "id": "v1",
                    "name": "Version 1"
                  }
                },
                "context": {
                  "access": {
                    "default": "velt"
                  },
                  "accessFields": [
                    "default:velt"
                  ]
                },
                "lastUpdated": 1777978714205,
                "fromUsers": [
                  {
                    "lastUpdated": 1777978714205,
                    "from": {
                      "userId": "guestUser456",
                      "organizationId": "d448b95936703db7d0923122172fb13c",
                      "userSnippylyId": "8810801459478142",
                      "isGuest": true,
                      "initial": "P",
                      "clientUserName": "Powerful Panda",
                      "name": "Powerful Panda",
                      "name_lowercase": "powerfulpanda",
                      "clientOrganizationId": "yourOrganizationId",
                      "type": "signedIn",
                      "contacts": [],
                      "email": "guest@example.com",
                      "email_lowercase": "guest@example.com",
                      "photoUrl": "https://example.com/avatars/powerful_panda.svg",
                      "color": "#67DBF4",
                      "textColor": "#FFFFFF",
                      "isAdmin": false
                    }
                  }
                ]
              }
            ],
            "from": {
              "userId": "user123",
              "organizationId": "d448b95936703db7d0923122172fb13c",
              "userSnippylyId": "1174701858709696",
              "photoUrl": "",
              "initial": "J",
              "clientUserName": "John Doe",
              "name": "John Doe",
              "name_lowercase": "johndoe",
              "clientOrganizationId": "yourOrganizationId",
              "clientGroupId": "yourClientGroupId",
              "groupId": "yourGroupId",
              "type": "signedIn",
              "contacts": [],
              "email": "john.doe@example.com",
              "email_lowercase": "john.doe@example.com",
              "color": "#a259fe",
              "textColor": "#FFFFFF",
              "isAdmin": false
            }
          }
        ],
        "status": {
          "id": "OPEN",
          "name": "Open",
          "color": "var(--velt-accent, #625DF5)",
          "lightColor": "var(--velt-accent-light, #E7E8FA)",
          "type": "default",
          "svg": "\n      <svg\n        width=\"16\"\n        height=\"16\"\n        viewBox=\"0 0 16 16\"\n        fill=\"none\"\n        xmlns=\"http://www.w3.org/2000/svg\"\n      >\n        <path\n          fill-rule=\"evenodd\"\n          clip-rule=\"evenodd\"\n          d=\"M8.00016 13.3333C10.9457 13.3333 13.3335 10.9455 13.3335 8.00001C13.3335 5.05449 10.9457 2.66668 8.00016 2.66668C5.05464 2.66668 2.66683 5.05449 2.66683 8.00001C2.66683 10.9455 5.05464 13.3333 8.00016 13.3333ZM8.00016 14.6667C11.6821 14.6667 14.6668 11.6819 14.6668 8.00001C14.6668 4.31811 11.6821 1.33334 8.00016 1.33334C4.31826 1.33334 1.3335 4.31811 1.3335 8.00001C1.3335 11.6819 4.31826 14.6667 8.00016 14.6667Z\"\n          fill=\"currentColor\"\n        />\n      </svg>\n      "
        }
      },
      null // null is returned only if you provided an annotationId that doesn't exist
    ],
    "nextPageToken": "pageToken"
  }
}

​
Success Response with multiple documentIds with groupByDocumentId

{
    "result": {
        "status": "success",
        "message": "Annotations fetched successfully.",
        "data": {
            "documentId1": [
                {
                    "annotationId": "annotationId1",
                    "comments": [
                      //comment objects
                    ],
                    "from": {
                      //from user object
                    },
                    "status": {
                        "color": "#625DF5",
                        "id": "OPEN",
                        "lightColor": "#E7E8FA",
                        "name": "Open",
                        "type": "default"
                    },
                    //other fields
                },
                {
                    "annotationId": "annotationId2",
                    "comments": [
                      //comment objects
                    ],
                    "from": {
                      //from user object
                    },
                    "status": {
                        "color": "#625DF5",
                        "id": "OPEN",
                        "lightColor": "#E7E8FA",
                        "name": "Open",
                        "type": "default"
                    },
                    //other fields
                },
            ],
            "documentId1": [
                {
                    "annotationId": "annotationId1",
                    "comments": [
                      //comment objects
                    ],
                    "from": {
                      //from user object
                    },
                    "status": {
                        "color": "#625DF5",
                        "id": "OPEN",
                        "lightColor": "#E7E8FA",
                        "name": "Open",
                        "type": "default"
                    },
                    //other fields
                },
                {
                    "annotationId": "annotationId2",
                    "comments": [
                      //comment objects
                    ],
                    "from": {
                      //from user object
                    },
                    "status": {
                        "color": "#625DF5",
                        "id": "OPEN",
                        "lightColor": "#E7E8FA",
                        "name": "Open",
                        "type": "default"
                    },
                    //other fields
                },
            ]
        },
        "nextPageToken": "Ds7NMZw0wWSdmfJFLNioTw=="
    }
}

​
Failure Response

{
  "error": {
    "message": "ERROR_MESSAGE",
    "status": "INVALID_ARGUMENT"
  }
}

{
  "result": {
    "status": "success",
    "message": "Annotation(s) fetched successfully.",
    "data": [
      {
        "annotationId": "yourAnnotationId",
        "annotationNumber": 2,
        "annotationIndex": 1,
        "type": "comment",
        "createdAt": 1777973713421,
        "lastUpdated": 1777978714209,
        "hasDraftComments": false,
        "locationId": 5509827173770816,
        "location": {
          "version": {
            "id": "v1",
            "name": "Version 1"
          }
        },
        "context": {
          "access": {
            "default": "velt"
          },
          "accessFields": [
            "default:velt"
          ]
        },
        "visibilityConfig": {
          "type": "public"
        },
        "metadata": {
          "apiKey": "yourApiKey",
          "organizationId": "yourOrganizationId",
          "documentId": "yourDocumentId",
          "sdkVersion": "5.0.2-beta.45"
        },
        "pageInfo": {
          "deviceInfo": {
            "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/147.0.0.0 Safari/537.36",
            "browserName": "Chrome",
            "browserVersion": "147",
            "deviceType": "Tablet",
            "orientation": "landscape",
            "osName": "Macintosh",
            "osVersion": "10.15.7",
            "screenWidth": 1512,
            "screenHeight": 982
          },
          "url": "https://example.com/document?id=yourDocumentId&version=v1",
          "path": "/document",
          "queryParams": "?id=yourDocumentId&version=v1",
          "baseUrl": "https://example.com",
          "title": "Document Title",
          "screenWidth": 1131,
          "commentUrl": "https://example.com/document?id=yourDocumentId&version=v1&scommentId=yourAnnotationId"
        },
        "from": {
          "userId": "user123",
          "organizationId": "d448b95936703db7d0923122172fb13c",
          "userSnippylyId": "1174701858709696",
          "photoUrl": "",
          "initial": "J",
          "clientUserName": "John Doe",
          "name": "John Doe",
          "name_lowercase": "johndoe",
          "clientOrganizationId": "yourOrganizationId",
          "clientGroupId": "yourClientGroupId",
          "groupId": "yourGroupId",
          "type": "signedIn",
          "contacts": [],
          "email": "john.doe@example.com",
          "email_lowercase": "john.doe@example.com",
          "color": "#a259fe",
          "textColor": "#FFFFFF",
          "isAdmin": false
        },
        "subscribedUsers": {
          "061a01a98f80f415b1431236b62bb10b": {
            "user": {
              "userId": "user123"
            },
            "type": "auto"
          }
        },
        "unsubscribedUsers": {},
        "subscribedGroups": {},
        "customList": [],
        "comments": [
          {
            "commentId": 123456,
            "type": "text",
            "status": "updated",
            "isDraft": false,
            "isCommentTextAvailable": true,
            "commentText": "This is a sample comment text.",
            "commentHtml": "<p>This is a sample comment text.</p>",
            "createdAt": 1777973714914,
            "lastUpdated": "2026-05-05T09:35:15.048Z",
            "to": [],
            "toOrganizationUserGroup": [],
            "taggedUserContacts": [],
            "attachments": [],
            "recorders": [],
            "customList": [],
            "reactionAnnotationIds": [
              "reactionAnnotationId1",
              "reactionAnnotationId2"
            ],
            "reactionAnnotations": [
              {
                "annotationId": "reactionAnnotationId1",
                "type": "reaction",
                "icon": "RAISED_HANDS",
                "commentAnnotationId": "yourAnnotationId",
                "locationId": 5509827173770816,
                "location": {
                  "version": {
                    "id": "v1",
                    "name": "Version 1"
                  }
                },
                "context": {
                  "access": {
                    "default": "velt"
                  },
                  "accessFields": [
                    "default:velt"
                  ]
                },
                "lastUpdated": 1777978712656,
                "fromUsers": [
                  {
                    "lastUpdated": 1777978709472,
                    "from": {
                      "userId": "user123",
                      "organizationId": "d448b95936703db7d0923122172fb13c",
                      "userSnippylyId": "1174701858709696",
                      "photoUrl": "",
                      "initial": "J",
                      "clientUserName": "John Doe",
                      "name": "John Doe",
                      "name_lowercase": "johndoe",
                      "clientOrganizationId": "yourOrganizationId",
                      "clientGroupId": "yourClientGroupId",
                      "groupId": "yourGroupId",
                      "type": "signedIn",
                      "contacts": [],
                      "email": "john.doe@example.com",
                      "email_lowercase": "john.doe@example.com",
                      "color": "#a259fe",
                      "textColor": "#FFFFFF",
                      "isAdmin": false
                    }
                  },
                  {
                    "lastUpdated": 1777978712656,
                    "from": {
                      "userId": "guestUser456",
                      "organizationId": "d448b95936703db7d0923122172fb13c",
                      "userSnippylyId": "8810801459478142",
                      "isGuest": true,
                      "initial": "P",
                      "clientUserName": "Powerful Panda",
                      "name": "Powerful Panda",
                      "name_lowercase": "powerfulpanda",
                      "clientOrganizationId": "yourOrganizationId",
                      "type": "signedIn",
                      "contacts": [],
                      "email": "guest@example.com",
                      "email_lowercase": "guest@example.com",
                      "photoUrl": "https://example.com/avatars/powerful_panda.svg",
                      "color": "#67DBF4",
                      "textColor": "#FFFFFF",
                      "isAdmin": false
                    }
                  }
                ]
              },
              {
                "annotationId": "reactionAnnotationId2",
                "type": "reaction",
                "icon": "HEART_FACE",
                "commentAnnotationId": "yourAnnotationId",
                "locationId": 5509827173770816,
                "location": {
                  "version": {
                    "id": "v1",
                    "name": "Version 1"
                  }
                },
                "context": {
                  "access": {
                    "default": "velt"
                  },
                  "accessFields": [
                    "default:velt"
                  ]
                },
                "lastUpdated": 1777978714205,
                "fromUsers": [
                  {
                    "lastUpdated": 1777978714205,
                    "from": {
                      "userId": "guestUser456",
                      "organizationId": "d448b95936703db7d0923122172fb13c",
                      "userSnippylyId": "8810801459478142",
                      "isGuest": true,
                      "initial": "P",
                      "clientUserName": "Powerful Panda",
                      "name": "Powerful Panda",
                      "name_lowercase": "powerfulpanda",
                      "clientOrganizationId": "yourOrganizationId",
                      "type": "signedIn",
                      "contacts": [],
                      "email": "guest@example.com",
                      "email_lowercase": "guest@example.com",
                      "photoUrl": "https://example.com/avatars/powerful_panda.svg",
                      "color": "#67DBF4",
                      "textColor": "#FFFFFF",
                      "isAdmin": false
                    }
                  }
                ]
              }
            ],
            "from": {
              "userId": "user123",
              "organizationId": "d448b95936703db7d0923122172fb13c",
              "userSnippylyId": "1174701858709696",
              "photoUrl": "",
              "initial": "J",
              "clientUserName": "John Doe",
              "name": "John Doe",
              "name_lowercase": "johndoe",
              "clientOrganizationId": "yourOrganizationId",
              "clientGroupId": "yourClientGroupId",
              "groupId": "yourGroupId",
              "type": "signedIn",
              "contacts": [],
              "email": "john.doe@example.com",
              "email_lowercase": "john.doe@example.com",
              "color": "#a259fe",
              "textColor": "#FFFFFF",
              "isAdmin": false
            }
          }
        ],
        "status": {
          "id": "OPEN",
          "name": "Open",
          "color": "var(--velt-accent, #625DF5)",
          "lightColor": "var(--velt-accent-light, #E7E8FA)",
          "type": "default",
          "svg": "\n      <svg\n        width=\"16\"\n        height=\"16\"\n        viewBox=\"0 0 16 16\"\n        fill=\"none\"\n        xmlns=\"http://www.w3.org/2000/svg\"\n      >\n        <path\n          fill-rule=\"evenodd\"\n          clip-rule=\"evenodd\"\n          d=\"M8.00016 13.3333C10.9457 13.3333 13.3335 10.9455 13.3335 8.00001C13.3335 5.05449 10.9457 2.66668 8.00016 2.66668C5.05464 2.66668 2.66683 5.05449 2.66683 8.00001C2.66683 10.9455 5.05464 13.3333 8.00016 13.3333ZM8.00016 14.6667C11.6821 14.6667 14.6668 11.6819 14.6668 8.00001C14.6668 4.31811 11.6821 1.33334 8.00016 1.33334C4.31826 1.33334 1.3335 4.31811 1.3335 8.00001C1.3335 11.6819 4.31826 14.6667 8.00016 14.6667Z\"\n          fill=\"currentColor\"\n        />\n      </svg>\n      "
        }
      },
      null // null is returned only if you provided an annotationId that doesn't exist
    ],
    "nextPageToken": "pageToken"
  }
}