Triggering Notifications

Send desktop notifications to a target display using notify-send. This endpoint accepts a notification payload and dispatches it to the specified X11 display, with configurable urgency, icon, and expiration.

POST /api/v1/notifications/notify

Triggers a new desktop notification using notify-send on the target display.

This endpoint takes no path, query, or header parameters.

Request Body

Name	Type	Required	Description
display	string	Yes	Target display ID (e.g., "1" or ":1")
summary	string	Yes	Notification summary/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. Accepted values: low, normal, critical. Default: "normal"

Response 200 — Notification sent successfully

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

Response 400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid notification payload"
}

Response 429

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Rate limit exceeded"
}

Response 500

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Failed to send notification"
}

SDK Usage

cURL

curl -X POST "https://{projectId}-{containerId}-n-1.{server}.containers.hoody.icu/api/v1/notifications/notify" \
  -H "Content-Type: application/json" \
  -d '{
    "display": "1",
    "summary": "Test Notification",
    "body": "This is a test message from the API.",
    "category": "test-api",
    "icon": "info",
    "urgency": "normal",
    "expire_time": 5000
  }'

TypeScript SDK

await client.notifications.notify.trigger({
  display: "1",
  summary: "Test Notification",
  body: "This is a test message from the API.",
  category: "test-api",
  icon: "info",
  urgency: "normal",
  expire_time: 5000,
});

Response

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