> ## Documentation Index
> Fetch the complete documentation index at: https://velt.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Add Activity Logs

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

> [!NOTE]
>
> Adding activity logs via the REST API requires `activityServiceConfig` to be enabled at the workspace level in the [Velt Console](https://console.velt.dev).

# 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](https://velt.dev/docs/security/auth-tokens.md).

# Body

#### Params

**data** `object` *required*

**properties**

**organizationId** `string` *required*

Organization ID

**documentId** `string` *required*

Document ID

**activities** `object[]` *required*

Array of activity log objects to create.

**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)

```JSON theme={null}
{
  "data": {
    "organizationId": "org-123",
    "documentId": "doc-456",
    "activities": [
      {
        "featureType": "comment",
        "actionType": "comment.add",
        "actionUser": {
          "userId": "user-1",
          "email": "user@example.com",
          "name": "User Name"
        },
        "displayMessageTemplate": "{{user}} added a comment"
      }
    ]
  }
}
```

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

```JSON theme={null}
{
  "data": {
    "organizationId": "org-123",
    "documentId": "doc-456",
    "activities": [
      {
        "id": "my-custom-activity-id",
        "featureType": "comment",
        "actionType": "comment.add",
        "actionUser": {
          "userId": "user-1",
          "email": "user@example.com",
          "name": "User Name"
        },
        "targetEntityId": "annotation-789",
        "displayMessageTemplate": "{{user}} added a comment"
      }
    ]
  }
}
```

#### Add a custom featureType activity (targetEntityId required)

```JSON theme={null}
{
  "data": {
    "organizationId": "org-123",
    "documentId": "doc-456",
    "activities": [
      {
        "featureType": "custom",
        "actionType": "statusChanged",
        "actionUser": {
          "userId": "user-1",
          "email": "user@example.com",
          "name": "User Name"
        },
        "targetEntityId": "entity-456",
        "displayMessageTemplate": "{{user}} changed the status"
      }
    ]
  }
}
```

#### Add an activity log with changes and template data

```JSON theme={null}
{
  "data": {
    "organizationId": "org-123",
    "documentId": "doc-456",
    "activities": [
      {
        "featureType": "comment",
        "actionType": "comment.update",
        "actionUser": {
          "userId": "user-1",
          "email": "user@example.com",
          "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

```JSON theme={null}
{
  "result": {
    "status": "success",
    "message": "Activity(s) added successfully.",
    "data": {
      "success": true,
      "message": "Activity(s) added successfully."
    }
  }
}
```

#### Failure Response

```JSON theme={null}
{
  "error": {
    "message": "ERROR_MESSAGE",
    "status": "INVALID_ARGUMENT"
  }
}
```

```js theme={null}
{
  "result": {
    "status": "success",
    "message": "Activity(s) added successfully.",
    "data": {
      "success": true,
      "message": "Activity(s) added successfully."
    }
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.