Add Comments

POST /v2/commentannotations/comments/add

Add Comments

cURL

curl --request POST \
  --url https://api.velt.dev/v2/commentannotations/comments/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>",
    "createOrganization": true,
    "documentId": "<string>",
    "createDocument": true,
    "annotationId": "<string>",
    "verifyUserPermissions": true,
    "commentData": [
      {
        "commentId": 123,
        "commentText": "<string>",
        "commentHtml": "<string>",
        "context": {},
        "isCommentResolverUsed": true,
        "isCommentTextAvailable": true,
        "from": {},
        "createdAt": 123,
        "lastUpdated": 123,
        "taggedUserContacts": [
          {
            "text": "<string>",
            "userId": "<string>",
            "contact": {
              "email": "<string>",
              "name": "<string>",
              "userId": "<string>"
            }
          }
        ],
        "attachments": [
          {
            "attachmentId": 123,
            "name": "<string>",
            "bucketPath": "<string>",
            "size": 123,
            "type": "<string>",
            "url": "<string>",
            "thumbnail": "<string>",
            "mimeType": "<string>",
            "metadata": {}
          }
        ],
        "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>"
          }
        }
      }
    ]
  }
}
'

import requests

url = "https://api.velt.dev/v2/commentannotations/comments/add"

payload = { "data": {
        "organizationId": "<string>",
        "createOrganization": True,
        "documentId": "<string>",
        "createDocument": True,
        "annotationId": "<string>",
        "verifyUserPermissions": True,
        "commentData": [
            {
                "commentId": 123,
                "commentText": "<string>",
                "commentHtml": "<string>",
                "context": {},
                "isCommentResolverUsed": True,
                "isCommentTextAvailable": True,
                "from": {},
                "createdAt": 123,
                "lastUpdated": 123,
                "taggedUserContacts": [
                    {
                        "text": "<string>",
                        "userId": "<string>",
                        "contact": {
                            "email": "<string>",
                            "name": "<string>",
                            "userId": "<string>"
                        }
                    }
                ],
                "attachments": [
                    {
                        "attachmentId": 123,
                        "name": "<string>",
                        "bucketPath": "<string>",
                        "size": 123,
                        "type": "<string>",
                        "url": "<string>",
                        "thumbnail": "<string>",
                        "mimeType": "<string>",
                        "metadata": {}
                    }
                ],
                "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>"
                    }
                }
            }
        ]
    } }
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>',
      createOrganization: true,
      documentId: '<string>',
      createDocument: true,
      annotationId: '<string>',
      verifyUserPermissions: true,
      commentData: [
        {
          commentId: 123,
          commentText: '<string>',
          commentHtml: '<string>',
          context: {},
          isCommentResolverUsed: true,
          isCommentTextAvailable: true,
          from: {},
          createdAt: 123,
          lastUpdated: 123,
          taggedUserContacts: [
            {
              text: '<string>',
              userId: '<string>',
              contact: {email: '<string>', name: '<string>', userId: '<string>'}
            }
          ],
          attachments: [
            {
              attachmentId: 123,
              name: '<string>',
              bucketPath: '<string>',
              size: 123,
              type: '<string>',
              url: '<string>',
              thumbnail: '<string>',
              mimeType: '<string>',
              metadata: {}
            }
          ],
          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>'
            }
          }
        }
      ]
    }
  })
};

fetch('https://api.velt.dev/v2/commentannotations/comments/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/comments/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>',
        'createOrganization' => true,
        'documentId' => '<string>',
        'createDocument' => true,
        'annotationId' => '<string>',
        'verifyUserPermissions' => true,
        'commentData' => [
                [
                                'commentId' => 123,
                                'commentText' => '<string>',
                                'commentHtml' => '<string>',
                                'context' => [
                                                                
                                ],
                                'isCommentResolverUsed' => true,
                                'isCommentTextAvailable' => true,
                                'from' => [
                                                                
                                ],
                                'createdAt' => 123,
                                'lastUpdated' => 123,
                                'taggedUserContacts' => [
                                                                [
                                                                                                                                'text' => '<string>',
                                                                                                                                'userId' => '<string>',
                                                                                                                                'contact' => [
                                                                                                                                                                                                                                                                'email' => '<string>',
                                                                                                                                                                                                                                                                'name' => '<string>',
                                                                                                                                                                                                                                                                'userId' => '<string>'
                                                                                                                                ]
                                                                ]
                                ],
                                'attachments' => [
                                                                [
                                                                                                                                'attachmentId' => 123,
                                                                                                                                'name' => '<string>',
                                                                                                                                'bucketPath' => '<string>',
                                                                                                                                'size' => 123,
                                                                                                                                'type' => '<string>',
                                                                                                                                'url' => '<string>',
                                                                                                                                'thumbnail' => '<string>',
                                                                                                                                'mimeType' => '<string>',
                                                                                                                                'metadata' => [
                                                                                                                                                                                                                                                                
                                                                                                                                ]
                                                                ]
                                ],
                                '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>'
                                                                ]
                                ]
                ]
        ]
    ]
  ]),
  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/comments/add"

	payload := strings.NewReader("{\n  \"data\": {\n    \"organizationId\": \"<string>\",\n    \"createOrganization\": true,\n    \"documentId\": \"<string>\",\n    \"createDocument\": true,\n    \"annotationId\": \"<string>\",\n    \"verifyUserPermissions\": true,\n    \"commentData\": [\n      {\n        \"commentId\": 123,\n        \"commentText\": \"<string>\",\n        \"commentHtml\": \"<string>\",\n        \"context\": {},\n        \"isCommentResolverUsed\": true,\n        \"isCommentTextAvailable\": true,\n        \"from\": {},\n        \"createdAt\": 123,\n        \"lastUpdated\": 123,\n        \"taggedUserContacts\": [\n          {\n            \"text\": \"<string>\",\n            \"userId\": \"<string>\",\n            \"contact\": {\n              \"email\": \"<string>\",\n              \"name\": \"<string>\",\n              \"userId\": \"<string>\"\n            }\n          }\n        ],\n        \"attachments\": [\n          {\n            \"attachmentId\": 123,\n            \"name\": \"<string>\",\n            \"bucketPath\": \"<string>\",\n            \"size\": 123,\n            \"type\": \"<string>\",\n            \"url\": \"<string>\",\n            \"thumbnail\": \"<string>\",\n            \"mimeType\": \"<string>\",\n            \"metadata\": {}\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  }\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/comments/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    \"createOrganization\": true,\n    \"documentId\": \"<string>\",\n    \"createDocument\": true,\n    \"annotationId\": \"<string>\",\n    \"verifyUserPermissions\": true,\n    \"commentData\": [\n      {\n        \"commentId\": 123,\n        \"commentText\": \"<string>\",\n        \"commentHtml\": \"<string>\",\n        \"context\": {},\n        \"isCommentResolverUsed\": true,\n        \"isCommentTextAvailable\": true,\n        \"from\": {},\n        \"createdAt\": 123,\n        \"lastUpdated\": 123,\n        \"taggedUserContacts\": [\n          {\n            \"text\": \"<string>\",\n            \"userId\": \"<string>\",\n            \"contact\": {\n              \"email\": \"<string>\",\n              \"name\": \"<string>\",\n              \"userId\": \"<string>\"\n            }\n          }\n        ],\n        \"attachments\": [\n          {\n            \"attachmentId\": 123,\n            \"name\": \"<string>\",\n            \"bucketPath\": \"<string>\",\n            \"size\": 123,\n            \"type\": \"<string>\",\n            \"url\": \"<string>\",\n            \"thumbnail\": \"<string>\",\n            \"mimeType\": \"<string>\",\n            \"metadata\": {}\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  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.velt.dev/v2/commentannotations/comments/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    \"createOrganization\": true,\n    \"documentId\": \"<string>\",\n    \"createDocument\": true,\n    \"annotationId\": \"<string>\",\n    \"verifyUserPermissions\": true,\n    \"commentData\": [\n      {\n        \"commentId\": 123,\n        \"commentText\": \"<string>\",\n        \"commentHtml\": \"<string>\",\n        \"context\": {},\n        \"isCommentResolverUsed\": true,\n        \"isCommentTextAvailable\": true,\n        \"from\": {},\n        \"createdAt\": 123,\n        \"lastUpdated\": 123,\n        \"taggedUserContacts\": [\n          {\n            \"text\": \"<string>\",\n            \"userId\": \"<string>\",\n            \"contact\": {\n              \"email\": \"<string>\",\n              \"name\": \"<string>\",\n              \"userId\": \"<string>\"\n            }\n          }\n        ],\n        \"attachments\": [\n          {\n            \"attachmentId\": 123,\n            \"name\": \"<string>\",\n            \"bucketPath\": \"<string>\",\n            \"size\": 123,\n            \"type\": \"<string>\",\n            \"url\": \"<string>\",\n            \"thumbnail\": \"<string>\",\n            \"mimeType\": \"<string>\",\n            \"metadata\": {}\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  }\n}"

response = http.request(request)
puts response.read_body

{
  "result": {
    "status": "success",
    "message": "Comment(s) added successfully.",
    "data": [
      778115
    ]
  }
}

Use this API to add comments within a specific CommentAnnotation.

Endpoint

POST https://api.velt.dev/v2/commentannotations/comments/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

createOrganization · boolean

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

documentId · string · required

Document ID

createDocument · boolean

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

annotationId · string · required

Comment Annotation ID

verifyUserPermissions · boolean

When enabled, verifies the user has access to the document before adding comments. This ensures comments respect document access permissions configured via Access Control or Permission Provider.

Default: false

commentData · Comment[] · 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

commentHtml · string

Comment content in HTML string

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.

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

Show properties

text · string · required

Display text of the tagged user (e.g. “@Username”)

userId · string · required

User ID of the tagged user

contact · object · required

Show properties

email · string · required

Email of the tagged user

name · string · required

Name of the tagged user

userId · string · required

User ID of the tagged user

attachments · object[]

Array of attachments to include with the comment. See Attachment for full schema details.

Show properties

attachmentId · number · required

Unique identifier for the attachment

name · string

File name of the attachment

bucketPath · string

Path to the file in storage bucket

size · number

File size in bytes

type · string

File type (e.g., “image”, “video”, “document”)

url · string

Download URL of the attachment

thumbnail · string

Thumbnail URL of the attachment

mimeType · string

MIME type of the attachment (e.g., “image/png”, “video/mp4”)

metadata · object

Custom metadata for the attachment (e.g., dimensions, timestamps, etc.)

agent · object

Marks this comment as an agent-authored reply. V2 only. When set, the server stamps sourceType: "agent" on the comment. Discriminated on agentSource.

Show properties

agentSource · string · required

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

agentId · string

Agent ID. Required when agentSource is velt (a built-in agent like spell-check, or a custom agent ID that is verified server-side). Optional and opaque (never validated) when agentSource is external.

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.

Example Requests

This endpoint adds comments (including agent replies) to an existing CommentAnnotation. Annotation-level fields such as type (comment / suggestion) and visibility are set when the annotation is created or updated via the Add Comment Annotations and Update Comment Annotations APIs — they are not accepted on this endpoint.

1. Add comment in a CommentAnnotation by organizationId, documentId, and annotationId

{
  "data": {
    "organizationId": "yourOrganizationId",
    "documentId": "yourDocumentId",
    "annotationId": "yourAnnotationId",
    "commentData": [
      {
        "commentText": "Sample Comment",
        "commentHtml": "<div>Hello</div>",
        "from": {
          "userId": "yourUserId"
        }
      }
    ]
  }
}

2. Add comment with permission verification

{
  "data": {
    "organizationId": "yourOrganizationId",
    "documentId": "yourDocumentId",
    "annotationId": "yourAnnotationId",
    "verifyUserPermissions": true,
    "commentData": [
      {
        "commentText": "Sample Comment",
        "commentHtml": "<div>Hello</div>",
        "from": {
          "userId": "yourUserId"
        }
      }
    ]
  }
}

When verifyUserPermissions is enabled, the API verifies the user has access to the document before adding the comment. If verification fails, the request will be rejected.

3. Add comment with attachments

{
  "data": {
    "organizationId": "yourOrganizationId",
    "createOrganization": true,
    "documentId": "yourDocumentId",
    "createDocument": true,
    "annotationId": "yourAnnotationId",
    "commentData": [
      {
        "commentId": 123,
        "commentText": "Please review this screenshot",
        "commentHtml": "<div>Please review this screenshot</div>",
        "context": {},
        "attachments": [
          {
            "attachmentId": 100001,
            "name": "screenshot.png",
            "bucketPath": "attachments/org-123/doc-456/screenshot.png",
            "size": 1024000,
            "type": "image",
            "url": "https://storage.googleapis.com/bucket/screenshot.png",
            "thumbnail": "https://storage.googleapis.com/bucket/screenshot_thumb.png",
            "mimeType": "image/png",
            "metadata": {
              "width": 1920,
              "height": 1080,
              "uploadedAt": 1696118400000
            }
          }
        ],
        "from": {
          "userId": "yourUserId"
        }
      }
    ]
  }
}

4. Add an agent reply

Attach an agent block to mark the comment as agent-authored. The server stamps sourceType: "agent" on the comment.

{
  "data": {
    "organizationId": "yourOrganizationId",
    "documentId": "yourDocumentId",
    "annotationId": "yourAnnotationId",
    "commentData": [
      {
        "commentText": "I fixed the spelling. Please re-review.",
        "from": {
          "userId": "spell-check",
          "name": "Spell Check Agent"
        },
        "agent": {
          "agentSource": "velt",
          "agentId": "spell-check",
          "executionId": "exec_124",
          "reason": {
            "title": "Spelling corrected",
            "description": "Updated 'Welcom' to 'Welcome'.",
            "severity": "info",
            "findingType": "text"
          }
        }
      }
    ]
  }
}

Response

Success Response

{
  "result": {
    "status": "success",
    "message": "Comment(s) added successfully.",
    "data": [
      778115
    ]
  }
}

Failure Response

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

{
  "result": {
    "status": "success",
    "message": "Comment(s) added successfully.",
    "data": [
      778115
    ]
  }
}