Triggering Notifications

Send native desktop notifications to a target display via notify-send. Use this endpoint to dispatch OS-level notifications with configurable urgency, icons, categories, and expiration times. The notification is rendered on the display identified by the display field (e.g., "0" or ":0").

Trigger a new desktop 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

The request body must be a JSON object conforming to the notifications_NotifyRequest schema.

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

Responses

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

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

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

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

curl -X POST https://api.hoody.com/api/v1/notifications/notify \
  -H "Authorization: Bearer <token>" \
  -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",
    "expire_time": 5000,
    "urgency": "normal"
  }'

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