Add Comment Annotations
curl --request POST \
--url https://api.velt.dev/v2/commentannotations/add \
--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>",
"createOrganization": true,
"createDocument": true,
"verifyUserPermissions": true,
"commentAnnotations": [
{
"annotationId": "<string>",
"location": {
"id": "<string>",
"locationName": "<string>"
},
"targetElement": {
"elementId": "<string>",
"targetText": "<string>",
"occurrence": 123,
"selectAllContent": true
},
"commentData": [
{
"commentId": 123,
"commentText": "<string>",
"commentHtml": "<string>",
"context": {},
"isCommentResolverUsed": true,
"isCommentTextAvailable": true,
"progress": {},
"actions": [
{}
],
"triggerNotification": true,
"triggerActivities": true,
"from": {},
"createdAt": 123,
"lastUpdated": 123,
"taggedUserContacts": [
{
"userId": "<string>",
"contact": {
"userId": "<string>",
"name": "<string>",
"email": "<string>"
}
}
],
"agent": {
"agentSource": "<string>",
"agentId": "<string>",
"executionId": "<string>",
"agentName": "<string>",
"url": "<string>",
"reason": {
"title": "<string>",
"description": "<string>",
"severity": "<string>",
"findingId": "<string>",
"findingType": "<string>",
"issueType": "<string>",
"confidence": 123,
"suggestion": "<string>",
"suggestedFix": "<string>",
"htmlSnippet": "<string>",
"htmlSelector": "<string>",
"source": "<string>",
"knowledgeSection": "<string>"
}
}
}
],
"status": {
"id": "<string>",
"name": "<string>",
"type": "<string>",
"color": "<string>",
"lightColor": "<string>",
"svg": "<string>",
"iconUrl": "<string>"
},
"assignedTo": {},
"context": {},
"createdAt": 123,
"lastUpdated": 123,
"priority": {
"id": "<string>",
"color": "<string>",
"name": "<string>",
"lightColor": "<string>"
},
"type": "<string>",
"suggestion": {
"targetId": "<string>",
"targetType": "<string>",
"oldValue": "<any>",
"newValue": "<any>",
"summary": {},
"driftDetected": true
},
"commentType": "<string>",
"visibility": {
"type": "<string>",
"organizationId": "<string>",
"userIds": [
"<string>"
]
},
"actions": [
{}
]
}
]
}
}
'import requests
url = "https://api.velt.dev/v2/commentannotations/add"
payload = { "data": {
"organizationId": "<string>",
"documentId": "<string>",
"createOrganization": True,
"createDocument": True,
"verifyUserPermissions": True,
"commentAnnotations": [
{
"annotationId": "<string>",
"location": {
"id": "<string>",
"locationName": "<string>"
},
"targetElement": {
"elementId": "<string>",
"targetText": "<string>",
"occurrence": 123,
"selectAllContent": True
},
"commentData": [
{
"commentId": 123,
"commentText": "<string>",
"commentHtml": "<string>",
"context": {},
"isCommentResolverUsed": True,
"isCommentTextAvailable": True,
"progress": {},
"actions": [{}],
"triggerNotification": True,
"triggerActivities": True,
"from": {},
"createdAt": 123,
"lastUpdated": 123,
"taggedUserContacts": [
{
"userId": "<string>",
"contact": {
"userId": "<string>",
"name": "<string>",
"email": "<string>"
}
}
],
"agent": {
"agentSource": "<string>",
"agentId": "<string>",
"executionId": "<string>",
"agentName": "<string>",
"url": "<string>",
"reason": {
"title": "<string>",
"description": "<string>",
"severity": "<string>",
"findingId": "<string>",
"findingType": "<string>",
"issueType": "<string>",
"confidence": 123,
"suggestion": "<string>",
"suggestedFix": "<string>",
"htmlSnippet": "<string>",
"htmlSelector": "<string>",
"source": "<string>",
"knowledgeSection": "<string>"
}
}
}
],
"status": {
"id": "<string>",
"name": "<string>",
"type": "<string>",
"color": "<string>",
"lightColor": "<string>",
"svg": "<string>",
"iconUrl": "<string>"
},
"assignedTo": {},
"context": {},
"createdAt": 123,
"lastUpdated": 123,
"priority": {
"id": "<string>",
"color": "<string>",
"name": "<string>",
"lightColor": "<string>"
},
"type": "<string>",
"suggestion": {
"targetId": "<string>",
"targetType": "<string>",
"oldValue": "<any>",
"newValue": "<any>",
"summary": {},
"driftDetected": True
},
"commentType": "<string>",
"visibility": {
"type": "<string>",
"organizationId": "<string>",
"userIds": ["<string>"]
},
"actions": [{}]
}
]
} }
headers = {
"x-velt-api-key": "<x-velt-api-key>",
"x-velt-auth-token": "<x-velt-auth-token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'x-velt-api-key': '<x-velt-api-key>',
'x-velt-auth-token': '<x-velt-auth-token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
data: {
organizationId: '<string>',
documentId: '<string>',
createOrganization: true,
createDocument: true,
verifyUserPermissions: true,
commentAnnotations: [
{
annotationId: '<string>',
location: {id: '<string>', locationName: '<string>'},
targetElement: {
elementId: '<string>',
targetText: '<string>',
occurrence: 123,
selectAllContent: true
},
commentData: [
{
commentId: 123,
commentText: '<string>',
commentHtml: '<string>',
context: {},
isCommentResolverUsed: true,
isCommentTextAvailable: true,
progress: {},
actions: [{}],
triggerNotification: true,
triggerActivities: true,
from: {},
createdAt: 123,
lastUpdated: 123,
taggedUserContacts: [
{
userId: '<string>',
contact: {userId: '<string>', name: '<string>', email: '<string>'}
}
],
agent: {
agentSource: '<string>',
agentId: '<string>',
executionId: '<string>',
agentName: '<string>',
url: '<string>',
reason: {
title: '<string>',
description: '<string>',
severity: '<string>',
findingId: '<string>',
findingType: '<string>',
issueType: '<string>',
confidence: 123,
suggestion: '<string>',
suggestedFix: '<string>',
htmlSnippet: '<string>',
htmlSelector: '<string>',
source: '<string>',
knowledgeSection: '<string>'
}
}
}
],
status: {
id: '<string>',
name: '<string>',
type: '<string>',
color: '<string>',
lightColor: '<string>',
svg: '<string>',
iconUrl: '<string>'
},
assignedTo: {},
context: {},
createdAt: 123,
lastUpdated: 123,
priority: {id: '<string>', color: '<string>', name: '<string>', lightColor: '<string>'},
type: '<string>',
suggestion: {
targetId: '<string>',
targetType: '<string>',
oldValue: '<any>',
newValue: '<any>',
summary: {},
driftDetected: true
},
commentType: '<string>',
visibility: {type: '<string>', organizationId: '<string>', userIds: ['<string>']},
actions: [{}]
}
]
}
})
};
fetch('https://api.velt.dev/v2/commentannotations/add', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.velt.dev/v2/commentannotations/add",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'data' => [
'organizationId' => '<string>',
'documentId' => '<string>',
'createOrganization' => true,
'createDocument' => true,
'verifyUserPermissions' => true,
'commentAnnotations' => [
[
'annotationId' => '<string>',
'location' => [
'id' => '<string>',
'locationName' => '<string>'
],
'targetElement' => [
'elementId' => '<string>',
'targetText' => '<string>',
'occurrence' => 123,
'selectAllContent' => true
],
'commentData' => [
[
'commentId' => 123,
'commentText' => '<string>',
'commentHtml' => '<string>',
'context' => [
],
'isCommentResolverUsed' => true,
'isCommentTextAvailable' => true,
'progress' => [
],
'actions' => [
[
]
],
'triggerNotification' => true,
'triggerActivities' => true,
'from' => [
],
'createdAt' => 123,
'lastUpdated' => 123,
'taggedUserContacts' => [
[
'userId' => '<string>',
'contact' => [
'userId' => '<string>',
'name' => '<string>',
'email' => '<string>'
]
]
],
'agent' => [
'agentSource' => '<string>',
'agentId' => '<string>',
'executionId' => '<string>',
'agentName' => '<string>',
'url' => '<string>',
'reason' => [
'title' => '<string>',
'description' => '<string>',
'severity' => '<string>',
'findingId' => '<string>',
'findingType' => '<string>',
'issueType' => '<string>',
'confidence' => 123,
'suggestion' => '<string>',
'suggestedFix' => '<string>',
'htmlSnippet' => '<string>',
'htmlSelector' => '<string>',
'source' => '<string>',
'knowledgeSection' => '<string>'
]
]
]
],
'status' => [
'id' => '<string>',
'name' => '<string>',
'type' => '<string>',
'color' => '<string>',
'lightColor' => '<string>',
'svg' => '<string>',
'iconUrl' => '<string>'
],
'assignedTo' => [
],
'context' => [
],
'createdAt' => 123,
'lastUpdated' => 123,
'priority' => [
'id' => '<string>',
'color' => '<string>',
'name' => '<string>',
'lightColor' => '<string>'
],
'type' => '<string>',
'suggestion' => [
'targetId' => '<string>',
'targetType' => '<string>',
'oldValue' => '<any>',
'newValue' => '<any>',
'summary' => [
],
'driftDetected' => true
],
'commentType' => '<string>',
'visibility' => [
'type' => '<string>',
'organizationId' => '<string>',
'userIds' => [
'<string>'
]
],
'actions' => [
[
]
]
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-velt-api-key: <x-velt-api-key>",
"x-velt-auth-token: <x-velt-auth-token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.velt.dev/v2/commentannotations/add"
payload := strings.NewReader("{\n \"data\": {\n \"organizationId\": \"<string>\",\n \"documentId\": \"<string>\",\n \"createOrganization\": true,\n \"createDocument\": true,\n \"verifyUserPermissions\": true,\n \"commentAnnotations\": [\n {\n \"annotationId\": \"<string>\",\n \"location\": {\n \"id\": \"<string>\",\n \"locationName\": \"<string>\"\n },\n \"targetElement\": {\n \"elementId\": \"<string>\",\n \"targetText\": \"<string>\",\n \"occurrence\": 123,\n \"selectAllContent\": true\n },\n \"commentData\": [\n {\n \"commentId\": 123,\n \"commentText\": \"<string>\",\n \"commentHtml\": \"<string>\",\n \"context\": {},\n \"isCommentResolverUsed\": true,\n \"isCommentTextAvailable\": true,\n \"progress\": {},\n \"actions\": [\n {}\n ],\n \"triggerNotification\": true,\n \"triggerActivities\": true,\n \"from\": {},\n \"createdAt\": 123,\n \"lastUpdated\": 123,\n \"taggedUserContacts\": [\n {\n \"userId\": \"<string>\",\n \"contact\": {\n \"userId\": \"<string>\",\n \"name\": \"<string>\",\n \"email\": \"<string>\"\n }\n }\n ],\n \"agent\": {\n \"agentSource\": \"<string>\",\n \"agentId\": \"<string>\",\n \"executionId\": \"<string>\",\n \"agentName\": \"<string>\",\n \"url\": \"<string>\",\n \"reason\": {\n \"title\": \"<string>\",\n \"description\": \"<string>\",\n \"severity\": \"<string>\",\n \"findingId\": \"<string>\",\n \"findingType\": \"<string>\",\n \"issueType\": \"<string>\",\n \"confidence\": 123,\n \"suggestion\": \"<string>\",\n \"suggestedFix\": \"<string>\",\n \"htmlSnippet\": \"<string>\",\n \"htmlSelector\": \"<string>\",\n \"source\": \"<string>\",\n \"knowledgeSection\": \"<string>\"\n }\n }\n }\n ],\n \"status\": {\n \"id\": \"<string>\",\n \"name\": \"<string>\",\n \"type\": \"<string>\",\n \"color\": \"<string>\",\n \"lightColor\": \"<string>\",\n \"svg\": \"<string>\",\n \"iconUrl\": \"<string>\"\n },\n \"assignedTo\": {},\n \"context\": {},\n \"createdAt\": 123,\n \"lastUpdated\": 123,\n \"priority\": {\n \"id\": \"<string>\",\n \"color\": \"<string>\",\n \"name\": \"<string>\",\n \"lightColor\": \"<string>\"\n },\n \"type\": \"<string>\",\n \"suggestion\": {\n \"targetId\": \"<string>\",\n \"targetType\": \"<string>\",\n \"oldValue\": \"<any>\",\n \"newValue\": \"<any>\",\n \"summary\": {},\n \"driftDetected\": true\n },\n \"commentType\": \"<string>\",\n \"visibility\": {\n \"type\": \"<string>\",\n \"organizationId\": \"<string>\",\n \"userIds\": [\n \"<string>\"\n ]\n },\n \"actions\": [\n {}\n ]\n }\n ]\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-velt-api-key", "<x-velt-api-key>")
req.Header.Add("x-velt-auth-token", "<x-velt-auth-token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.velt.dev/v2/commentannotations/add")
.header("x-velt-api-key", "<x-velt-api-key>")
.header("x-velt-auth-token", "<x-velt-auth-token>")
.header("Content-Type", "application/json")
.body("{\n \"data\": {\n \"organizationId\": \"<string>\",\n \"documentId\": \"<string>\",\n \"createOrganization\": true,\n \"createDocument\": true,\n \"verifyUserPermissions\": true,\n \"commentAnnotations\": [\n {\n \"annotationId\": \"<string>\",\n \"location\": {\n \"id\": \"<string>\",\n \"locationName\": \"<string>\"\n },\n \"targetElement\": {\n \"elementId\": \"<string>\",\n \"targetText\": \"<string>\",\n \"occurrence\": 123,\n \"selectAllContent\": true\n },\n \"commentData\": [\n {\n \"commentId\": 123,\n \"commentText\": \"<string>\",\n \"commentHtml\": \"<string>\",\n \"context\": {},\n \"isCommentResolverUsed\": true,\n \"isCommentTextAvailable\": true,\n \"progress\": {},\n \"actions\": [\n {}\n ],\n \"triggerNotification\": true,\n \"triggerActivities\": true,\n \"from\": {},\n \"createdAt\": 123,\n \"lastUpdated\": 123,\n \"taggedUserContacts\": [\n {\n \"userId\": \"<string>\",\n \"contact\": {\n \"userId\": \"<string>\",\n \"name\": \"<string>\",\n \"email\": \"<string>\"\n }\n }\n ],\n \"agent\": {\n \"agentSource\": \"<string>\",\n \"agentId\": \"<string>\",\n \"executionId\": \"<string>\",\n \"agentName\": \"<string>\",\n \"url\": \"<string>\",\n \"reason\": {\n \"title\": \"<string>\",\n \"description\": \"<string>\",\n \"severity\": \"<string>\",\n \"findingId\": \"<string>\",\n \"findingType\": \"<string>\",\n \"issueType\": \"<string>\",\n \"confidence\": 123,\n \"suggestion\": \"<string>\",\n \"suggestedFix\": \"<string>\",\n \"htmlSnippet\": \"<string>\",\n \"htmlSelector\": \"<string>\",\n \"source\": \"<string>\",\n \"knowledgeSection\": \"<string>\"\n }\n }\n }\n ],\n \"status\": {\n \"id\": \"<string>\",\n \"name\": \"<string>\",\n \"type\": \"<string>\",\n \"color\": \"<string>\",\n \"lightColor\": \"<string>\",\n \"svg\": \"<string>\",\n \"iconUrl\": \"<string>\"\n },\n \"assignedTo\": {},\n \"context\": {},\n \"createdAt\": 123,\n \"lastUpdated\": 123,\n \"priority\": {\n \"id\": \"<string>\",\n \"color\": \"<string>\",\n \"name\": \"<string>\",\n \"lightColor\": \"<string>\"\n },\n \"type\": \"<string>\",\n \"suggestion\": {\n \"targetId\": \"<string>\",\n \"targetType\": \"<string>\",\n \"oldValue\": \"<any>\",\n \"newValue\": \"<any>\",\n \"summary\": {},\n \"driftDetected\": true\n },\n \"commentType\": \"<string>\",\n \"visibility\": {\n \"type\": \"<string>\",\n \"organizationId\": \"<string>\",\n \"userIds\": [\n \"<string>\"\n ]\n },\n \"actions\": [\n {}\n ]\n }\n ]\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.velt.dev/v2/commentannotations/add")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-velt-api-key"] = '<x-velt-api-key>'
request["x-velt-auth-token"] = '<x-velt-auth-token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"data\": {\n \"organizationId\": \"<string>\",\n \"documentId\": \"<string>\",\n \"createOrganization\": true,\n \"createDocument\": true,\n \"verifyUserPermissions\": true,\n \"commentAnnotations\": [\n {\n \"annotationId\": \"<string>\",\n \"location\": {\n \"id\": \"<string>\",\n \"locationName\": \"<string>\"\n },\n \"targetElement\": {\n \"elementId\": \"<string>\",\n \"targetText\": \"<string>\",\n \"occurrence\": 123,\n \"selectAllContent\": true\n },\n \"commentData\": [\n {\n \"commentId\": 123,\n \"commentText\": \"<string>\",\n \"commentHtml\": \"<string>\",\n \"context\": {},\n \"isCommentResolverUsed\": true,\n \"isCommentTextAvailable\": true,\n \"progress\": {},\n \"actions\": [\n {}\n ],\n \"triggerNotification\": true,\n \"triggerActivities\": true,\n \"from\": {},\n \"createdAt\": 123,\n \"lastUpdated\": 123,\n \"taggedUserContacts\": [\n {\n \"userId\": \"<string>\",\n \"contact\": {\n \"userId\": \"<string>\",\n \"name\": \"<string>\",\n \"email\": \"<string>\"\n }\n }\n ],\n \"agent\": {\n \"agentSource\": \"<string>\",\n \"agentId\": \"<string>\",\n \"executionId\": \"<string>\",\n \"agentName\": \"<string>\",\n \"url\": \"<string>\",\n \"reason\": {\n \"title\": \"<string>\",\n \"description\": \"<string>\",\n \"severity\": \"<string>\",\n \"findingId\": \"<string>\",\n \"findingType\": \"<string>\",\n \"issueType\": \"<string>\",\n \"confidence\": 123,\n \"suggestion\": \"<string>\",\n \"suggestedFix\": \"<string>\",\n \"htmlSnippet\": \"<string>\",\n \"htmlSelector\": \"<string>\",\n \"source\": \"<string>\",\n \"knowledgeSection\": \"<string>\"\n }\n }\n }\n ],\n \"status\": {\n \"id\": \"<string>\",\n \"name\": \"<string>\",\n \"type\": \"<string>\",\n \"color\": \"<string>\",\n \"lightColor\": \"<string>\",\n \"svg\": \"<string>\",\n \"iconUrl\": \"<string>\"\n },\n \"assignedTo\": {},\n \"context\": {},\n \"createdAt\": 123,\n \"lastUpdated\": 123,\n \"priority\": {\n \"id\": \"<string>\",\n \"color\": \"<string>\",\n \"name\": \"<string>\",\n \"lightColor\": \"<string>\"\n },\n \"type\": \"<string>\",\n \"suggestion\": {\n \"targetId\": \"<string>\",\n \"targetType\": \"<string>\",\n \"oldValue\": \"<any>\",\n \"newValue\": \"<any>\",\n \"summary\": {},\n \"driftDetected\": true\n },\n \"commentType\": \"<string>\",\n \"visibility\": {\n \"type\": \"<string>\",\n \"organizationId\": \"<string>\",\n \"userIds\": [\n \"<string>\"\n ]\n },\n \"actions\": [\n {}\n ]\n }\n ]\n }\n}"
response = http.request(request)
puts response.read_body{
"result": {
"status": "success",
"message": "Comment Annotation(s) added successfully.",
"data": {
"-O0mpUziLcBwzREvZKs6": {
"success": true,
"annotationId": "-O0mpUziLcBwzREvZKs6",
"commentIds": [
126535
],
"message": "Added Successfully"
}
}
}
}
Comments Annotations
Add Comment Annotations
Create V2 comment annotations via REST: plain comments, agent findings, suggestions with a proposed-change payload, and private annotations.
POST
/
v2
/
commentannotations
/
add
Add Comment Annotations
curl --request POST \
--url https://api.velt.dev/v2/commentannotations/add \
--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>",
"createOrganization": true,
"createDocument": true,
"verifyUserPermissions": true,
"commentAnnotations": [
{
"annotationId": "<string>",
"location": {
"id": "<string>",
"locationName": "<string>"
},
"targetElement": {
"elementId": "<string>",
"targetText": "<string>",
"occurrence": 123,
"selectAllContent": true
},
"commentData": [
{
"commentId": 123,
"commentText": "<string>",
"commentHtml": "<string>",
"context": {},
"isCommentResolverUsed": true,
"isCommentTextAvailable": true,
"progress": {},
"actions": [
{}
],
"triggerNotification": true,
"triggerActivities": true,
"from": {},
"createdAt": 123,
"lastUpdated": 123,
"taggedUserContacts": [
{
"userId": "<string>",
"contact": {
"userId": "<string>",
"name": "<string>",
"email": "<string>"
}
}
],
"agent": {
"agentSource": "<string>",
"agentId": "<string>",
"executionId": "<string>",
"agentName": "<string>",
"url": "<string>",
"reason": {
"title": "<string>",
"description": "<string>",
"severity": "<string>",
"findingId": "<string>",
"findingType": "<string>",
"issueType": "<string>",
"confidence": 123,
"suggestion": "<string>",
"suggestedFix": "<string>",
"htmlSnippet": "<string>",
"htmlSelector": "<string>",
"source": "<string>",
"knowledgeSection": "<string>"
}
}
}
],
"status": {
"id": "<string>",
"name": "<string>",
"type": "<string>",
"color": "<string>",
"lightColor": "<string>",
"svg": "<string>",
"iconUrl": "<string>"
},
"assignedTo": {},
"context": {},
"createdAt": 123,
"lastUpdated": 123,
"priority": {
"id": "<string>",
"color": "<string>",
"name": "<string>",
"lightColor": "<string>"
},
"type": "<string>",
"suggestion": {
"targetId": "<string>",
"targetType": "<string>",
"oldValue": "<any>",
"newValue": "<any>",
"summary": {},
"driftDetected": true
},
"commentType": "<string>",
"visibility": {
"type": "<string>",
"organizationId": "<string>",
"userIds": [
"<string>"
]
},
"actions": [
{}
]
}
]
}
}
'import requests
url = "https://api.velt.dev/v2/commentannotations/add"
payload = { "data": {
"organizationId": "<string>",
"documentId": "<string>",
"createOrganization": True,
"createDocument": True,
"verifyUserPermissions": True,
"commentAnnotations": [
{
"annotationId": "<string>",
"location": {
"id": "<string>",
"locationName": "<string>"
},
"targetElement": {
"elementId": "<string>",
"targetText": "<string>",
"occurrence": 123,
"selectAllContent": True
},
"commentData": [
{
"commentId": 123,
"commentText": "<string>",
"commentHtml": "<string>",
"context": {},
"isCommentResolverUsed": True,
"isCommentTextAvailable": True,
"progress": {},
"actions": [{}],
"triggerNotification": True,
"triggerActivities": True,
"from": {},
"createdAt": 123,
"lastUpdated": 123,
"taggedUserContacts": [
{
"userId": "<string>",
"contact": {
"userId": "<string>",
"name": "<string>",
"email": "<string>"
}
}
],
"agent": {
"agentSource": "<string>",
"agentId": "<string>",
"executionId": "<string>",
"agentName": "<string>",
"url": "<string>",
"reason": {
"title": "<string>",
"description": "<string>",
"severity": "<string>",
"findingId": "<string>",
"findingType": "<string>",
"issueType": "<string>",
"confidence": 123,
"suggestion": "<string>",
"suggestedFix": "<string>",
"htmlSnippet": "<string>",
"htmlSelector": "<string>",
"source": "<string>",
"knowledgeSection": "<string>"
}
}
}
],
"status": {
"id": "<string>",
"name": "<string>",
"type": "<string>",
"color": "<string>",
"lightColor": "<string>",
"svg": "<string>",
"iconUrl": "<string>"
},
"assignedTo": {},
"context": {},
"createdAt": 123,
"lastUpdated": 123,
"priority": {
"id": "<string>",
"color": "<string>",
"name": "<string>",
"lightColor": "<string>"
},
"type": "<string>",
"suggestion": {
"targetId": "<string>",
"targetType": "<string>",
"oldValue": "<any>",
"newValue": "<any>",
"summary": {},
"driftDetected": True
},
"commentType": "<string>",
"visibility": {
"type": "<string>",
"organizationId": "<string>",
"userIds": ["<string>"]
},
"actions": [{}]
}
]
} }
headers = {
"x-velt-api-key": "<x-velt-api-key>",
"x-velt-auth-token": "<x-velt-auth-token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'x-velt-api-key': '<x-velt-api-key>',
'x-velt-auth-token': '<x-velt-auth-token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
data: {
organizationId: '<string>',
documentId: '<string>',
createOrganization: true,
createDocument: true,
verifyUserPermissions: true,
commentAnnotations: [
{
annotationId: '<string>',
location: {id: '<string>', locationName: '<string>'},
targetElement: {
elementId: '<string>',
targetText: '<string>',
occurrence: 123,
selectAllContent: true
},
commentData: [
{
commentId: 123,
commentText: '<string>',
commentHtml: '<string>',
context: {},
isCommentResolverUsed: true,
isCommentTextAvailable: true,
progress: {},
actions: [{}],
triggerNotification: true,
triggerActivities: true,
from: {},
createdAt: 123,
lastUpdated: 123,
taggedUserContacts: [
{
userId: '<string>',
contact: {userId: '<string>', name: '<string>', email: '<string>'}
}
],
agent: {
agentSource: '<string>',
agentId: '<string>',
executionId: '<string>',
agentName: '<string>',
url: '<string>',
reason: {
title: '<string>',
description: '<string>',
severity: '<string>',
findingId: '<string>',
findingType: '<string>',
issueType: '<string>',
confidence: 123,
suggestion: '<string>',
suggestedFix: '<string>',
htmlSnippet: '<string>',
htmlSelector: '<string>',
source: '<string>',
knowledgeSection: '<string>'
}
}
}
],
status: {
id: '<string>',
name: '<string>',
type: '<string>',
color: '<string>',
lightColor: '<string>',
svg: '<string>',
iconUrl: '<string>'
},
assignedTo: {},
context: {},
createdAt: 123,
lastUpdated: 123,
priority: {id: '<string>', color: '<string>', name: '<string>', lightColor: '<string>'},
type: '<string>',
suggestion: {
targetId: '<string>',
targetType: '<string>',
oldValue: '<any>',
newValue: '<any>',
summary: {},
driftDetected: true
},
commentType: '<string>',
visibility: {type: '<string>', organizationId: '<string>', userIds: ['<string>']},
actions: [{}]
}
]
}
})
};
fetch('https://api.velt.dev/v2/commentannotations/add', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.velt.dev/v2/commentannotations/add",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'data' => [
'organizationId' => '<string>',
'documentId' => '<string>',
'createOrganization' => true,
'createDocument' => true,
'verifyUserPermissions' => true,
'commentAnnotations' => [
[
'annotationId' => '<string>',
'location' => [
'id' => '<string>',
'locationName' => '<string>'
],
'targetElement' => [
'elementId' => '<string>',
'targetText' => '<string>',
'occurrence' => 123,
'selectAllContent' => true
],
'commentData' => [
[
'commentId' => 123,
'commentText' => '<string>',
'commentHtml' => '<string>',
'context' => [
],
'isCommentResolverUsed' => true,
'isCommentTextAvailable' => true,
'progress' => [
],
'actions' => [
[
]
],
'triggerNotification' => true,
'triggerActivities' => true,
'from' => [
],
'createdAt' => 123,
'lastUpdated' => 123,
'taggedUserContacts' => [
[
'userId' => '<string>',
'contact' => [
'userId' => '<string>',
'name' => '<string>',
'email' => '<string>'
]
]
],
'agent' => [
'agentSource' => '<string>',
'agentId' => '<string>',
'executionId' => '<string>',
'agentName' => '<string>',
'url' => '<string>',
'reason' => [
'title' => '<string>',
'description' => '<string>',
'severity' => '<string>',
'findingId' => '<string>',
'findingType' => '<string>',
'issueType' => '<string>',
'confidence' => 123,
'suggestion' => '<string>',
'suggestedFix' => '<string>',
'htmlSnippet' => '<string>',
'htmlSelector' => '<string>',
'source' => '<string>',
'knowledgeSection' => '<string>'
]
]
]
],
'status' => [
'id' => '<string>',
'name' => '<string>',
'type' => '<string>',
'color' => '<string>',
'lightColor' => '<string>',
'svg' => '<string>',
'iconUrl' => '<string>'
],
'assignedTo' => [
],
'context' => [
],
'createdAt' => 123,
'lastUpdated' => 123,
'priority' => [
'id' => '<string>',
'color' => '<string>',
'name' => '<string>',
'lightColor' => '<string>'
],
'type' => '<string>',
'suggestion' => [
'targetId' => '<string>',
'targetType' => '<string>',
'oldValue' => '<any>',
'newValue' => '<any>',
'summary' => [
],
'driftDetected' => true
],
'commentType' => '<string>',
'visibility' => [
'type' => '<string>',
'organizationId' => '<string>',
'userIds' => [
'<string>'
]
],
'actions' => [
[
]
]
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-velt-api-key: <x-velt-api-key>",
"x-velt-auth-token: <x-velt-auth-token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.velt.dev/v2/commentannotations/add"
payload := strings.NewReader("{\n \"data\": {\n \"organizationId\": \"<string>\",\n \"documentId\": \"<string>\",\n \"createOrganization\": true,\n \"createDocument\": true,\n \"verifyUserPermissions\": true,\n \"commentAnnotations\": [\n {\n \"annotationId\": \"<string>\",\n \"location\": {\n \"id\": \"<string>\",\n \"locationName\": \"<string>\"\n },\n \"targetElement\": {\n \"elementId\": \"<string>\",\n \"targetText\": \"<string>\",\n \"occurrence\": 123,\n \"selectAllContent\": true\n },\n \"commentData\": [\n {\n \"commentId\": 123,\n \"commentText\": \"<string>\",\n \"commentHtml\": \"<string>\",\n \"context\": {},\n \"isCommentResolverUsed\": true,\n \"isCommentTextAvailable\": true,\n \"progress\": {},\n \"actions\": [\n {}\n ],\n \"triggerNotification\": true,\n \"triggerActivities\": true,\n \"from\": {},\n \"createdAt\": 123,\n \"lastUpdated\": 123,\n \"taggedUserContacts\": [\n {\n \"userId\": \"<string>\",\n \"contact\": {\n \"userId\": \"<string>\",\n \"name\": \"<string>\",\n \"email\": \"<string>\"\n }\n }\n ],\n \"agent\": {\n \"agentSource\": \"<string>\",\n \"agentId\": \"<string>\",\n \"executionId\": \"<string>\",\n \"agentName\": \"<string>\",\n \"url\": \"<string>\",\n \"reason\": {\n \"title\": \"<string>\",\n \"description\": \"<string>\",\n \"severity\": \"<string>\",\n \"findingId\": \"<string>\",\n \"findingType\": \"<string>\",\n \"issueType\": \"<string>\",\n \"confidence\": 123,\n \"suggestion\": \"<string>\",\n \"suggestedFix\": \"<string>\",\n \"htmlSnippet\": \"<string>\",\n \"htmlSelector\": \"<string>\",\n \"source\": \"<string>\",\n \"knowledgeSection\": \"<string>\"\n }\n }\n }\n ],\n \"status\": {\n \"id\": \"<string>\",\n \"name\": \"<string>\",\n \"type\": \"<string>\",\n \"color\": \"<string>\",\n \"lightColor\": \"<string>\",\n \"svg\": \"<string>\",\n \"iconUrl\": \"<string>\"\n },\n \"assignedTo\": {},\n \"context\": {},\n \"createdAt\": 123,\n \"lastUpdated\": 123,\n \"priority\": {\n \"id\": \"<string>\",\n \"color\": \"<string>\",\n \"name\": \"<string>\",\n \"lightColor\": \"<string>\"\n },\n \"type\": \"<string>\",\n \"suggestion\": {\n \"targetId\": \"<string>\",\n \"targetType\": \"<string>\",\n \"oldValue\": \"<any>\",\n \"newValue\": \"<any>\",\n \"summary\": {},\n \"driftDetected\": true\n },\n \"commentType\": \"<string>\",\n \"visibility\": {\n \"type\": \"<string>\",\n \"organizationId\": \"<string>\",\n \"userIds\": [\n \"<string>\"\n ]\n },\n \"actions\": [\n {}\n ]\n }\n ]\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-velt-api-key", "<x-velt-api-key>")
req.Header.Add("x-velt-auth-token", "<x-velt-auth-token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.velt.dev/v2/commentannotations/add")
.header("x-velt-api-key", "<x-velt-api-key>")
.header("x-velt-auth-token", "<x-velt-auth-token>")
.header("Content-Type", "application/json")
.body("{\n \"data\": {\n \"organizationId\": \"<string>\",\n \"documentId\": \"<string>\",\n \"createOrganization\": true,\n \"createDocument\": true,\n \"verifyUserPermissions\": true,\n \"commentAnnotations\": [\n {\n \"annotationId\": \"<string>\",\n \"location\": {\n \"id\": \"<string>\",\n \"locationName\": \"<string>\"\n },\n \"targetElement\": {\n \"elementId\": \"<string>\",\n \"targetText\": \"<string>\",\n \"occurrence\": 123,\n \"selectAllContent\": true\n },\n \"commentData\": [\n {\n \"commentId\": 123,\n \"commentText\": \"<string>\",\n \"commentHtml\": \"<string>\",\n \"context\": {},\n \"isCommentResolverUsed\": true,\n \"isCommentTextAvailable\": true,\n \"progress\": {},\n \"actions\": [\n {}\n ],\n \"triggerNotification\": true,\n \"triggerActivities\": true,\n \"from\": {},\n \"createdAt\": 123,\n \"lastUpdated\": 123,\n \"taggedUserContacts\": [\n {\n \"userId\": \"<string>\",\n \"contact\": {\n \"userId\": \"<string>\",\n \"name\": \"<string>\",\n \"email\": \"<string>\"\n }\n }\n ],\n \"agent\": {\n \"agentSource\": \"<string>\",\n \"agentId\": \"<string>\",\n \"executionId\": \"<string>\",\n \"agentName\": \"<string>\",\n \"url\": \"<string>\",\n \"reason\": {\n \"title\": \"<string>\",\n \"description\": \"<string>\",\n \"severity\": \"<string>\",\n \"findingId\": \"<string>\",\n \"findingType\": \"<string>\",\n \"issueType\": \"<string>\",\n \"confidence\": 123,\n \"suggestion\": \"<string>\",\n \"suggestedFix\": \"<string>\",\n \"htmlSnippet\": \"<string>\",\n \"htmlSelector\": \"<string>\",\n \"source\": \"<string>\",\n \"knowledgeSection\": \"<string>\"\n }\n }\n }\n ],\n \"status\": {\n \"id\": \"<string>\",\n \"name\": \"<string>\",\n \"type\": \"<string>\",\n \"color\": \"<string>\",\n \"lightColor\": \"<string>\",\n \"svg\": \"<string>\",\n \"iconUrl\": \"<string>\"\n },\n \"assignedTo\": {},\n \"context\": {},\n \"createdAt\": 123,\n \"lastUpdated\": 123,\n \"priority\": {\n \"id\": \"<string>\",\n \"color\": \"<string>\",\n \"name\": \"<string>\",\n \"lightColor\": \"<string>\"\n },\n \"type\": \"<string>\",\n \"suggestion\": {\n \"targetId\": \"<string>\",\n \"targetType\": \"<string>\",\n \"oldValue\": \"<any>\",\n \"newValue\": \"<any>\",\n \"summary\": {},\n \"driftDetected\": true\n },\n \"commentType\": \"<string>\",\n \"visibility\": {\n \"type\": \"<string>\",\n \"organizationId\": \"<string>\",\n \"userIds\": [\n \"<string>\"\n ]\n },\n \"actions\": [\n {}\n ]\n }\n ]\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.velt.dev/v2/commentannotations/add")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-velt-api-key"] = '<x-velt-api-key>'
request["x-velt-auth-token"] = '<x-velt-auth-token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"data\": {\n \"organizationId\": \"<string>\",\n \"documentId\": \"<string>\",\n \"createOrganization\": true,\n \"createDocument\": true,\n \"verifyUserPermissions\": true,\n \"commentAnnotations\": [\n {\n \"annotationId\": \"<string>\",\n \"location\": {\n \"id\": \"<string>\",\n \"locationName\": \"<string>\"\n },\n \"targetElement\": {\n \"elementId\": \"<string>\",\n \"targetText\": \"<string>\",\n \"occurrence\": 123,\n \"selectAllContent\": true\n },\n \"commentData\": [\n {\n \"commentId\": 123,\n \"commentText\": \"<string>\",\n \"commentHtml\": \"<string>\",\n \"context\": {},\n \"isCommentResolverUsed\": true,\n \"isCommentTextAvailable\": true,\n \"progress\": {},\n \"actions\": [\n {}\n ],\n \"triggerNotification\": true,\n \"triggerActivities\": true,\n \"from\": {},\n \"createdAt\": 123,\n \"lastUpdated\": 123,\n \"taggedUserContacts\": [\n {\n \"userId\": \"<string>\",\n \"contact\": {\n \"userId\": \"<string>\",\n \"name\": \"<string>\",\n \"email\": \"<string>\"\n }\n }\n ],\n \"agent\": {\n \"agentSource\": \"<string>\",\n \"agentId\": \"<string>\",\n \"executionId\": \"<string>\",\n \"agentName\": \"<string>\",\n \"url\": \"<string>\",\n \"reason\": {\n \"title\": \"<string>\",\n \"description\": \"<string>\",\n \"severity\": \"<string>\",\n \"findingId\": \"<string>\",\n \"findingType\": \"<string>\",\n \"issueType\": \"<string>\",\n \"confidence\": 123,\n \"suggestion\": \"<string>\",\n \"suggestedFix\": \"<string>\",\n \"htmlSnippet\": \"<string>\",\n \"htmlSelector\": \"<string>\",\n \"source\": \"<string>\",\n \"knowledgeSection\": \"<string>\"\n }\n }\n }\n ],\n \"status\": {\n \"id\": \"<string>\",\n \"name\": \"<string>\",\n \"type\": \"<string>\",\n \"color\": \"<string>\",\n \"lightColor\": \"<string>\",\n \"svg\": \"<string>\",\n \"iconUrl\": \"<string>\"\n },\n \"assignedTo\": {},\n \"context\": {},\n \"createdAt\": 123,\n \"lastUpdated\": 123,\n \"priority\": {\n \"id\": \"<string>\",\n \"color\": \"<string>\",\n \"name\": \"<string>\",\n \"lightColor\": \"<string>\"\n },\n \"type\": \"<string>\",\n \"suggestion\": {\n \"targetId\": \"<string>\",\n \"targetType\": \"<string>\",\n \"oldValue\": \"<any>\",\n \"newValue\": \"<any>\",\n \"summary\": {},\n \"driftDetected\": true\n },\n \"commentType\": \"<string>\",\n \"visibility\": {\n \"type\": \"<string>\",\n \"organizationId\": \"<string>\",\n \"userIds\": [\n \"<string>\"\n ]\n },\n \"actions\": [\n {}\n ]\n }\n ]\n }\n}"
response = http.request(request)
puts response.read_body{
"result": {
"status": "success",
"message": "Comment Annotation(s) added successfully.",
"data": {
"-O0mpUziLcBwzREvZKs6": {
"success": true,
"annotationId": "-O0mpUziLcBwzREvZKs6",
"commentIds": [
126535
],
"message": "Added Successfully"
}
}
}
}
Use this API to add comment annotations to a document within an organization.
In this example,
To attach a finding from an agent run through your own framework, use
When some annotations fail or a user is permission denied, the error carries the same per-annotation map in
- You can add comments on an element, text or page.
- You can provide HTML or text content.
- Additional filters can be applied using location IDs.
Endpoint
POST https://api.velt.dev/v2/commentannotations/add
Headers
string
required
Your API key.
string
required
Your Auth Token.
Body
Params
object
required
Show properties
Show properties
string
required
Organization ID
string
required
Document ID
boolean
If set to true, a new organization will be created (if it doesn’t exist) before the annotation is added.
boolean
If set to true, a new document will be created (if it doesn’t exist) before the annotation is added.
boolean
When enabled, verifies the user has access to the document before creating comment annotations.
This ensures annotations respect document access permissions configured via Access Control or Permission Provider.Default:
falseobject[]
required
Show properties
Show properties
string
Custom Annotation ID. If not provided, Velt will generate a unique ID for the annotation.
object
Target Element
Show properties
Show properties
string
Element DOM Id. When used with
targetText, defines the text search boundaries for locating text comments within the specified element.string
Target Text. Provide this if you want to add comment annotation on the provided text content.
number
Occurrence. Provide this if you want to add comment annotation on a text content.
boolean
Select All Content. Provide this if you want to select and add comment annotation on the entire text content of the target elementId.
object[]
required
Array of Comment Data
Show properties
Show properties
number
Custom Comment ID. If not provided, Velt will generate a unique ID for the comment.
string
Comment content in plain text string. To tag users, wrap their userId in double curly braces like
{{userId}}. The frontend will replace this with the user’s name.string
Comment content in HTML string. To tag users, wrap their userId in double curly braces like
{{userId}}. The frontend will replace this with the user’s name.object
Custom key/value metadata object. This is used to store any additional information about the comment.
boolean
Use this for self-hosting comments data. Set this as true if you are comments resolver data provider in the SDK.
boolean
Use this for self-hosting comments data. Set this as true if this comment will have text content. Sometimes, comments might only have attachments and in that case, set this as false.
CommentProgress
Turns this comment into a live progress row while
progress.state is active. Absence leaves the comment unaffected. See CommentProgress for the full shape. steps is capped at 100 entries.CommentAction[]
Customer-defined action chips rendered on this comment row. Overrides the annotation-level
actions default for this row. Capped at 20 entries. See CommentAction for the full shape.boolean
When enabled, adding comments via the REST API will trigger in-app notifications, email notifications to relevant users and also trigger webhooks matching the SDK’s native notification behavior. Default: false.
boolean
When enabled, adding comments via the REST API will create activity log records matching the SDK’s native activity log behavior. Default: false.
User
required
User object from whom the comment is added
number
Created At timestamp (in milliseconds since epoch).
number
Last Updated timestamp (in milliseconds since epoch).
object[]
Array of tagged user contacts. Use this field to provide information about users tagged in the comment. Each userId wrapped in
{{userId}} in commentText or commentHtml should have a corresponding entry here so the frontend can replace it with the user’s name.Show properties
Show properties
string
required
User ID of the tagged user. This should match the userId used in
{{userId}} syntax within commentText or commentHtml.object
Marks this comment as agent-authored (an agent finding or an agent reply). V2 only. When set, the server stamps
sourceType: "agent" on the comment. When set on the root comment (commentData[0]), the server also generates the annotation-level agent block and stamps sourceType: "agent" on the annotation. Discriminated on agentSource.Show properties
Show properties
string
required
Origin of the agent. Must be one of:
velt or external.string
required
Agent ID. Must be non-empty for both sources. When
agentSource is velt, it is a built-in agent like spell-check or a custom agent ID that is verified server-side (unknown IDs return NOT_FOUND). When agentSource is external, it is your own identifier — opaque and never validated against any registry.string
Execution / run ID for this agent invocation.
string
Display name for the agent. Required when
agentSource is external (the only source of truth for an external agent’s name). Not used for velt agents (their name is resolved server-side).string
Page URL associated with the finding.
object
required
Finding details produced by the agent. Additional custom fields are preserved.
Show properties
Show properties
string
required
Short finding title.
string
required
Finding description.
string
required
Severity of the finding. Must be one of:
critical, high, medium, low, or info.string
Unique identifier for the finding.
string
Type of finding. Must be one of:
text, pin, or page.string
Custom issue classification.
number
Confidence score for the finding. Integer between 0 and 100.
string
Suggested change in plain text.
string
Suggested fix for the finding.
string
Relevant HTML snippet for the finding.
string
CSS/HTML selector pointing to the finding location.
string
Provenance of the rule that triggered the finding. Must be one of:
instructions or knowledge.string
Knowledge section that triggered the finding.
Status
Status
Show properties
Show properties
string
required
Status ID
string
required
Status Name
string
required
Type. Must be one of:
default, ongoing, or terminal.string
required
Text and comment pin color
string
required
Background color on the status indicator
string
Raw SVG of the icon. Either
svg or iconUrl is required.string
Icon URL. Either
svg or iconUrl is required.User
User object to whom the comment is assigned
object
Custom key/value metadata object
number
Created At timestamp (in milliseconds since epoch).
number
Last Updated timestamp (in milliseconds since epoch).
object
string
Annotation kind. Must be one of:
comment or suggestion. This is the source of truth for the suggestion classification; agent-produced findings should set suggestion. Defaults to comment when omitted.object
Proposed-change payload for
type: "suggestion" annotations. Persisted verbatim so reviewers (and your app’s accept handler) can round-trip the target and the old/new values. Ignored when type is not suggestion. See Suggestions for the full frontend lifecycle.The schema is open: any additional custom fields you include are stored as-is alongside the fields below. status is server-owned: any caller-supplied value is dropped and the server stamps pending at create time (and accepted / rejected on the corresponding lifecycle action).Show properties
Show properties
string
Stable ID of the thing being changed (for example, the record or field ID the suggestion applies to). Your accept handler uses this to locate what to update.
string
Kind of target the suggestion applies to (for example,
custom, text, or a value your app defines).any
The value at the time the suggestion was created. Can be any JSON-serializable value.
any
The proposed new value. Can be any JSON-serializable value. Your app writes this into its own state or backend when the suggestion is accepted.
string | null
Optional human-readable summary of the change (for example,
"row.123: 205 → 305").boolean
Set to
true when the live target value at accept time differs from oldValue. Informational; it does not block the accept.string
Caller-driven comment classification. Must be one of:
manual or chart. Defaults to manual when omitted.The legacy value
commentType: "suggestion" is still accepted and preserved for backward compatibility, but it no longer drives the suggestion classification. Use the annotation-level type: "suggestion" field instead.object
Controls who can see the annotation. Discriminated on
type. When omitted, the annotation defaults to public.Show properties
Show properties
string
required
Visibility type. Must be one of:
public, organizationPrivate, or restricted.public: Visible to everyone.organizationPrivate: Visible only to users in the specified organization. RequiresorganizationId.restricted: Visible only to the specified users (private comment). RequiresuserIds.
string
Organization ID whose users can see the annotation. Required when
type is organizationPrivate.string[]
User IDs allowed to see the annotation. Required (non-empty) when
type is restricted.CommentAction[]
Per-row default action chips, inherited by every comment on the annotation that doesn’t set its own
commentData[].actions. Capped at 20 entries. See CommentAction for the full shape.Example Requests
Add comment annotation by organizationId, documentId and location
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"commentAnnotations": [
{
"location": {
"id": "yourLocationId",
"locationName": "yourLocationName"
},
"targetElement": {
"elementId": "yourElementId",
"targetText": "Your Target Text",
"occurrence": 1,
"selectAllContent": false
},
"commentData": [
{
"commentText": "Sample Comment",
"commentHtml": "<div>Sample Comment</div>",
"from": {
"userId": "yourUserId",
"name": "yourUserName",
"email": "yourUserEmail",
}
}
]
}
]
}
}
Add comment annotation with user tagging
{
"data": {
"organizationId": "acme-corp",
"documentId": "design-mockup-v2",
"commentAnnotations": [
{
"commentData": [
{
"triggerNotification": true,
"commentText": "Hey {{user_sarah_chen}}, can you review this color scheme? I think we should use a darker shade for better contrast.",
"commentHtml": "<p>Hey {{user_sarah_chen}}, can you review this color scheme? I think we should use a darker shade for better contrast.</p>",
"from": {
"userId": "user_john_smith",
"name": "John Smith",
"email": "john.smith@acme-corp.com"
},
"taggedUserContacts": [
{
"userId": "user_sarah_chen",
"contact": {
"userId": "user_sarah_chen",
"name": "Sarah Chen",
"email": "sarah.chen@acme-corp.com"
}
}
]
}
]
}
]
}
}
{{user_sarah_chen}} in the commentText will be replaced with “Sarah Chen” on the frontend, displaying as “Hey Sarah Chen, can you review this color scheme? I think we should use a darker shade for better contrast.”
Add comment annotation with permission verification
{
"data": {
"organizationId": "acme-corp",
"documentId": "design-mockup-v2",
"verifyUserPermissions": true,
"commentAnnotations": [
{
"commentData": [
{
"commentText": "Please review this section",
"from": {
"userId": "user_john_smith",
"name": "John Smith",
"email": "john.smith@acme-corp.com"
}
}
]
}
]
}
}
When
verifyUserPermissions is enabled, the API verifies the user has access to the document before creating the comment annotation. If verification fails, the request will be rejected.Add comment annotation with activity tracking
{
"data": {
"organizationId": "acme-corp",
"documentId": "design-mockup-v2",
"commentAnnotations": [
{
"commentData": [
{
"commentText": "This needs review",
"triggerNotification": true,
"triggerActivities": true,
"from": {
"userId": "user-1",
"email": "user@example.com",
"name": "User Name"
}
}
]
}
]
}
}
Add a content-less progress comment with action chips
Create a comment with no text andprogress.state: "active" to reserve a spot for a running task. Push step updates with subsequent Update Comments calls on the same commentId, then finish by writing the real content with state: "completed". actions renders customer-defined chips; Velt performs no write of its own when one is clicked.
{
"data": {
"organizationId": "acme-corp",
"documentId": "design-mockup-v2",
"commentAnnotations": [
{
"commentData": [
{
"isCommentTextAvailable": false,
"progress": {
"state": "active",
"steps": [
{ "label": "Fetching data", "state": "active" }
]
},
"actions": [
{ "id": "approve", "label": "Approve" }
],
"from": {
"userId": "agent-1",
"name": "Review Agent"
}
}
]
}
]
}
}
Add comment annotation with access context
{
"data": {
"organizationId": "acme-corp",
"documentId": "analytics-dashboard",
"commentAnnotations": [
{
"context": {
"access": {
"entityId": "numberOfVisitors",
"dashboardId": "myDashboard"
}
},
"commentData": [
{
"commentText": "Traffic numbers look unusual today",
"from": {
"userId": "user_john_smith",
"name": "John Smith",
"email": "john.smith@acme-corp.com"
}
}
]
}
]
}
}
Add an agent suggestion (finding)
Settype: "suggestion" and attach an agent block to the root comment (commentData[0]). The server generates the annotation-level agent block and stamps sourceType: "agent".
{
"data": {
"organizationId": "acme-corp",
"documentId": "design-mockup-v2",
"commentAnnotations": [
{
"type": "suggestion",
"commentData": [
{
"commentText": "Heading has a spelling mistake: 'Welcom' should be 'Welcome'.",
"from": {
"userId": "spell-check",
"name": "Spell Check Agent"
},
"agent": {
"agentSource": "velt",
"agentId": "spell-check",
"executionId": "exec_123",
"url": "https://example.com/design-mockup-v2",
"reason": {
"title": "Spelling error",
"description": "The word 'Welcom' is misspelled.",
"severity": "low",
"findingType": "text",
"confidence": 98,
"suggestedFix": "Welcome",
"source": "instructions"
}
}
}
]
}
]
}
}
agentSource: "external" and supply your own agentName and agentId (executionId is optional):
{
"data": {
"organizationId": "acme-corp",
"documentId": "design-mockup-v2",
"commentAnnotations": [
{
"type": "suggestion",
"commentData": [
{
"commentText": "This button has insufficient color contrast.",
"from": {
"userId": "a11y-bot"
},
"agent": {
"agentSource": "external",
"agentName": "Accessibility Bot",
"agentId": "a11y-bot",
"reason": {
"title": "Low color contrast",
"description": "Contrast ratio is 2.1:1, below the 4.5:1 WCAG AA threshold.",
"severity": "high",
"findingType": "pin"
}
}
}
]
}
]
}
}
Add a suggestion with a proposed-change payload
Settype: "suggestion" and attach a suggestion object describing what should change. The server persists the payload verbatim and stamps suggestion.status: "pending"; any caller-supplied status is dropped. Additional custom fields inside suggestion are stored as-is.
{
"data": {
"organizationId": "acme-corp",
"documentId": "design-mockup-v2",
"commentAnnotations": [
{
"type": "suggestion",
"suggestion": {
"targetId": "row.123",
"targetType": "custom",
"oldValue": { "x": 205 },
"newValue": { "x": 305 },
"summary": "row.123: 205 → 305",
"driftDetected": false,
"myCustomField": "kept as-is"
},
"commentData": [
{
"commentText": "Bump x from 205 to 305 to match the spec.",
"from": {
"userId": "user_sarah_chen",
"name": "Sarah Chen"
}
}
]
}
]
}
}
Add a private (restricted) comment annotation
Usevisibility to limit who can see the annotation.
{
"data": {
"organizationId": "acme-corp",
"documentId": "design-mockup-v2",
"commentAnnotations": [
{
"visibility": {
"type": "restricted",
"userIds": ["user_sarah_chen", "user_john_smith"]
},
"commentData": [
{
"commentText": "Internal note: don't ship this section yet.",
"from": {
"userId": "user_john_smith",
"name": "John Smith",
"email": "john.smith@acme-corp.com"
}
}
]
}
]
}
}
Response
data is a map of results, keyed per annotation, not an array.
Success Response
{
"result": {
"status": "success",
"message": "Comment Annotation(s) added successfully.",
"data": {
"-O0mpUziLcBwzREvZKs6": {
"success": true,
"annotationId": "-O0mpUziLcBwzREvZKs6",
"commentIds": [
126535
],
"message": "Added Successfully"
}
}
}
}
Result fields
boolean
Outcome for this annotation. The envelope reports
success only when every entry succeeded and no user was permission denied.string
The annotation ID.
annotationId is optional on input, so the server generates one when you do not supply it.number[]
IDs of the comments created inside this annotation.
string
Success message, or the reason this annotation failed.
string
Agent annotations only. Echoes back
commentData[0].agent.reason.findingId exactly as you sent it. The field is omitted for non-agent annotations.Correlating results back to your own records
Readentry.annotationId from each result, never the map key.
The server generates annotationId, and results are written into the map as each write completes, so the map order does not match the order you submitted. For agent annotations, findingId is the reliable way to match a created annotation back to the record it came from.
Entries for annotations rejected by permission checks are recorded before an ID exists. When you did not supply an annotationId for one of those, its key falls back to __velt_denied:<index>, where <index> is its position in the commentAnnotations array you sent, and the entry has no annotationId field to read. That key is reserved: annotation IDs cannot contain a colon, so it never collides with one of yours.
Failure Response
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
details. Entries marked "success": true inside details were created, so treat a failed request as a partial write and read details instead of assuming nothing was saved.
{
"error": {
"message": "ERROR_MESSAGE",
"status": "PERMISSION_DENIED",
"details": {
"-O0mpUziLcBwzREvZKs6": {
"success": true,
"annotationId": "-O0mpUziLcBwzREvZKs6",
"commentIds": [
126535
],
"message": "Added Successfully"
},
"deniedAnnotation-1": {
"success": false,
"message": "ERROR_MESSAGE"
}
}
}
}
{
"result": {
"status": "success",
"message": "Comment Annotation(s) added successfully.",
"data": {
"-O0mpUziLcBwzREvZKs6": {
"success": true,
"annotationId": "-O0mpUziLcBwzREvZKs6",
"commentIds": [
126535
],
"message": "Added Successfully"
}
}
}
}
Was this page helpful?