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

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

200

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

400

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

401

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

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

Response

200

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

400

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

401

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

404

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

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

Response

200

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

400

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

401

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

{
  "retention_days": 30
}

SDK Usage

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

Response

200

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

400

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

401

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

403

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

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

SDK Usage

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

Response

200

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

400

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

401

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

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

Response

200

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

400

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

401

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

403

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

404

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

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

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

Response

200

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

401

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

500

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

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

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

Response

200

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

500

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

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

Response

200

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

400

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

401

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

403

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

404

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

500

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

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

Response

200

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

401

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

500

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

Note

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.