Triggering Notifications

Trigger Notification

Send a desktop notification to a target display using notify-send. Use this endpoint to surface alerts, status updates, or any event-driven message on the user’s desktop session. The notification is rendered by the system’s notification daemon on the specified display.

`POST /api/v1/notifications/notify`

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

This endpoint takes no parameters.

Request Body

Send a JSON object with the following fields:

Name	Type	Required	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
`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 -X POST https://api.hoody.com/api/v1/notifications/notify \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "summary": "Build Complete",
    "display": "1",
    "body": "Your deployment to production finished successfully.",
    "category": "deployment",
    "icon": "dialog-information",
    "expire_time": 5000,
    "urgency": "normal"
  }'

const response = await client.notifications.notify.trigger({
  summary: "Build Complete",
  display: "1",
  body: "Your deployment to production finished successfully.",
  category: "deployment",
  icon: "dialog-information",
  expire_time: 5000,
  urgency: "normal"
});

Responses

Notification sent successfully.

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

The request was malformed or missing required fields.

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

The notification server is receiving requests too rapidly.

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

The notification server encountered an internal error (for example, notify-send failed or the target display is unavailable).

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