# Fetching Notifications

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

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

---

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



## Fetching Notifications

Retrieve, stream, dismiss, and clear notifications associated with one or more displays. Use these endpoints to fetch historical notification data, subscribe to real-time notification events over WebSocket, or manage dismissed state.

---

### `GET /api/v1/notifications/{display}`

Retrieves notifications for one or more specified displays. The `display` path parameter accepts a single display ID (e.g. `"1"` or `":1"`), a comma-separated list (e.g. `"1,:2,3"`), or `"all"` to fetch from all displays.

#### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `display` | path | string | Yes | A single display ID (e.g. `"1"` or `":1"`), a comma-separated list (e.g. `"1,:2,3"`), or `"all"` to fetch from all displays |
| `limit` | query | integer | No | Maximum number of notifications to return. Defaults to `100` |
| `since` | query | integer | No | Unix timestamp in milliseconds to get notifications after this time |
| `username` | query | string | No | Filter notifications by username |
| `session` | query | string | No | Filter notifications by session ID |




```bash
curl -X GET "https://display.kit.hoody.com/api/v1/notifications/1?limit=50&since=1749024000000" \
  -H "Authorization: Bearer <token>"
```




```typescript
const result = await client.notifications.listIterator({
  display: "1",
  limit: 50,
  since: 1749024000000,
});
```




```json
{
  "success": true,
  "data": {
    "count": 1,
    "displays": ["1"],
    "notifications": [
      {
        "id": 10,
        "appname": "Google Chrome",
        "summary": "Focus or Open a Window",
        "body": "Click to focus the window",
        "message": "Focus or Open a Window: Click to focus the window",
        "icon_url": "/api/v1/notifications/icons/6_10_1749024932903.png",
        "has_icon": true,
        "category": "system",
        "urgency": "normal",
        "expire_time": 5000,
        "display_id": 1,
        "timestamp": 1749024932903
      }
    ]
  }
}
```




```json
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid display parameter"
}
```




```json
{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "An unexpected error occurred while retrieving notifications"
}
```




---

### `GET /api/v1/notifications/stream`

Establishes a WebSocket connection for real-time notification updates. Clients can subscribe to one or more displays and receive immediate notifications as they occur.


This endpoint uses the WebSocket protocol. A successful connection returns HTTP `101 Switching Protocols` and then streams JSON notification messages until the client disconnects.


#### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `displays` | query | string | Yes | Comma-separated display IDs to subscribe to (e.g. `"0,:1,2"`), or `"all"` to receive notifications from every display |




```bash
curl -i -N \
  -H "Connection: Upgrade" \
  -H "Upgrade: websocket" \
  -H "Sec-WebSocket-Version: 13" \
  -H "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" \
  "https://display.kit.hoody.com/api/v1/notifications/stream?displays=all"
```




```typescript
const stream = await client.notifications.connectStream({
  displays: "all",
});

stream.on("message", (notification) => {
  console.log(notification);
});
```




```
HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=
```




```json
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Missing or invalid 'displays' query parameter"
}
```




```json
{
  "error": "Connection limit exceeded",
  "type": "error"
}
```




---

### `POST /api/v1/notifications/dismiss`

Marks notifications as dismissed. Dismissed notifications are filtered from subsequent `GET` responses.

This endpoint takes no parameters.

#### Request Body

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `notificationIds` | array&lt;integer&gt; | Yes | Array of notification IDs to dismiss |
| `displayId` | string | No | Optional display ID to scope the dismissal |




```bash
curl -X POST "https://display.kit.hoody.com/api/v1/notifications/dismiss" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "displayId": "1",
    "notificationIds": [10, 11, 12]
  }'
```




```typescript
const result = await client.notifications.dismiss({
  data: {
    displayId: "1",
    notificationIds: [10, 11, 12],
  },
});
```




```json
{
  "success": true,
  "message": "3 notification(s) dismissed"
}
```




```json
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "notificationIds must be a non-empty array of integers"
}
```




```json
{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "An unexpected error occurred while dismissing notifications"
}
```




---

### `DELETE /api/v1/notifications/dismiss`

Clears the dismissed state, making previously dismissed notifications visible again.

#### Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `displayId` | query | string | No | Optional display ID to scope the clear operation |




```bash
curl -X DELETE "https://display.kit.hoody.com/api/v1/notifications/dismiss?displayId=1" \
  -H "Authorization: Bearer <token>"
```




```typescript
const result = await client.notifications.clearDismissed({
  displayId: "1",
});
```




```json
{
  "success": true,
  "message": "Dismissed notifications cleared"
}
```




---

### Notification object schema

The objects returned inside `data.notifications` for the list endpoint share the following structure:

| Field | Type | Description |
|-------|------|-------------|
| `id` | integer | Unique notification ID |
| `appname` | string | Name of the application that triggered the notification |
| `summary` | string | Notification summary/title |
| `body` | string | Notification body text |
| `message` | string | Combined message text |
| `icon_url` | string | Relative URL to the notification icon |
| `has_icon` | boolean | Whether the notification has an icon |
| `category` | string | Notification category |
| `urgency` | string | Urgency level. One of `low`, `normal`, or `critical` |
| `expire_time` | integer | Expiration time in milliseconds |
| `display_id` | integer | Display ID where the notification was shown |
| `timestamp` | integer | Unix timestamp in milliseconds when the notification was created |