Notification Server

The Hoody Notification Server is a lightweight, display-scoped service that delivers desktop notifications to a single target display by invoking notify-send on the host. It runs as a kit service inside a Hoody project and is intended for surfacing short, transient alerts — process completion, build status, agent events, watchtower pings — directly to the user’s desktop session.

This page describes the service’s capabilities and the rate limits that govern it. Use it as a quick orientation before reading the individual endpoint reference pages.

Capabilities

The service exposes a small, focused surface:

• Trigger a desktop notification — synchronously runs notify-send on the target display. POST /api/v1/notifications/notify.
• Fetch notification history for a display — returns the historical notifications for a given display along with their dismiss state. This is the only fetch model exposed; there is no per-notification delivery-status endpoint and no pending / delivered / failed state tracking. GET /api/v1/notifications/{display}.
• Dismiss a notification and clear dismissed entries — POST and DELETE /api/v1/notifications/dismiss.
• Real-time stream of notification updates — a Server-Sent Events stream of notification lifecycle updates. GET /api/v1/notifications/stream.
• Serve notification icon images — resolves an icon id to its image asset. GET /api/v1/notifications/icons/{iconId}.
• Health and metrics — liveness and Prometheus-style metrics. GET /api/v1/notifications/health and GET /api/v1/notifications/metrics.

Note

The Notification Server is display-scoped, not user-scoped. Every endpoint targets a specific display rather than a Hoody account, and there is no concept of a recipient inbox.

What this service does NOT do

The Notification Server is intentionally narrow. It does not provide:

• An email channel, in-app channel, or mobile push channel. Notifications are delivered exclusively through notify-send to the host’s desktop session.
• Multi-channel routing or fan-out across channels.
• Notification templates, templating languages, or rendering engines. The title and body you send are the body that is shown.
• User-preference management: no quiet-hours, no opt-out, no priority filtering, no per-user subscriptions.
• Delivery-status tracking. The service does not expose pending, delivered, or failed states per notification.
• Configurable retry or backoff. There is no API for tuning retry behaviour.

If you need any of the above, sync them through a different kit or through Hoody’s general messaging layer — they are not part of this service.

Rate limits

The service applies three fixed rate limits. These are not configurable per project:

Scope	Limit
General	60 requests / minute
notify endpoint	10 requests / minute
icons endpoint	100 requests / minute

Caution

The notify limit of 10/min is intentionally tight. The service is designed for discrete, human-meaningful events (a build finished, a long-running task completed) — not for high-frequency streaming of agent output. If you need to surface many small updates, batch them client-side before calling notify.

Choosing the right endpoint

Goal	Endpoint
Show a desktop notification now	POST /api/v1/notifications/notify
List past notifications for a display, including dismiss state	GET /api/v1/notifications/{display}
Mark a notification as dismissed	POST /api/v1/notifications/dismiss
Clear a dismissed notification from history	DELETE /api/v1/notifications/dismiss
Subscribe to a live stream of notification updates	GET /api/v1/notifications/stream
Resolve an icon id to an image	GET /api/v1/notifications/icons/{iconId}
Check service health	GET /api/v1/notifications/health
Scrape metrics	GET /api/v1/notifications/metrics

The individual endpoint reference pages linked from the sidebar document the exact request bodies, response schemas, and error codes for each operation.