Hoody Notification Server API

The Hoody Notification Server delivers desktop notifications to a target display by synchronously invoking notify-send on the host. It is a thin, display-scoped service — every operation is tied to a specific display identifier, and every notification is rendered as a native OS toast via the host’s notification daemon.

Use this API when you need to:

• Trigger a desktop notification on a remote or headless display
• Retrieve the recent notification history for a display
• Dismiss active notifications or clear dismissed state
• Subscribe to a real-time stream of notification updates
• Serve icon images used by notification payloads
• Probe the service health and scrape metrics

Capabilities at a glance

Operation	Method	Path
Send a desktop notification	POST	/api/v1/notifications/notify
Fetch notification history for a display	GET	/api/v1/notifications/{display}
Dismiss a notification	POST	/api/v1/notifications/dismiss
Clear dismissed notifications	DELETE	/api/v1/notifications/dismiss
Stream notification updates	GET	/api/v1/notifications/stream
Serve an icon image	GET	/api/v1/notifications/icons/{iconId}
Health check	GET	/api/v1/notifications/health
Metrics	GET	/api/v1/notifications/metrics

Scope and limitations

The notification server has a deliberately narrow surface area. Understanding what it does not do is just as important as knowing what it does.

Note

The notification server only delivers desktop notifications via notify-send on the target display. It does not provide an email channel, an in-app channel, a push channel, or any multi-channel routing. There are no notification templates, no user-preference or quiet-hours management, no opt-out controls, and no priority-based filtering.

Specifically, the service does not expose:

• A per-notification delivery-status endpoint
• Pending, delivered, or failed state tracking
• Configurable retry or backoff policies
• Acknowledgment callbacks
• User-level subscription or preference management

The only documented rate-limit semantics are:

• 60 requests per minute for general traffic
• 10 requests per minute for the notify endpoint
• 100 requests per minute for icon requests

Exceeding these limits returns a standard rate-limit response. There is no retry-after header configuration beyond what the server returns by default, and no client-side backoff parameters to tune.

Notification lifecycle

Notifications follow a simple lifecycle: they are created by POST /api/v1/notifications/notify, appear in the history returned by GET /api/v1/notifications/{display}, and may be transitioned into a dismissed state via POST /api/v1/notifications/dismiss. The dismissed state can then be cleared with DELETE /api/v1/notifications/dismiss. The GET /api/v1/notifications/stream endpoint delivers a real-time feed of these transitions over a server-sent stream.

When to use this API

Reach for the notification server when you need OS-level desktop toasts that surface on a specific physical or virtual display — for example, alerting an operator at a kiosk, surfacing build results on a workstation, or piping events from a long-running task into a desktop environment. If your workflow requires multi-channel delivery, templated messages, or delivery receipts, those concerns live in a different service and must be handled before or after invoking this server.

Continue to the endpoint-specific pages for full request and response details, parameter tables, and SDK examples.