Add Comment Annotations

POST /v2/commentannotations/add

Add Comment Annotations

cURL

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,
            "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>",
        "commentType": "<string>",
        "visibility": {
          "type": "<string>",
          "organizationId": "<string>",
          "userIds": [
            "<string>"
          ]
        }
      }
    ]
  }
}
'

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,
                        "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>",
                "commentType": "<string>",
                "visibility": {
                    "type": "<string>",
                    "organizationId": "<string>",
                    "userIds": ["<string>"]
                }
            }
        ]
    } }
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,
              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>',
          commentType: '<string>',
          visibility: {type: '<string>', organizationId: '<string>', userIds: ['<string>']}
        }
      ]
    }
  })
};

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,
                                                                                                                                '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>',
                                'commentType' => '<string>',
                                'visibility' => [
                                                                'type' => '<string>',
                                                                'organizationId' => '<string>',
                                                                'userIds' => [
                                                                                                                                '<string>'
                                                                ]
                                ]
                ]
        ]
    ]
  ]),
  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            \"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        \"commentType\": \"<string>\",\n        \"visibility\": {\n          \"type\": \"<string>\",\n          \"organizationId\": \"<string>\",\n          \"userIds\": [\n            \"<string>\"\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            \"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        \"commentType\": \"<string>\",\n        \"visibility\": {\n          \"type\": \"<string>\",\n          \"organizationId\": \"<string>\",\n          \"userIds\": [\n            \"<string>\"\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            \"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        \"commentType\": \"<string>\",\n        \"visibility\": {\n          \"type\": \"<string>\",\n          \"organizationId\": \"<string>\",\n          \"userIds\": [\n            \"<string>\"\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.

• You can add comments on an elemement, 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

x-velt-api-key · string · required

Your API key.

x-velt-auth-token · string · required

Your Auth Token.

Body

Params

data · object · required

Show properties

organizationId · string · required

Organization ID

documentId · string · required

Document ID

createOrganization · boolean

If set to true, a new organization will be created (if it doesn’t exist) before the annotation is added.

createDocument · boolean

If set to true, a new document will be created (if it doesn’t exist) before the annotation is added.

verifyUserPermissions · 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: false

commentAnnotations · object[] · required

Show properties

annotationId · string

Custom Annotation ID. If not provided, Velt will generate a unique ID for the annotation.

location · object

Show properties

id · string · required

Location ID

locationName · string

Location Name

targetElement · object

Target Element

Show properties

elementId · string

Element DOM Id. When used with targetText, defines the text search boundaries for locating text comments within the specified element.

targetText · string

Target Text. Provide this if you want to add comment annotation on the provided text content.

occurrence · number

Occurrence. Provide this if you want to add comment annotation on a text content.

selectAllContent · boolean

Select All Content. Provide this if you want to select and add comment annotation on the entire text content of the target elementId.

commentData · object[] · required

Array of Comment Data

Show properties

commentId · number

Custom Comment ID. If not provided, Velt will generate a unique ID for the comment.

commentText · 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.

commentHtml · 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.

context · object

Custom key/value metadata object. This is used to store any additional information about the comment.

isCommentResolverUsed · boolean

Use this for self-hosting comments data. Set this as true if you are comments resolver data provider in the SDK.

isCommentTextAvailable · 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.

triggerNotification · 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.

triggerActivities · boolean

When enabled, adding comments via the REST API will create activity log records matching the SDK’s native activity log behavior. Default: false.

from · User · required

User object from whom the comment is added

createdAt · number

Created At timestamp (in milliseconds since epoch).

lastUpdated · number

Last Updated timestamp (in milliseconds since epoch).

taggedUserContacts · 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

userId · string · required

User ID of the tagged user. This should match the userId used in {{userId}} syntax within commentText or commentHtml.

contact · object · required

Contact information for the tagged user

Show properties

userId · string · required

User ID of the tagged user

name · string

Name of the tagged user

email · string

Email of the tagged user

agent · 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

agentSource · string · required

Origin of the agent. Must be one of: velt or external.

agentId · 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.

executionId · string

Execution / run ID for this agent invocation.

agentName · 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).

url · string

Page URL associated with the finding.

reason · object · required

Finding details produced by the agent. Additional custom fields are preserved.

Show properties

title · string · required

Short finding title.

description · string · required

Finding description.

severity · string · required

Severity of the finding. Must be one of: critical, high, medium, low, or info.

findingId · string

Unique identifier for the finding.

findingType · string

Type of finding. Must be one of: text, pin, or page.

issueType · string

Custom issue classification.

confidence · number

Confidence score for the finding. Integer between 0 and 100.

suggestion · string

Suggested change in plain text.

suggestedFix · string

Suggested fix for the finding.

htmlSnippet · string

Relevant HTML snippet for the finding.

htmlSelector · string

CSS/HTML selector pointing to the finding location.

source · string

Provenance of the rule that triggered the finding. Must be one of: instructions or knowledge.

knowledgeSection · string

Knowledge section that triggered the finding.

status · Status

Status

Show properties

id · string · required

Status ID

name · string · required

Status Name

type · string · required

Type. Must be one of: default, ongoing, or terminal.

color · string · required

Text and comment pin color

lightColor · string · required

Background color on the status indicator

svg · string

Raw SVG of the icon. Either svg or iconUrl is required.

iconUrl · string

Icon URL. Either svg or iconUrl is required.

assignedTo · User

User object to whom the comment is assigned

context · object

Custom key/value metadata object

createdAt · number

Created At timestamp (in milliseconds since epoch).

lastUpdated · number

Last Updated timestamp (in milliseconds since epoch).

priority · object

Priority

Show properties

id · string · required

Priority ID

color · string · required

Priority Color

name · string · required

Priority Name

lightColor · string · required

Priority Light Color

type · 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.

commentType · 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.

visibility · object

Controls who can see the annotation. Discriminated on type. When omitted, the annotation defaults to public.

Show properties

type · 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. Requires organizationId.
• restricted: Visible only to the specified users (private comment). Requires userIds.

organizationId · string

Organization ID whose users can see the annotation. Required when type is organizationPrivate.

userIds · string[]

User IDs allowed to see the annotation. Required (non-empty) when type is restricted.

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": "[e-mail]"
            },
            "taggedUserContacts": [
              {
                "userId": "user_sarah_chen",
                "contact": {
                  "userId": "user_sarah_chen",
                  "name": "Sarah Chen",
                  "email": "[e-mail]"
                }
              }
            ]
          }
        ]
      }
    ]
  }
}

In this example, {{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": "[e-mail]"
            }
          }
        ]
      }
    ]
  }
}

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": "[e-mail]",
              "name": "User Name"
            }
          }
        ]
      }
    ]
  }
}

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": "[e-mail]"
            }
          }
        ]
      }
    ]
  }
}

Add an agent suggestion (finding)

Set type: "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"
              }
            }
          }
        ]
      }
    ]
  }
}

To attach a finding from an agent run through your own framework, use 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 private (restricted) comment annotation

Use visibility 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": "[e-mail]"
            }
          }
        ]
      }
    ]
  }
}

Response

Success Response

{
   "result": {
       "status": "success",
       "message": "Comment Annotation(s) added successfully.",
       "data": {
           "-O0mpUziLcBwzREvZKs6": {
               "success": true,
               "annotationId": "-O0mpUziLcBwzREvZKs6",
               "commentIds": [
                   126535
               ],
               "message": "Added Successfully"
           }
       }
   }
}

Failure Response

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

{
   "result": {
       "status": "success",
       "message": "Comment Annotation(s) added successfully.",
       "data": {
           "-O0mpUziLcBwzREvZKs6": {
               "success": true,
               "annotationId": "-O0mpUziLcBwzREvZKs6",
               "commentIds": [
                   126535
               ],
               "message": "Added Successfully"
           }
       }
   }
}