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

cURL

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

SDK

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

Response — 200

{
  "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
      }
    ]
  }
}

Response — 400

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

Response — 500

{
  "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.

Note

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

cURL

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"

SDK

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

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

Response — 101

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

Response — 400

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

Response — 429

{
  "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<integer>	Yes	Array of notification IDs to dismiss
displayId	string	No	Optional display ID to scope the dismissal

cURL

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]
  }'

SDK

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

Response — 200

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

Response — 400

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

Response — 500

{
  "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

cURL

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

SDK

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

Response — 200

{
  "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