Notifications & Events

List platform-level user notifications and query the full event audit log. The event history is append-only and paginated, with filtering by event type, resource type, and date range. Use the notification endpoints to surface user-facing banners (maintenance, announcements, status updates) and to track read state per user.

Note

All event and notification endpoints require authentication unless explicitly marked public. The maximum page size for event listings is 500 entries.

---

Authentication

All endpoints require a JWT token in the Authorization header:

Authorization: Bearer <token>

---

Events

GET /api/v1/events

Query event history with filtering, pagination, and sorting. Returns up to 500 events per page.

cURL

curl -X GET "https://api.hoody.com/api/v1/events?limit=50&event_type=container.running&sort_by=created_at&sort_order=desc" \
  -H "Authorization: Bearer <token>"

SDK

const events = await client.api.events.listIterator({
  limit: 50,
  event_type: "container.running",
  sort_by: "created_at",
  sort_order: "desc"
});

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. Default: "created_at". Allowed: created_at, event_type
sort_order	query	string	No	Sort direction. Default: "desc". Allowed: asc, 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

Allowed event_type values

container.creating, container.running, container.stopped, container.failed, container.deleting, auth.token.deleted, container.autostart_enabled, container.autostart_disabled, container.renamed, container.resource_updated, container.ssh_key.added, container.ssh_key.removed, container.snapshot.created, container.snapshot.deleted, container.snapshot.restored, container.snapshot.renamed, container.display.enabled, user.created, auth.token.updated, auth.token.enabled, auth.token.disabled, proxy.alias.expiring_soon, proxy.alias.expired, storage.share.mount_changed, notification.read, server.health_changed, server.rental_expiring, firewall.rule.added, firewall.rule.removed, firewall.rule.updated, firewall.rule.enabled, firewall.rule.disabled, proxy.permissions.default_changed, proxy.permissions.group_added, proxy.permissions.group_updated, proxy.permissions.group_removed, pool.member.joined, pool.member.left, pool.member.role_changed, pool.invited, pool.invitation_revoked, user.banned, user.unbanned, user.role_changed, activity.logged

Allowed resource_type values

container, storage_share, notification, project, server, firewall, proxy_alias, proxy_permissions, auth_token, pool, user, activity_log

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.

cURL

curl -X GET "https://api.hoody.com/api/v1/events/507f1f77bcf86cd799439044" \
  -H "Authorization: Bearer <token>"

SDK

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

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Event ID

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": "Token has expired"
}

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 within an optional date range and realm.

cURL

curl -X GET "https://api.hoody.com/api/v1/events/stats?start_date=2024-11-01T00:00:00.000Z&end_date=2025-01-15T23:59:59.999Z" \
  -H "Authorization: Bearer <token>"

SDK

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

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

Response

200

{
  "statusCode": 200,
  "message": "Event statistics retrieved successfully",
  "data": {
    "total_events": 15234,
    "by_type": {
      "container.running": 3456,
      "container.stopped": 2134,
      "storage.share.created": 1523,
      "notification.created": 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 only.

cURL

curl -X POST "https://api.hoody.com/api/v1/events/cleanup" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"retention_days": 30}'

SDK

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

Request Body

Field	Type	Required	Description
retention_days	integer	Yes	Delete events older than this many days. Min: 1, Max: 365

{
  "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": "Token has expired"
}

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. At least one filter must be supplied.

cURL

curl -X DELETE "https://api.hoody.com/api/v1/events" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"resource_type": "container", "before_date": "2024-12-15T00:00:00.000Z"}'

SDK

const result = await client.api.events.bulkDelete({
  data: {
    resource_type: "container",
    before_date: "2024-12-15T00:00:00.000Z"
  }
});

Request Body

Field	Type	Required	Description
event_type	string	No	Delete all events of this type. See allowed event types
resource_type	string	No	Delete all events for this resource type. See allowed resource types
resource_id	string	No	Delete all events for this resource (24-character hex ID)
before_date	string	No	Delete events before this date (ISO 8601)
realm_id	string	No	Delete events in this realm (24-character hex ID)

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

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.

cURL

curl -X DELETE "https://api.hoody.com/api/v1/events/507f1f77bcf86cd799439044" \
  -H "Authorization: Bearer <token>"

SDK

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

Parameters

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

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": "Token has expired"
}

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.

cURL

curl -X GET "https://api.hoody.com/api/v1/notifications/" \
  -H "Authorization: Bearer <token>"

SDK

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

This endpoint takes no parameters.

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 token 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.

cURL

curl -X GET "https://api.hoody.com/api/v1/notifications/public"

SDK

const publicNotifications = await client.api.notifications.listPublicIterator();

This endpoint takes no parameters.

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

---

PUT /api/v1/notifications/{id}/read

Mark a single notification as read for the authenticated user.

cURL

curl -X PUT "https://api.hoody.com/api/v1/notifications/507f1f77bcf86cd799439030/read" \
  -H "Authorization: Bearer <token>"

SDK

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

Parameters

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

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 ID format"
}

401

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

403

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

404

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

500

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

---

PUT /api/v1/notifications/read-all

Mark all notifications as read for the authenticated user.

cURL

curl -X PUT "https://api.hoody.com/api/v1/notifications/read-all" \
  -H "Authorization: Bearer <token>"

SDK

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

This endpoint takes no parameters.

Response

200

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

401

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

500

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

---

Notification Object

Field	Type	Description
id	string	Unique notification identifier
title	string	Notification title
message	string	Notification body
type	string	One of: MAINTENANCE, ANNOUNCEMENT, STATUS_UPDATE
severity	string	One of: INFO, WARNING, ERROR, SUCCESS
is_public	boolean	Whether the notification is visible without authentication
is_global	boolean	Whether the notification targets all users
target_user_ids	array | null	Specific user IDs targeted, or null for global
expires_at	string | null	ISO 8601 expiry timestamp, or null if never expires
created_at	string	ISO 8601 timestamp of creation
updated_at	string	ISO 8601 timestamp of last update
is_read	boolean	Whether the authenticated user has read this notification (user listing only)
read_at	string | null	ISO 8601 timestamp of when the notification was read (user listing only)

Event Object

Field	Type	Description
id	string	24-character hex event identifier
event_type	string	Type of event (see allowed event types)
resource_type	string	Type of resource (see allowed resource types)
resource_id	string	24-character hex resource ID
user_id	string	24-character hex ID of the user who owns or triggered the event
payload	object	Event-specific data, sanitized for security
realm_ids	array	Realm IDs this event belongs to
created_at	string	ISO 8601 timestamp of when the event occurred