Add Activity Logs

POST /v2/activities/add

Add Activity Logs

cURL

curl --request POST \
  --url https://api.velt.dev/v2/activities/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>",
    "activities": [
      {
        "id": "<string>",
        "featureType": "<string>",
        "actionType": "<string>",
        "actionUser": {},
        "targetEntityId": "<string>",
        "targetSubEntityId": "<string>",
        "changes": {},
        "entityData": "<any>",
        "entityTargetData": "<any>",
        "displayMessageTemplate": "<string>",
        "displayMessageTemplateData": {},
        "actionIcon": "<string>",
        "isActivityResolverUsed": true
      }
    ]
  }
}
'

{
  "result": {
    "status": "success",
    "message": "Activity(s) added successfully.",
    "data": {
      "success": true,
      "message": "Activity(s) added successfully."
    }
  }
}

Use this API to create activity log records for a document within an organization.

Adding activity logs via the REST API requires activityServiceConfig to be enabled at the workspace level in the Velt Console.

Endpoint

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

activities · object[] · required

Array of activity log objects to create.

Show properties

id · string

Optional Firestore document ID for the activity record. Use this to control the ID for idempotent writes — if an activity with this ID already exists it will be overwritten.

featureType · string · required

Feature that generated the activity log. Must be one of: "comment", "reaction", "recorder", "crdt", "custom".

actionType · string · required

Specific action performed (e.g., "comment.add").

actionUser · User · required

User who performed the action.

targetEntityId · string

ID of the primary entity the activity log targets (e.g., annotation ID). Required when featureType is "custom"; optional for all other feature types.

targetSubEntityId · string

ID of a sub-entity within the target (e.g., a specific comment ID).

changes · object

Map of field names to { from, to } objects describing what changed.

entityData · any

Snapshot of the entity at the time of the action.

entityTargetData · any

Snapshot of the target entity at the time of the action.

displayMessageTemplate · string

Message template string. Use {{variable}} syntax for dynamic values.

displayMessageTemplateData · object

Key-value data to populate displayMessageTemplate variables.

actionIcon · string

URL or identifier for the icon representing this action.

isActivityResolverUsed · boolean

Use this for self-hosting activity data. Set to true if you are using the activity resolver data provider in the SDK. When true, indicates that PII has been stripped from the activity record and the record is pending resolver re-hydration.

Example Requests

Add a single activity log (non-custom featureType, targetEntityId optional)

{
  "data": {
    "organizationId": "org-123",
    "documentId": "doc-456",
    "activities": [
      {
        "featureType": "comment",
        "actionType": "comment.add",
        "actionUser": {
          "userId": "user-1",
          "email": "[e-mail]",
          "name": "User Name"
        },
        "displayMessageTemplate": "{{user}} added a comment"
      }
    ]
  }
}

Add an activity log with a custom ID (idempotent write)

{
  "data": {
    "organizationId": "org-123",
    "documentId": "doc-456",
    "activities": [
      {
        "id": "my-custom-activity-id",
        "featureType": "comment",
        "actionType": "comment.add",
        "actionUser": {
          "userId": "user-1",
          "email": "[e-mail]",
          "name": "User Name"
        },
        "targetEntityId": "annotation-789",
        "displayMessageTemplate": "{{user}} added a comment"
      }
    ]
  }
}

Add a custom featureType activity (targetEntityId required)

{
  "data": {
    "organizationId": "org-123",
    "documentId": "doc-456",
    "activities": [
      {
        "featureType": "custom",
        "actionType": "statusChanged",
        "actionUser": {
          "userId": "user-1",
          "email": "[e-mail]",
          "name": "User Name"
        },
        "targetEntityId": "entity-456",
        "displayMessageTemplate": "{{user}} changed the status"
      }
    ]
  }
}

Add an activity log with changes and template data

{
  "data": {
    "organizationId": "org-123",
    "documentId": "doc-456",
    "activities": [
      {
        "featureType": "comment",
        "actionType": "comment.update",
        "actionUser": {
          "userId": "user-1",
          "email": "[e-mail]",
          "name": "User Name"
        },
        "targetEntityId": "annotation-789",
        "targetSubEntityId": "comment-001",
        "changes": {
          "commentText": {
            "from": "Original text",
            "to": "Updated text"
          }
        },
        "displayMessageTemplate": "{{user}} updated a comment",
        "displayMessageTemplateData": {
          "user": {
            "userId": "user-1",
            "name": "User Name"
          }
        }
      }
    ]
  }
}

Response

Success Response

{
  "result": {
    "status": "success",
    "message": "Activity(s) added successfully.",
    "data": {
      "success": true,
      "message": "Activity(s) added successfully."
    }
  }
}

Failure Response

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

{
  "result": {
    "status": "success",
    "message": "Activity(s) added successfully.",
    "data": {
      "success": true,
      "message": "Activity(s) added successfully."
    }
  }
}