> ## 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).
</Note>

# Endpoint

`POST https://api.velt.dev/v2/activities/add`

# Headers

<ParamField header="x-velt-api-key" type="string" required>
  Your API key.
</ParamField>

<ParamField header="x-velt-auth-token" type="string" required>
  Your [Auth Token](/security/auth-tokens).
</ParamField>

# Body

#### Params

<ParamField body="data" type="object" required>
  <Expandable title="properties">
    <ParamField body="organizationId" type="string" required>
      Organization ID
    </ParamField>

    <ParamField body="documentId" type="string" required>
      Document ID
    </ParamField>

    <ParamField body="activities" type="object[]" required>
      Array of activity log objects to create.

      <Expandable title="properties">
        <ParamField body="id" type="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.
        </ParamField>

        <ParamField body="featureType" type="string" required>
          Feature that generated the activity log. Must be one of: `"comment"`, `"reaction"`, `"recorder"`, `"crdt"`, `"custom"`.
        </ParamField>

        <ParamField body="actionType" type="string" required>
          Specific action performed (e.g., `"comment.add"`).
        </ParamField>

        <ParamField body="actionUser" type="User" required>
          User who performed the action.
        </ParamField>

        <ParamField body="targetEntityId" type="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.
        </ParamField>

        <ParamField body="targetSubEntityId" type="string">
          ID of a sub-entity within the target (e.g., a specific comment ID).
        </ParamField>

        <ParamField body="changes" type="object">
          Map of field names to `{ from, to }` objects describing what changed.
        </ParamField>

        <ParamField body="entityData" type="any">
          Snapshot of the entity at the time of the action.
        </ParamField>

        <ParamField body="entityTargetData" type="any">
          Snapshot of the target entity at the time of the action.
        </ParamField>

        <ParamField body="displayMessageTemplate" type="string">
          Message template string. Use `{{variable}}` syntax for dynamic values.
        </ParamField>

        <ParamField body="displayMessageTemplateData" type="object">
          Key-value data to populate `displayMessageTemplate` variables.
        </ParamField>

        <ParamField body="actionIcon" type="string">
          URL or identifier for the icon representing this action.
        </ParamField>

        <ParamField body="isActivityResolverUsed" type="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.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## **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"
  }
}
```

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