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

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

Example Requests

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

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