The Hoody Notification Server is a lightweight service that delivers desktop notifications to a target Linux display by invoking notify-send directly on the host. It is purpose-built for local, single-host notification delivery and is intentionally minimal in scope.

When to use this service

Use the Notification Server when you need to push a desktop notification to a specific DISPLAY running on the same machine as the service. It is appropriate for system alerts, background task completion, CI signals, and other event-driven desktop messages. It is not a multi-channel notification platform — there is no email, in-app, push, SMS, or webhook channel. There are no templates, no user-preference or quiet-hours management, no priority filtering, and no configurable retry or backoff policy.

Capabilities

The API exposes a small, focused set of endpoints:

• Send a desktop notification — POST /api/v1/notifications/notify runs notify-send synchronously on the target display.
• Fetch notification history — GET /api/v1/notifications/{display} returns historical notifications for a display, including whether each has been dismissed. This is the only “fetch” model available; there is no per-notification delivery-status endpoint and no pending / delivered / failed state tracking.
• Dismiss and clear dismissed — POST and DELETE /api/v1/notifications/dismiss manage dismiss state.
• Real-time updates — GET /api/v1/notifications/stream provides a server-sent stream of notification updates.
• Icon assets — GET /api/v1/notifications/icons/{iconId} serves notification icon images.
• Operational endpoints — GET /api/v1/notifications/health and GET /api/v1/notifications/metrics provide health checks and metrics.

Note

The stream endpoint is the only mechanism for receiving asynchronous notification updates. There is no acknowledgment callback, no webhook for delivery confirmation, and no persistent delivery-state machine.

Rate limits

The only documented throttling is per-IP rate limiting, applied uniformly across all endpoints:

Scope	Limit
General API	60 requests per minute
notify endpoint	10 requests per minute
icons endpoint	100 requests per minute

Exceeding a limit returns an HTTP 429 response. There is no client-configurable retry or backoff — clients should respect the rate-limit response and retry after a sensible delay.

Next steps

The remaining pages in this section document each endpoint in detail, including request parameters, request bodies, response schemas, and SDK usage examples.