# Notifications & Events

**Page:** api/notifications

[Download Raw Markdown](./api/notifications.md)

---

{/* AUTO-GENERATED — Do not edit manually. Regenerate with: npm run docs:api:generate */}



# Notifications & Events

The Notifications & Events API provides access to platform-level event history and user-facing notifications. Use these endpoints to query audit logs, retrieve aggregated event statistics, manage user notifications, and clean up old event records.

## Events

### `GET /api/v1/events`

Query event history with filtering, pagination, and sorting. Maximum 500 events per page.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `limit` | query | integer | No | Number of events to return (max 500). Default: `100` |
| `offset` | query | integer | No | Number of events to skip. Default: `0` |
| `sort_by` | query | string | No | Field to sort by. Allowed: `created_at`, `event_type`. Default: `"created_at"` |
| `sort_order` | query | string | No | Sort direction. Allowed: `asc`, `desc`. Default: `"desc"` |
| `event_type` | query | string | No | Filter by specific event type |
| `resource_type` | query | string | No | Filter by resource type |
| `resource_id` | query | string | No | Filter by specific resource ID |
| `project_id` | query | string | No | Filter by project ID |
| `container_id` | query | string | No | Filter by container ID |
| `start_date` | query | string | No | Filter events after this timestamp |
| `end_date` | query | string | No | Filter events before this timestamp |
| `realm_id` | query | string | No | Filter by realm ID |

#### SDK Usage

```ts
const stream = client.api.events.listIterator({
  limit: 100,
  sort_by: "created_at",
  sort_order: "desc",
});

for await (const event of stream) {
  console.log(event.event_type);
}
```

#### Response



```json
{
  "statusCode": 200,
  "message": "Events retrieved successfully",
  "data": {
    "events": [
      {
        "id": "507f1f77bcf86cd799439044",
        "event_type": "container.running",
        "resource_type": "container",
        "resource_id": "507f1f77bcf86cd799439033",
        "user_id": "507f1f77bcf86cd799439011",
        "payload": {
          "container": {
            "id": "507f1f77bcf86cd799439033",
            "name": "web-app-1",
            "status": "running",
            "project_id": "507f1f77bcf86cd799439022"
          }
        },
        "realm_ids": ["507f1f77bcf86cd799439022"],
        "created_at": "2025-01-15T10:30:05.123Z"
      }
    ],
    "pagination": {
      "total": 1523,
      "limit": 100,
      "offset": 0,
      "has_more": true
    }
  }
}
```


```json
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid date range: start_date cannot be after end_date"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `VALIDATION_ERROR` | Invalid input parameters | One or more request parameters failed validation | Check the error message for specific field requirements and correct your input |
| `INVALID_PARAMETER_VALUE` | Invalid parameter value | A parameter value is outside the allowed range or format | Ensure parameter values meet the documented constraints (min/max, format, regex) |
| `INVALID_DATE_RANGE` | Invalid date range | The start_date cannot be after the end_date | Ensure the start_date is before or the same as the end_date |


```json
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication token required"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `MISSING_TOKEN` | Authentication token missing | No authentication token was provided in the request | Include a valid JWT token in the Authorization header as `Bearer <token>` |
| `INVALID_TOKEN` | Invalid authentication token | The provided authentication token is malformed or invalid | Obtain a new token by logging in again or using a valid auth token |
| `TOKEN_EXPIRED` | Authentication token expired | The provided authentication token has expired | Obtain a new token by logging in again or refreshing your session |



### `GET /api/v1/events/{id}`

Retrieve detailed information about a specific event.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `id` | path | string | Yes | Event ID |

#### SDK Usage

```ts
const event = await client.api.events.get({
  id: "507f1f77bcf86cd799439044",
});
```

#### Response



```json
{
  "statusCode": 200,
  "message": "Event retrieved successfully",
  "data": {
    "id": "507f1f77bcf86cd799439044",
    "event_type": "container.running",
    "resource_type": "container",
    "resource_id": "507f1f77bcf86cd799439033",
    "user_id": "507f1f77bcf86cd799439011",
    "payload": {
      "container": {
        "id": "507f1f77bcf86cd799439033",
        "name": "web-app-1",
        "status": "running",
        "project_id": "507f1f77bcf86cd799439022"
      }
    },
    "realm_ids": ["507f1f77bcf86cd799439022"],
    "created_at": "2025-01-15T10:30:05.123Z"
  }
}
```


```json
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid ID format"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `INVALID_ID_FORMAT` | Invalid ID format | The provided ID must be a 24-character hexadecimal string | Ensure the ID is exactly 24 characters long and contains only hexadecimal characters (0-9, a-f) |


```json
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication token required"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `MISSING_TOKEN` | Authentication token missing | No authentication token was provided in the request | Include a valid JWT token in the Authorization header as `Bearer <token>` |
| `INVALID_TOKEN` | Invalid authentication token | The provided authentication token is malformed or invalid | Obtain a new token by logging in again or using a valid auth token |
| `TOKEN_EXPIRED` | Authentication token expired | The provided authentication token has expired | Obtain a new token by logging in again or refreshing your session |


```json
{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Event not found"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `EVENT_NOT_FOUND` | Event not found | The requested event does not exist or has been deleted | Verify the event ID is correct and that you have access to this event |



### `GET /api/v1/events/stats`

Get aggregated statistics about event history.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `start_date` | query | string | No | Start of time range |
| `end_date` | query | string | No | End of time range |
| `realm_id` | query | string | No | Filter by realm |

#### SDK Usage

```ts
const stats = await client.api.events.getStats({
  start_date: "2025-01-01T00:00:00.000Z",
  end_date: "2025-01-31T23:59:59.999Z",
});
```

#### Response



```json
{
  "statusCode": 200,
  "message": "Event statistics retrieved successfully",
  "data": {
    "total_events": 15234,
    "by_type": {
      "container.running": 3456,
      "container.stopped": 2134,
      "storage.share.mount_changed": 1523,
      "notification.read": 8121
    },
    "by_resource": {
      "container": 8765,
      "storage_share": 2456,
      "notification": 4013
    },
    "oldest_event": "2024-11-15T10:30:00.000Z",
    "newest_event": "2025-01-15T10:30:00.000Z"
  }
}
```


```json
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid date range: start_date cannot be after end_date"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `INVALID_DATE_RANGE` | Invalid date range | The start_date cannot be after the end_date | Ensure the start_date is before or the same as the end_date |


```json
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication token required"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `MISSING_TOKEN` | Authentication token missing | No authentication token was provided in the request | Include a valid JWT token in the Authorization header as `Bearer <token>` |
| `INVALID_TOKEN` | Invalid authentication token | The provided authentication token is malformed or invalid | Obtain a new token by logging in again or using a valid auth token |
| `TOKEN_EXPIRED` | Authentication token expired | The provided authentication token has expired | Obtain a new token by logging in again or refreshing your session |



### `POST /api/v1/events/cleanup`

Delete events older than the specified retention period. Admin access required.

#### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `retention_days` | integer | Yes | Delete events older than this many days (min: 1, max: 365) |

```json
{
  "retention_days": 30
}
```

#### SDK Usage

```ts
const result = await client.api.events.cleanup({
  retention_days: 30,
});
```

#### Response



```json
{
  "statusCode": 200,
  "message": "Old events cleaned up successfully",
  "data": {
    "deleted_count": 5432,
    "retention_days": 30,
    "cutoff_date": "2024-12-15T10:30:00.000Z"
  }
}
```


```json
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Validation failed"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `VALIDATION_ERROR` | Invalid input parameters | One or more request parameters failed validation | Check the error message for specific field requirements and correct your input |


```json
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication token required"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `MISSING_TOKEN` | Authentication token missing | No authentication token was provided in the request | Include a valid JWT token in the Authorization header as `Bearer <token>` |
| `INVALID_TOKEN` | Invalid authentication token | The provided authentication token is malformed or invalid | Obtain a new token by logging in again or using a valid auth token |
| `TOKEN_EXPIRED` | Authentication token expired | The provided authentication token has expired | Obtain a new token by logging in again or refreshing your session |


```json
{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Admin access required"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `ADMIN_ONLY` | Admin access required | This endpoint is only accessible to admin users | Contact an administrator if you need access to this functionality |
| `ACCOUNT_BANNED` | Account banned | Your account has been banned and cannot access this resource | Contact support for information about your account status |



### `DELETE /api/v1/events`

Delete multiple events at once based on filters.

#### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `event_type` | string | No | Delete all events of this type |
| `resource_type` | string | No | Delete all events for this resource type |
| `resource_id` | string | No | Delete all events for this resource |
| `before_date` | string | No | Delete events before this date |
| `realm_id` | string | No | Delete events in this realm |

```json
{
  "resource_type": "container",
  "before_date": "2024-12-15T00:00:00.000Z"
}
```

#### SDK Usage

```ts
const result = await client.api.events.bulkDelete({
  resource_id: "507f1f77bcf86cd799439033",
});
```

#### Response



```json
{
  "statusCode": 200,
  "message": "Events deleted successfully",
  "data": {
    "deleted_count": 1523
  }
}
```


```json
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Either filters or `all=true` must be provided for bulk delete"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `VALIDATION_ERROR` | Invalid input parameters | One or more request parameters failed validation | Check the error message for specific field requirements and correct your input |
| `INVALID_BULK_DELETE_PARAMS` | Invalid bulk delete parameters | You must provide at least one filter when performing a bulk delete, or set `all=true` to delete all events. | Provide one or more filters (e.g., resource_type, event_type) or use all=true to confirm deletion of all events. |


```json
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication token required"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `MISSING_TOKEN` | Authentication token missing | No authentication token was provided in the request | Include a valid JWT token in the Authorization header as `Bearer <token>` |
| `INVALID_TOKEN` | Invalid authentication token | The provided authentication token is malformed or invalid | Obtain a new token by logging in again or using a valid auth token |
| `TOKEN_EXPIRED` | Authentication token expired | The provided authentication token has expired | Obtain a new token by logging in again or refreshing your session |



### `DELETE /api/v1/events/{id}`

Permanently delete an event from history.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `id` | path | string | Yes | Event ID to delete |

#### SDK Usage

```ts
await client.api.events.delete({
  id: "507f1f77bcf86cd799439044",
});
```

#### Response



```json
{
  "statusCode": 200,
  "message": "Event deleted successfully"
}
```


```json
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid ID format"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `INVALID_ID_FORMAT` | Invalid ID format | The provided ID must be a 24-character hexadecimal string | Ensure the ID is exactly 24 characters long and contains only hexadecimal characters (0-9, a-f) |


```json
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication token required"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `MISSING_TOKEN` | Authentication token missing | No authentication token was provided in the request | Include a valid JWT token in the Authorization header as `Bearer <token>` |
| `INVALID_TOKEN` | Invalid authentication token | The provided authentication token is malformed or invalid | Obtain a new token by logging in again or using a valid auth token |
| `TOKEN_EXPIRED` | Authentication token expired | The provided authentication token has expired | Obtain a new token by logging in again or refreshing your session |


```json
{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Insufficient permissions"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `INSUFFICIENT_PERMISSIONS` | Insufficient permissions | You do not have the required permissions to perform this action | Contact the resource owner or administrator to request access |
| `ACCOUNT_BANNED` | Account banned | Your account has been banned and cannot access this resource | Contact support for information about your account status |


```json
{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Event not found"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `EVENT_NOT_FOUND` | Event not found | The requested event does not exist or has been deleted | Verify the event ID is correct and that you have access to this event |



## Notifications

### `GET /api/v1/notifications/`

Get all notifications for the authenticated user, including global notifications and notifications targeted to the user.

This endpoint takes no parameters.

#### SDK Usage

```ts
const stream = client.api.notifications.listIterator();

for await (const notification of stream) {
  console.log(notification.title);
}
```

#### Response



```json
{
  "statusCode": 200,
  "message": "Notifications retrieved successfully",
  "data": [
    {
      "id": "507f1f77bcf86cd799439030",
      "title": "System Maintenance Notice",
      "message": "Scheduled maintenance will occur on January 25th at 2:00 AM UTC.",
      "type": "MAINTENANCE",
      "severity": "WARNING",
      "is_public": true,
      "is_global": true,
      "target_user_ids": null,
      "expires_at": "2025-01-26T00:00:00.000Z",
      "created_at": "2025-01-20T10:00:00.000Z",
      "updated_at": "2025-01-20T10:00:00.000Z",
      "is_read": false,
      "read_at": null
    }
  ]
}
```


```json
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication required"
}
```


```json
{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "An unexpected error occurred"
}
```



### `GET /api/v1/notifications/public`

Get all public notifications. No authentication required.

This endpoint takes no parameters.

#### SDK Usage

```ts
const stream = client.api.notifications.listPublicIterator();

for await (const notification of stream) {
  console.log(notification.title);
}
```

#### Response



```json
{
  "statusCode": 200,
  "message": "Public notifications retrieved successfully",
  "data": [
    {
      "id": "507f1f77bcf86cd799439030",
      "title": "System Maintenance Notice",
      "message": "Scheduled maintenance will occur on January 25th at 2:00 AM UTC.",
      "type": "MAINTENANCE",
      "severity": "WARNING",
      "is_public": true,
      "is_global": true,
      "target_user_ids": null,
      "expires_at": "2025-01-26T00:00:00.000Z",
      "created_at": "2025-01-20T10:00:00.000Z",
      "updated_at": "2025-01-20T10:00:00.000Z"
    }
  ]
}
```


```json
{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "An unexpected error occurred"
}
```



### `PATCH /api/v1/notifications/{id}/read`

Mark a notification as read for the authenticated user.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `id` | path | string | Yes | Unique identifier of the notification to mark as read |

#### SDK Usage

```ts
const result = await client.api.notifications.markRead({
  id: "507f1f77bcf86cd799439030",
});
```

#### Response



```json
{
  "statusCode": 200,
  "message": "Notification marked as read",
  "data": {
    "id": "507f1f77bcf86cd799439150",
    "notification_id": "507f1f77bcf86cd799439030",
    "is_read": true,
    "read_at": "2025-01-21T21:30:00.000Z"
  }
}
```


```json
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid notification ID"
}
```


```json
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication required"
}
```


```json
{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "You do not have access to this notification"
}
```


```json
{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Notification not found"
}
```


```json
{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "An unexpected error occurred"
}
```



### `PATCH /api/v1/notifications/read-all`

Mark all notifications as read for the authenticated user.

This endpoint takes no parameters.

#### SDK Usage

```ts
const result = await client.api.notifications.markAllRead();
```

#### Response



```json
{
  "statusCode": 200,
  "message": "All notifications marked as read",
  "data": {
    "count": 5
  }
}
```


```json
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication required"
}
```


```json
{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "An unexpected error occurred"
}
```




Event types cover a wide range of platform activity including container lifecycle (`container.running`, `container.stopped`), proxy and firewall changes, pool membership events, and user account actions. Use the `event_type` filter combined with `resource_type` to narrow down results when investigating specific activity.