Notifications & Events

The Notifications & Events API surfaces two related streams of activity on the Hoody platform. Notifications are user-facing messages (maintenance windows, announcements, status updates) targeted at specific users or broadcast globally. Events are an immutable audit log of platform actions — container lifecycle changes, firewall edits, proxy permission updates, and similar — used for observability, compliance, and integration tooling.

Use these endpoints to list, inspect, and manage both streams. Most operations require authentication; the public notifications endpoint is the only one that does not.

Note

The event log is bounded: paginate using limit (max 500) and offset, and use the cleanup or bulk-delete endpoints to prune old entries. The mark-read endpoints use HTTP PUT, despite the operation identifiers ending in Patch.

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 (see enum below)
resource_type	query	string	No	Filter by resource type (see enum below)
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

The event_type parameter accepts: 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.

The resource_type parameter accepts: container, storage_share, notification, project, server, firewall, proxy_alias, proxy_permissions, auth_token, pool, user, activity_log.

cURL

curl -G https://api.hoody.icu/api/v1/events \
  -H "Authorization: Bearer <token>" \
  --data-urlencode "limit=50" \
  --data-urlencode "event_type=container.running" \
  --data-urlencode "resource_type=container" \
  --data-urlencode "sort_by=created_at" \
  --data-urlencode "sort_order=desc"

SDK

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

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

cURL

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

SDK

await client.api.events.get('507f1f77bcf86cd799439044');

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, broken down by event type and resource type over an optional time range.

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

cURL

curl -G https://api.hoody.icu/api/v1/events/stats \
  -H "Authorization: Bearer <token>" \
  --data-urlencode "start_date=2025-01-01T00:00:00.000Z" \
  --data-urlencode "end_date=2025-01-31T23:59:59.999Z"

SDK

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

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 a specified retention period. Admin-only.

Request Body

Field	Type	Required	Description
retention_days	integer	Yes	Delete events older than this many days. Range: 1 to 365

cURL

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

SDK

await client.api.events.cleanup({ retention_days: 30 });

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

Request Body

Field	Type	Required	Description
event_type	string	No	Delete all events of this type (see event_type enum on the list endpoint)
resource_type	string	No	Delete all events for this resource type (see resource_type enum on the list endpoint)
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

cURL

curl -X DELETE https://api.hoody.icu/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

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

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 a single event from history.

Parameters

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

cURL

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

SDK

await client.api.events.delete('507f1f77bcf86cd799439044');

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 broadcasts and notifications targeted to that user. Returns per-user read state via is_read and read_at.

This endpoint takes no parameters.

cURL

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

SDK

await client.api.notifications.listIterator();

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": "Failed to retrieve notifications"
}

GET /api/v1/notifications/public

Get all public notifications. Does not require authentication, so is_read and read_at are not included in the response.

This endpoint takes no parameters.

cURL

curl https://api.hoody.icu/api/v1/notifications/public

SDK

await client.api.notifications.listPublicIterator();

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": "Failed to retrieve public notifications"
}

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

Mark a single 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

cURL

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

SDK

await client.api.notifications.markRead('507f1f77bcf86cd799439030');

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

403

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "You cannot mark this notification"
}

404

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

500

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Failed to mark notification as read"
}

PUT /api/v1/notifications/read-all

Mark every notification belonging to the authenticated user as read in a single call.

This endpoint takes no parameters.

cURL

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

SDK

await client.api.notifications.markAllRead();

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": "Failed to mark all notifications as read"
}