Use these endpoints to inspect the platform event history and the user-facing notification inbox. Events are an append-only audit log of every state-changing action across Hoody; notifications are the curated subset shown to a user (account-security, billing, infrastructure announcements). Read endpoints differ in what they require — see the credential rules in the Notifications section before choosing.
The event log covers containers, storage, notifications, projects, servers, firewall rules, proxy aliases/permissions, auth tokens, pools, users and activity entries. Use the list endpoint for dashboards and integrations; use the stats endpoint for aggregations; use the cleanup and delete endpoints for retention management.
Query event history with filtering, pagination, and sorting. Maximum 500 events per page.
Name In Type Required Description limitquery integer No Number of events to return (max 500). Default: 100. offsetquery integer No Number of events to skip. Default: 0. sort_byquery string No Field to sort by. Allowed values: "created_at", "event_type". Default: "created_at". sort_orderquery string No Sort direction. Allowed values: "asc", "desc". Default: "desc". event_typequery string No Filter by specific event type. String enum (71 values, see response schema for the full list). resource_typequery string No Filter by resource type. String enum: "container", "storage_share", "notification", "project", "server", "firewall", "proxy_alias", "proxy_permissions", "auth_token", "pool", "user", "activity_log". resource_idquery string No Filter by specific resource ID. project_idquery string No Filter by project ID. container_idquery string No Filter by container ID. start_datequery string No Filter events after this timestamp. end_datequery string No Filter events before this timestamp. realm_idquery string No Filter by realm ID.
curl -X GET ' https://api.hoody.com/api/v1/events?limit=50&event_type=container.running ' \
-H " Authorization: Bearer $HOODY_TOKEN "
import { HoodyClient } from ' hoody-sdk ' ;
const client = new HoodyClient ({ baseURL : ' https://api.hoody.com ' , token : process . env . HOODY_TOKEN });
await client . api . events . listIterator ({ limit : 50 , event_type : ' container.running ' });
" message " : " Events retrieved successfully " ,
" id " : " 507f1f77bcf86cd799439044 " ,
" event_type " : " container.running " ,
" resource_type " : " container " ,
" resource_id " : " 507f1f77bcf86cd799439033 " ,
" user_id " : " 507f1f77bcf86cd799439011 " ,
" realm_ids " : [ " 507f1f77bcf86cd799439022 " ],
" created_at " : " 2025-01-15T10:30:05.123Z "
" message " : " Invalid date range: start_date cannot be after end_date "
Error Code Title Description Resolution VALIDATION_ERRORInvalid input parameters One or more request parameters failed validation Check the error message for specific field requirements and correct your input INVALID_PARAMETER_VALUEInvalid 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_RANGEInvalid date range The start_date cannot be after the end_date Ensure the start_date is before or the same as the end_date
" message " : " Authentication token required "
Error Code Title Description Resolution MISSING_TOKENAuthentication token missing No authentication token was provided in the request Include a valid JWT token in the Authorization header as Bearer <token> INVALID_TOKENInvalid 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_EXPIREDAuthentication token expired The provided authentication token has expired Obtain a new token by logging in again or refreshing your session
Retrieve detailed information about a specific event.
Name In Type Required Description idpath string Yes Event ID. Must be a 24-character hexadecimal string.
curl -X GET ' https://api.hoody.com/api/v1/events/507f1f77bcf86cd799439044 ' \
-H " Authorization: Bearer $HOODY_TOKEN "
import { HoodyClient } from ' hoody-sdk ' ;
const client = new HoodyClient ({ baseURL : ' https://api.hoody.com ' , token : process . env . HOODY_TOKEN });
await client . api . events . get ( ' 507f1f77bcf86cd799439044 ' );
" message " : " Event retrieved successfully " ,
" id " : " 507f1f77bcf86cd799439044 " ,
" event_type " : " container.running " ,
" resource_type " : " container " ,
" resource_id " : " 507f1f77bcf86cd799439033 " ,
" user_id " : " 507f1f77bcf86cd799439011 " ,
" realm_ids " : [ " 507f1f77bcf86cd799439022 " ],
" created_at " : " 2025-01-15T10:30:05.123Z "
" message " : " Invalid ID format "
Error Code Title Description Resolution INVALID_ID_FORMATInvalid 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)
" message " : " Authentication token required "
Error Code Title Description Resolution MISSING_TOKENAuthentication token missing No authentication token was provided in the request Include a valid JWT token in the Authorization header as Bearer <token> INVALID_TOKENInvalid 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_EXPIREDAuthentication token expired The provided authentication token has expired Obtain a new token by logging in again or refreshing your session
" message " : " Event not found "
Error Code Title Description Resolution EVENT_NOT_FOUNDEvent 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 aggregated statistics about event history. Returns counts grouped by event type and resource type, plus the oldest and newest event timestamps in the time range.
Name In Type Required Description start_datequery string No Start of time range. end_datequery string No End of time range. realm_idquery string No Filter by realm.
curl -X GET ' https://api.hoody.com/api/v1/events/stats?start_date=2025-01-01T00:00:00.000Z&end_date=2025-01-31T23:59:59.000Z ' \
-H " Authorization: Bearer $HOODY_TOKEN "
import { HoodyClient } from ' hoody-sdk ' ;
const client = new HoodyClient ({ baseURL : ' https://api.hoody.com ' , token : process . env . HOODY_TOKEN });
await client . api . events . getStats ({
start_date : ' 2025-01-01T00:00:00.000Z ' ,
end_date : ' 2025-01-31T23:59:59.000Z '
" message " : " Event statistics retrieved successfully " ,
" container.running " : 3456 ,
" container.stopped " : 2134 ,
" storage.share.created " : 1523 ,
" notification.created " : 8121
" oldest_event " : " 2024-11-15T10:30:00.000Z " ,
" newest_event " : " 2025-01-15T10:30:00.000Z "
" message " : " Invalid date range: start_date cannot be after end_date "
Error Code Title Description Resolution INVALID_DATE_RANGEInvalid date range The start_date cannot be after the end_date Ensure the start_date is before or the same as the end_date
" message " : " Authentication token required "
Error Code Title Description Resolution MISSING_TOKENAuthentication token missing No authentication token was provided in the request Include a valid JWT token in the Authorization header as Bearer <token> INVALID_TOKENInvalid 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_EXPIREDAuthentication token expired The provided authentication token has expired Obtain a new token by logging in again or refreshing your session
Delete events older than a specified retention period. Admin only.
Name Type Required Description retention_daysinteger Yes Delete events older than this many days. Minimum 1, maximum 365.
curl -X POST ' https://api.hoody.com/api/v1/events/cleanup ' \
-H " Authorization: Bearer $HOODY_TOKEN " \
-H " Content-Type: application/json " \
-d ' {"retention_days": 30} '
import { HoodyClient } from ' hoody-sdk ' ;
const client = new HoodyClient ({ baseURL : ' https://api.hoody.com ' , token : process . env . HOODY_TOKEN });
await client . api . events . cleanup ({ retention_days : 30 });
" message " : " Old events cleaned up successfully " ,
" cutoff_date " : " 2024-12-15T10:30:00.000Z "
" message " : " Validation failed "
Error Code Title Description Resolution VALIDATION_ERRORInvalid input parameters One or more request parameters failed validation Check the error message for specific field requirements and correct your input
" message " : " Authentication token required "
Error Code Title Description Resolution MISSING_TOKENAuthentication token missing No authentication token was provided in the request Include a valid JWT token in the Authorization header as Bearer <token> INVALID_TOKENInvalid 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_EXPIREDAuthentication token expired The provided authentication token has expired Obtain a new token by logging in again or refreshing your session
" message " : " Admin access required "
Error Code Title Description Resolution ADMIN_ONLYAdmin access required This endpoint is only accessible to admin users Contact an administrator if you need access to this functionality ACCOUNT_BANNEDAccount banned Your account has been banned and cannot access this resource Contact support for information about your account status
Bulk delete events by filter. At least one filter (or all=true) must be supplied, otherwise the request is refused.
Name Type Required Description event_typestring No Delete all events of this type. String enum (71 values, see response schema for the full list). resource_typestring No Delete all events for this resource type. String enum: "container", "storage_share", "notification", "project", "server", "firewall", "proxy_alias", "proxy_permissions", "auth_token", "pool", "user", "activity_log". resource_idstring No Delete all events for this resource. Must be a 24-character hexadecimal string. before_datestring No Delete events before this date (RFC 3339 timestamp). realm_idstring No Delete events in this realm. Must be a 24-character hexadecimal string.
curl -X DELETE ' https://api.hoody.com/api/v1/events ' \
-H " Authorization: Bearer $HOODY_TOKEN " \
-H " Content-Type: application/json " \
-d ' {"resource_type": "container", "before_date": "2024-12-15T00:00:00.000Z"} '
import { HoodyClient } from ' hoody-sdk ' ;
const client = new HoodyClient ({ baseURL : ' https://api.hoody.com ' , token : process . env . HOODY_TOKEN });
await client . api . events . bulkDelete ({
resource_type : ' container ' ,
before_date : ' 2024-12-15T00:00:00.000Z '
" message " : " Events deleted successfully " ,
" message " : " Either filters or `all=true` must be provided for bulk delete "
Error Code Title Description Resolution VALIDATION_ERRORInvalid input parameters One or more request parameters failed validation Check the error message for specific field requirements and correct your input INVALID_BULK_DELETE_PARAMSInvalid 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.
" message " : " Authentication token required "
Error Code Title Description Resolution MISSING_TOKENAuthentication token missing No authentication token was provided in the request Include a valid JWT token in the Authorization header as Bearer <token> INVALID_TOKENInvalid 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_EXPIREDAuthentication token expired The provided authentication token has expired Obtain a new token by logging in again or refreshing your session
Permanently delete a single event from history.
Name In Type Required Description idpath string Yes Event ID to delete. Must be a 24-character hexadecimal string.
curl -X DELETE ' https://api.hoody.com/api/v1/events/507f1f77bcf86cd799439044 ' \
-H " Authorization: Bearer $HOODY_TOKEN "
import { HoodyClient } from ' hoody-sdk ' ;
const client = new HoodyClient ({ baseURL : ' https://api.hoody.com ' , token : process . env . HOODY_TOKEN });
await client . api . events . delete ( ' 507f1f77bcf86cd799439044 ' );
" message " : " Event deleted successfully "
" message " : " Invalid ID format "
Error Code Title Description Resolution INVALID_ID_FORMATInvalid 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)
" message " : " Authentication token required "
Error Code Title Description Resolution MISSING_TOKENAuthentication token missing No authentication token was provided in the request Include a valid JWT token in the Authorization header as Bearer <token> INVALID_TOKENInvalid 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_EXPIREDAuthentication token expired The provided authentication token has expired Obtain a new token by logging in again or refreshing your session
" message " : " Insufficient permissions "
Error Code Title Description Resolution INSUFFICIENT_PERMISSIONSInsufficient permissions You do not have the required permissions to perform this action Contact the resource owner or administrator to request access ACCOUNT_BANNEDAccount banned Your account has been banned and cannot access this resource Contact support for information about your account status
" message " : " Event not found "
Error Code Title Description Resolution EVENT_NOT_FOUNDEvent 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
The notifications endpoints expose the recipient-facing inbox plus a public, unauthenticated view. Notification bodies carry account-security, billing and infrastructure events, so they are not freely readable by delegated credentials.
Caution
The two mark-read endpoints (PUT /api/v1/notifications/{id}/read and PUT /api/v1/notifications/read-all) refuse every auth token, whatever permissions it carries, along with HTTP Basic, admin impersonation and realm-scoped sessions. They require a first-party account login (JWT). They are not present in the table for ordinary authenticated calls — a cURL example using an API token will return 403.
Paginated list of the notifications visible to the authenticated user (global notifications plus those targeted to them), newest first. Results are paginated — page 1 is not the complete set; follow pagination.next_cursor (or increment page) to read the rest.
Auth-token callers must hold the resources.read_account permission; tokens without it receive 403. JWT/account-login callers are unaffected.
Name In Type Required Description pagequery integer No Page number (offset paging). Ignored when before is supplied. Default: 1. limitquery integer No Rows per page (max 100). Default: 20. unread_onlyquery boolean No Return only notifications the user has not read. Mutually exclusive with read_only. Default: false. read_onlyquery boolean No Return only notifications the user HAS read — the archive half of the inbox. pagination.total counts the same filtered set, so it can drive page numbers directly. Mutually exclusive with unread_only (sending both is a 400, not an empty page). Default: false. beforequery string No Keyset cursor from a previous response’s pagination.next_cursor (format <created_at>,<id>). Prefer this over page for an inbox: offset paging duplicates or skips rows when a new notification arrives mid-read.
curl -X GET ' https://api.hoody.com/api/v1/notifications/?unread_only=true&limit=20 ' \
-H " Authorization: Bearer $HOODY_TOKEN "
import { HoodyClient } from ' hoody-sdk ' ;
const client = new HoodyClient ({ baseURL : ' https://api.hoody.com ' , token : process . env . HOODY_TOKEN });
await client . api . notifications . listIterator ({ unread_only : true , limit : 20 });
" message " : " Notifications retrieved successfully " ,
" id " : " 507f1f77bcf86cd799439030 " ,
" title " : " System Maintenance Notice " ,
" message " : " Scheduled maintenance will occur on January 25th at 2:00 AM UTC. " ,
" expires_at " : " 2025-01-26T00:00:00.000Z " ,
" created_at " : " 2025-01-20T10:00:00.000Z " ,
" updated_at " : " 2025-01-20T10:00:00.000Z " ,
" next_cursor " : " 2025-01-20T10:00:00.000Z,507f1f77bcf86cd799439030 "
" message " : " unread_only and read_only cannot both be true "
" message " : " Authentication token required "
" message " : " Token lacks the resources.read_account permission "
" error " : " Too Many Requests " ,
" message " : " Rate limit exceeded "
" error " : " Internal Server Error " ,
" message " : " An unexpected error occurred "
Get all public notifications. No authentication required — use this when a token cannot read the inbox.
This endpoint takes no parameters.
curl -X GET ' https://api.hoody.com/api/v1/notifications/public '
import { HoodyClient } from ' hoody-sdk ' ;
const client = new HoodyClient ({ baseURL : ' https://api.hoody.com ' , token : process . env . HOODY_TOKEN });
await client . api . notifications . listPublicIterator ();
" message " : " Public notifications retrieved successfully " ,
" id " : " 507f1f77bcf86cd799439030 " ,
" title " : " System Maintenance Notice " ,
" message " : " Scheduled maintenance will occur on January 25th at 2:00 AM UTC. " ,
" expires_at " : " 2025-01-26T00:00:00.000Z " ,
" created_at " : " 2025-01-20T10:00:00.000Z " ,
" updated_at " : " 2025-01-20T10:00:00.000Z "
" error " : " Internal Server Error " ,
" message " : " An unexpected error occurred "
Lightweight polling endpoint: returns the unread count and the newest notification position without any notification bodies. Use this to detect new notifications; fetch the list only when something changed. The response includes a server-advertised poll_interval_seconds — clients should honour it rather than hardcoding an interval.
Auth-token callers must hold the resources.read_account permission; tokens without it receive 403. JWT/owner callers are unaffected.
This endpoint takes no parameters.
curl -X GET ' https://api.hoody.com/api/v1/notifications/summary ' \
-H " Authorization: Bearer $HOODY_TOKEN "
import { HoodyClient } from ' hoody-sdk ' ;
const client = new HoodyClient ({ baseURL : ' https://api.hoody.com ' , token : process . env . HOODY_TOKEN });
await client . api . notifications . getUserNotificationSummary ();
" message " : " Notification summary retrieved successfully " ,
" latest_id " : " 507f1f77bcf86cd799439030 " ,
" latest_created_at " : " 2025-01-20T10:00:00.000Z " ,
" poll_interval_seconds " : 300
" message " : " Authentication token required "
" message " : " Token lacks the resources.read_account permission "
" error " : " Too Many Requests " ,
" message " : " Rate limit exceeded "
" error " : " Internal Server Error " ,
" message " : " An unexpected error occurred "
Mark a notification as read. Requires a first-party account login (JWT): auth tokens, HTTP Basic, impersonation and realm-scoped sessions are refused, so a delegated or leaked credential cannot dismiss the account’s own security notices.
Name In Type Required Description idpath string Yes Unique identifier of the notification to mark as read. Must be a 24-character hexadecimal string.
# JWT must come from a first-party session login, NOT from an API token.
curl -X PUT ' https://api.hoody.com/api/v1/notifications/507f1f77bcf86cd799439030/read ' \
-H " Authorization: Bearer $JWT "
import { HoodyClient } from ' hoody-sdk ' ;
// The client must carry a first-party JWT, not an API token.
const client = new HoodyClient ({ baseURL : ' https://api.hoody.com ' , token : process . env . HOODY_JWT });
await client . api . notifications . markRead ( ' 507f1f77bcf86cd799439030 ' );
" message " : " Notification marked as read " ,
" id " : " 507f1f77bcf86cd799439150 " ,
" notification_id " : " 507f1f77bcf86cd799439030 " ,
" read_at " : " 2025-01-21T21:30:00.000Z "
" message " : " Invalid notification ID format "
" message " : " First-party account login required "
" message " : " This endpoint does not accept API tokens "
" message " : " Notification not found "
" error " : " Internal Server Error " ,
" message " : " An unexpected error occurred "
Mark all notifications as read. Requires a first-party account login (JWT) for the same reason as marking a single notification read.
This endpoint takes no parameters.
# JWT must come from a first-party session login, NOT from an API token.
curl -X PUT ' https://api.hoody.com/api/v1/notifications/read-all ' \
-H " Authorization: Bearer $JWT "
import { HoodyClient } from ' hoody-sdk ' ;
// The client must carry a first-party JWT, not an API token.
const client = new HoodyClient ({ baseURL : ' https://api.hoody.com ' , token : process . env . HOODY_JWT });
await client . api . notifications . markAllRead ();
" message " : " All notifications marked as read " ,
" message " : " First-party account login required "
" message " : " This endpoint does not accept API tokens "
" error " : " Internal Server Error " ,
" message " : " An unexpected error occurred "