# Triggering Notifications

**Page:** api/kit/notification-server/triggering

[Download Raw Markdown](./api/kit/notification-server/triggering.md)

---

{/* AUTO-GENERATED — Do not edit manually. Regenerate with: npm run docs:api:generate */}



## 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.


The `display` field identifies the X11 display where the notification will appear (e.g., `"0"` for `:0`). Ensure the display identifier is valid for the host running the notification server.


### `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` |

#### Example Request




```bash
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"
  }'
```




```typescript
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.

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




The request was malformed or missing required fields.

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




The notification server is receiving requests too rapidly.

```json
{
  "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).

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