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

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

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

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

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

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