Hoody NotificationsDesktop Notifications Over HTTP.
Send Linux desktop notifications to any container display with a single HTTP POST. The Notification Server runs notify-send on your container's X11 display — trigger an alert, fetch the history, or stream events live.
# Send a notification to display 0
curl -X POST "https://abc123-def456-n-1.node-us-1.containers.hoody.com/api/v1/notifications/notify"
-d '{"display":"0","summary":"Build Complete","urgency":"normal"}'
# Response
{"success":true}
Three Steps. One HTTP Call Each.
Every notification follows the same lifecycle: trigger it over HTTP, deliver it to the target display via notify-send, then fetch the history or stream it live.
Trigger
A POST to /notify calls notify-send on the target X11 display. Supply summary and display, plus optional body, category, urgency, expire_time, or icon.
# Fire a notification
curl -X POST .../notify
{"display":"0",
"summary":"Build Complete",
"urgency":"normal"}
{"success":true}
Deliver
notify-send hands the alert to the system's notification daemon on the target X11 display. It appears in any connected display session and auto-expires according to its urgency and expire_time.
# notify-send on display :0
notify-send → X11 :0
▸ Build Complete
normal · auto-expires
Fetch or Stream
GET /[display] returns notification history with optional limit, since, username, and session filters. Or open a WebSocket to /stream?displays=0 for real-time push.
# Poll history
curl .../0?limit=50
# Or stream live
new WebSocket(
"wss://.../stream?displays=0"
)
low. normal. critical.
The urgency field takes one of three documented values that map directly to notify-send behavior. Pick the right one and the notification daemon handles the rest.
Quiet and quick to dismiss. Pair with a short expire_time like 3000 ms for background tasks, telemetry, or informational pings that should not steal focus.
"urgency": "low",
"expire_time": 3000
The standard level, used whenever urgency is omitted. The notification daemon shows it at the configured timeout and dismisses it automatically.
"urgency": "normal"
// default — omit to use this
Stays on screen until acted on. Pair with expire_time 0 for system failures, build errors, or anything that demands immediate attention.
"urgency": "critical",
"expire_time": 0
Fetch History or Stream Live.
Two read channels for two needs: REST for audit logs and one-shot queries, WebSocket for dashboards and real-time monitors.
Pull notification history for one or more displays. Filter by limit, since timestamp, username, or session. Use it for audit logs, one-shot queries, and batch processing.
# last 50 for display 0
curl ".../0?limit=50"
# only since a timestamp
curl ".../0?since=1749025000000"
JSON with a notifications array — each object carries id, summary, body, urgency, category, icon_url, and timestamp.
Subscribe with displays=0,:1,2 or displays=all and receive each notification the moment it fires. Use it for dashboards and real-time monitoring.
# open a WebSocket
const ws = new WebSocket(
"wss://.../stream?displays=0"
)
# handle each push
ws.onmessage = (e) => {
const msg = JSON.parse(e.data)
// msg.summary, msg.body, msg.urgency
}
A WebSocket upgrade (HTTP 101), then a JSON message pushed for every new notification on the subscribed displays.
From Build Pipelines to ML Jobs.
Anywhere a long-running process needs to signal completion or failure, one HTTP POST is all it takes.
CI/CD Alerts
A long-running build finishes and a single HTTP POST raises a notification on the container display — visible in any active display session.
System Monitoring
Server alerts route to a desktop notification on the container's X11 display, with urgency set to critical so failures stay on screen until acknowledged.
Long-Running Tasks
Data exports, video rendering, ML model training, and backup jobs all notify on completion — no polling, no dashboards to babysit.
Automated Workflows
Cron jobs, scheduled tasks, and automation scripts post to /notify on success or failure, then a monitor streams those events over WebSocket.
5 Endpoints. One Notification Server.
Trigger, fetch, and stream desktop notifications — plus icons and a health check — all over plain HTTP.
Base URL https://abc123-def456-n-1.node-us-1.containers.hoody.com
Trigger
1 endpointPOST .../api/v1/notifications/notify
Fetch & Stream
2 endpointsGET .../api/v1/notifications/{display}?limit=50
Icons
1 endpointGET .../api/v1/notifications/icons/{iconId}
Health
1 endpointGET .../api/v1/notifications/health
Notifications Are One HTTP POST Away.
Any script, service, or automation that can make an HTTP request can raise a desktop notification on your container display.