Triggering Notifications

Send desktop notifications to the container’s display via notify-send. Use this endpoint to surface alerts, status updates, or asynchronous results to a user watching the container’s desktop session.

Trigger notification

POST /api/v1/notifications/notify

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

This endpoint takes no parameters.

Request Body

Name	Type	Required	Default	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	`"normal"`	Notification urgency level. One of: `low`, `normal`, `critical`

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 '{
    "summary": "Test Notification",
    "body": "This is a test message from the API.",
    "display": "1",
    "category": "test-api",
    "icon": "info",
    "expire_time": 5000,
    "urgency": "normal"
  }'

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.notify.trigger({
  summary: 'Test Notification',
  body: 'This is a test message from the API.',
  display: '1',
  category: 'test-api',
  icon: 'info',
  expire_time: 5000,
  urgency: 'normal'
});

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

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

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

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