> ## Documentation Index
> Fetch the complete documentation index at: https://velt.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Comment Annotations
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](https://console.velt.dev/dashboard/config/appconfig)
* Deploy v4 series of the Velt SDK.
# Endpoint
`POST https://api.velt.dev/v2/commentannotations/get`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
Document ID. Pass a single document Id or use the documentIds field to pass multiple document Ids.
Array of Document IDs. Limit: Only 30 IDs can be passed at a time.
If you don't provide this, data for all documents will be fetched.
Data will be grouped by document ID.
Array of Location IDs. Limit: Only 30 IDs can be passed at a time.
Folder ID. Filters annotations by the folder.
Array of Annotation IDs. Limit: Only 30 IDs can be passed at a time.
Array of User IDs. Limit: Only 30 IDs can be passed at a time.
Array of User IDs. Filters annotations that mention (tag) any of these users.
Filter annotations resolved by the given user ID.
Filter to agent annotations created by the given agent ID.
Filter to agent annotations from the given agent execution / run ID.
Filter to agent annotations of the given agent type. Must be one of: `built-in`, `custom`, or `external`.
Filter to agent annotations from the given source. Must be one of: `velt` or `external`.
When true, returns only fresh (unaccepted) agent suggestions.
When true, returns all agent annotations regardless of status.
Only one agent filter (`agentId`, `executionId`, `agentType`, `agentSource`, `agentSuggestions`, or `agentComments`) may be supplied per request.
Order of results based on `lastUpdated` timestamp. Must be one of: `asc` or `desc`. Default: `desc`.
Status IDs of the annotations to filter on.
Filter annotations updated after the given lastUpdated timestamp (in milliseconds since epoch).
Filter annotations updated before the given lastUpdated timestamp (in milliseconds since epoch).
Filter annotations created after the given createdAt timestamp (in milliseconds since epoch).
Filter annotations created before the given createdAt timestamp (in milliseconds since epoch).
Number of items to be retrieved per page. Default: 1000.
Page token retrieved from previous API call.
## **Example Requests**
#### 1. Get annotations by organizationId and documentId
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"pageSize": 10,
"pageToken": "1720441573192",
"statusId": "OPEN"
}
}
```
#### 2. Get annotations by organizationId and documentIds grouped by documentId
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentIds": ["yourDocumentId1", "yourDocumentId2"],
"groupByDocumentId": true
}
}
```
#### 3. Get annotations by organizationId, documentId, and locationIds
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"locationIds": [
"locationx"
],
"pageSize": 10,
"pageToken": "1720441573192",
"statusId": "OPEN"
}
}
```
#### 4. Get annotations by organizationId, documentId, locationIds, and userIds
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"locationIds": [
"locationx"
],
"userIds": [
"yourUserId"
],
"pageSize": 10,
"pageToken": "1720441573192",
"statusId": "OPEN"
}
}
```
#### 5. Get annotations by organizationId, documentId, and userIds
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"userIds": [
"yourUserId"
],
"pageSize": 10,
"pageToken": "1720441573192",
"statusId": "OPEN"
}
}
```
#### 6. Get annotations by organizationId, documentId, and annotationIds
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"annotationIds": [
"yourAnnotationId1",
"yourAnnotationId2"
],
"pageSize": 10,
"pageToken": "1720441573192",
"statusId": "OPEN"
}
}
```
#### 7. Get annotations by organizationId, documentId, locationIds, and annotationIds
```JSON theme={null}
{
"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
```JSON theme={null}
{
"data": {
"organizationId": "myorg1",
"statusIds": ["OPEN"],
"updatedAfter": 1720441573192,
"updatedBefore": 1720441573192,
}
}
```
#### 9. Get annotations by organizationId, folderId
```JSON theme={null}
{
"data": {
"organizationId": "myorg1",
"folderId": "folderId1"
}
}
```
#### 10. Get agent annotations by organizationId, documentId, and agentId
```JSON theme={null}
{
"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
```JSON theme={null}
{
"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": "This is a sample comment text.
",
"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 \n \n \n "
}
},
null // null is returned only if you provided an annotationId that doesn't exist
],
"nextPageToken": "pageToken"
}
}
```
#### Success Response with multiple documentIds with groupByDocumentId
```JSON theme={null}
{
"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
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```JSON Single Document theme={null}
{
"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": "This is a sample comment text.
",
"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 \n \n \n "
}
},
null // null is returned only if you provided an annotationId that doesn't exist
],
"nextPageToken": "pageToken"
}
}
```
```JSON Multiple Documents theme={null}
{
"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=="
}
}
```