Triggering Notifications

Send desktop notifications to a running Hoody container using the notify-send utility. These endpoints let you push system-level alerts, messages, or status updates to a specific display from any HTTP client, the Hoody CLI, or the Hoody SDK.

POST /api/v1/notifications/notify

Triggers a new desktop notification on the target display.

This endpoint takes no parameters.

Request Body

All fields below are sent as the JSON body of the POST request.

Name	Type	Required	Description
display	string	Yes	Target display ID (for example "1" or ":1")
summary	string	Yes	Notification summary or title
body	string	No	Notification body text
category	string	No	Notification category
expire_time	integer	No	Expiration time in milliseconds
icon	string	No	Icon name or path
urgency	string	No	Notification urgency level. One of low, normal, critical. Default: "normal"

cURL

curl -X POST "https://{projectId}-{containerId}-n-1.{server}.containers.hoody.com/api/v1/notifications/notify" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "display": "1",
    "summary": "Build Complete",
    "body": "Your project compiled successfully in 42 seconds.",
    "category": "build-status",
    "expire_time": 5000,
    "icon": "info",
    "urgency": "normal"
  }'

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-n-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.notifications.send({
  display: "1",
  summary: "Build Complete",
  body: "Your project compiled successfully in 42 seconds.",
  category: "build-status",
  expire_time: 5000,
  icon: "info",
  urgency: "normal"
});

Response

{
  "message": "Notification sent successfully",
  "success": true
}

Responses

200

Returned when the notification is dispatched successfully on the target display.

{
  "message": "Notification sent successfully",
  "success": true
}

400

Returned when the request payload is invalid, for example, missing required fields, an unknown urgency value, or a malformed display ID.

{
  "details": "Invalid display ID format",
  "error": "Validation Error",
  "success": false
}

Error Code	Title	Description	Resolution
VALIDATION_ERROR	Invalid input parameters	Request parameters failed validation	Check parameter format and try again
INVALID_DISPLAY_ID	Invalid display ID	Display ID format is incorrect	Use a display number from 1 to 40000, for example "1" or ":1"
FIELD_TOO_LONG	Field longer than its limit	A field exceeds its maximum allowed length	Shorten the field; long text is never truncated for you
INVALID_CHARACTERS	Field holds unusable characters	A field contains NUL bytes or only control characters	Remove NUL bytes and control characters

429

Returned when the notification rate limit for the container has been exceeded.

{
  "details": "Too many requests, please try again later",
  "error": "Rate Limit Exceeded",
  "success": false
}

Error Code	Title	Description	Resolution
RATE_LIMIT_EXCEEDED	Rate limit exceeded	Too many requests from your IP address	Wait before retrying. Limits: 60/min general, 10/min notify, 100/min icons

500

Returned when the request was valid and the display’s session was found, but notify-send failed to deliver the notification.

{
  "success": false,
  "error": "Notification dispatch failed",
  "code": "DISPATCH_FAILED",
  "details": "The notification service failed to send the notification."
}

Error Code	Title	Description	Resolution
DISPATCH_FAILED	Notification dispatch failed	notify-send could not deliver the notification. details is exactly one of two fixed sentences: “Sending the notification timed out. Retry later.” or “The notification service failed to send the notification.”	Retry later; if it keeps failing, check the display’s notification daemon

503

Returned when the target display is missing or not up yet, so the notification cannot be shown. code tells the two cases apart, and details is a fixed sentence. DISPLAY_NOT_READY is sent with a Retry-After header (seconds to wait before retrying).

{
  "success": false,
  "error": "Display not available",
  "code": "DISPLAY_NOT_AVAILABLE",
  "details": "No display is running and none can be started in this container, so the notification cannot be shown."
}

Error Code	Title	Description	Resolution
DISPLAY_NOT_AVAILABLE	Display not available	The display is not running and the container has no display server to start it. Answered at once, without waiting for the display.	Retrying does not help: use a container image with display support
DISPLAY_NOT_READY	Display not ready	The display’s notification session did not come up within DISPLAY_ENSURE_TIMEOUT; the display may still be starting. Sent with Retry-After.	Retry after the Retry-After seconds