Skip to content
Hoody.com

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.

NameInTypeRequiredDescription
limitqueryintegerNoNumber of events to return (max 500). Default: 100.
offsetqueryintegerNoNumber of events to skip. Default: 0.
sort_byquerystringNoField to sort by. Allowed values: "created_at", "event_type". Default: "created_at".
sort_orderquerystringNoSort direction. Allowed values: "asc", "desc". Default: "desc".
event_typequerystringNoFilter by specific event type. String enum (71 values, see response schema for the full list).
resource_typequerystringNoFilter by resource type. String enum: "container", "storage_share", "notification", "project", "server", "firewall", "proxy_alias", "proxy_permissions", "auth_token", "pool", "user", "activity_log".
resource_idquerystringNoFilter by specific resource ID.
project_idquerystringNoFilter by project ID.
container_idquerystringNoFilter by container ID.
start_datequerystringNoFilter events after this timestamp.
end_datequerystringNoFilter events before this timestamp.
realm_idquerystringNoFilter by realm ID.
Terminal window
curl -X GET 'https://api.hoody.com/api/v1/events?limit=50&event_type=container.running' \
-H "Authorization: Bearer $HOODY_TOKEN"

Retrieve detailed information about a specific event.

NameInTypeRequiredDescription
idpathstringYesEvent ID. Must be a 24-character hexadecimal string.
Terminal window
curl -X GET 'https://api.hoody.com/api/v1/events/507f1f77bcf86cd799439044' \
-H "Authorization: Bearer $HOODY_TOKEN"

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.

NameInTypeRequiredDescription
start_datequerystringNoStart of time range.
end_datequerystringNoEnd of time range.
realm_idquerystringNoFilter by realm.
Terminal window
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"

Delete events older than a specified retention period. Admin only.

NameTypeRequiredDescription
retention_daysintegerYesDelete events older than this many days. Minimum 1, maximum 365.
Terminal window
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}'

Bulk delete events by filter. At least one filter (or all=true) must be supplied, otherwise the request is refused.

NameTypeRequiredDescription
event_typestringNoDelete all events of this type. String enum (71 values, see response schema for the full list).
resource_typestringNoDelete 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_idstringNoDelete all events for this resource. Must be a 24-character hexadecimal string.
before_datestringNoDelete events before this date (RFC 3339 timestamp).
realm_idstringNoDelete events in this realm. Must be a 24-character hexadecimal string.
Terminal window
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"}'

Permanently delete a single event from history.

NameInTypeRequiredDescription
idpathstringYesEvent ID to delete. Must be a 24-character hexadecimal string.
Terminal window
curl -X DELETE 'https://api.hoody.com/api/v1/events/507f1f77bcf86cd799439044' \
-H "Authorization: Bearer $HOODY_TOKEN"

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.

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.

NameInTypeRequiredDescription
pagequeryintegerNoPage number (offset paging). Ignored when before is supplied. Default: 1.
limitqueryintegerNoRows per page (max 100). Default: 20.
unread_onlyquerybooleanNoReturn only notifications the user has not read. Mutually exclusive with read_only. Default: false.
read_onlyquerybooleanNoReturn 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.
beforequerystringNoKeyset 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.
Terminal window
curl -X GET 'https://api.hoody.com/api/v1/notifications/?unread_only=true&limit=20' \
-H "Authorization: Bearer $HOODY_TOKEN"

Get all public notifications. No authentication required — use this when a token cannot read the inbox.

This endpoint takes no parameters.

Terminal window
curl -X GET 'https://api.hoody.com/api/v1/notifications/public'

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.

Terminal window
curl -X GET 'https://api.hoody.com/api/v1/notifications/summary' \
-H "Authorization: Bearer $HOODY_TOKEN"

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.

NameInTypeRequiredDescription
idpathstringYesUnique identifier of the notification to mark as read. Must be a 24-character hexadecimal string.
Terminal window
# 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"

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.

Terminal window
# 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"