Add Comments

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>"
          }
        }
      }
    ]
  }
}
'

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

POST

commentannotations

comments

add

Add Comments

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>"
          }
        }
      }
    ]
  }
}
'

{
  "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

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
    ]
  }
}

Get Comment Annotations Count Get Comments

⌘I

​Endpoint

​Headers

​Body

​Params

​Example Requests

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

​2. Add comment with permission verification

​3. Add comment with attachments

​4. Add an agent reply

​Response

​Success Response

​Failure Response

Endpoint

Headers

Body

Params

Example Requests

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

2. Add comment with permission verification

3. Add comment with attachments

4. Add an agent reply

Response

Success Response

Failure Response