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,
        "progress": {},
        "actions": [
          {}
        ],
        "triggerNotification": 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.

progress · CommentProgress

Turns this comment into a live progress row while progress.state is active. See CommentProgress for the full shape. steps is capped at 100 entries.

actions · CommentAction[]

Customer-defined action chips rendered on this comment row. Overrides the annotation-level actions default for this row. Capped at 20 entries. See CommentAction for the full shape.

triggerNotification · boolean

When enabled, this reply triggers exactly one notification through the same funnel as a new comment. Defaults to false and is never persisted onto the comment.

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

​

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

​

5. Add a reply with a progress row and action chips

{
  "data": {
    "organizationId": "yourOrganizationId",
    "documentId": "yourDocumentId",
    "annotationId": "yourAnnotationId",
    "commentData": [
      {
        "isCommentTextAvailable": false,
        "progress": {
          "state": "active",
          "steps": [
            { "label": "Fetching data", "state": "active" }
          ]
        },
        "actions": [
          { "id": "approve", "label": "Approve" }
        ],
        "from": {
          "userId": "agent-1"
        }
      }
    ]
  }
}

​

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