Fetching Notifications

Retrieve historical notifications from one or more displays, subscribe to a real-time notification stream, manage dismissed state, and clear previously dismissed notifications. Use these endpoints to render notification feeds, listen for live alerts via WebSocket, and persist dismissal state across sessions.

List Notifications

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

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

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. Default: `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

Response

{
  "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",
        "category": "system",
        "urgency": "normal",
        "has_icon": true,
        "icon_url": "/api/v1/notifications/icons/6_10_1749024932903.png",
        "display_id": 1,
        "timestamp": 1749024932903,
        "expire_time": 5000
      }
    ]
  }
}

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

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Failed to read notifications"
}

curl -X GET "https://myproj-cnt123-n-1.us-east.containers.hoody.icu/api/v1/notifications/1?limit=50&since=1749024000000" \
  -H "Authorization: Bearer <token>"

// Stream notifications one-by-one (paginated internally)
for await (const n of client.notifications.listIterator("1", {
  limit: 50,
  since: 1749024000000,
})) {
  console.log(n);
}

// Or fetch all matching notifications in one call
const all = await client.notifications.listAll("1", { limit: 50 });
console.log(all);

Real-time Notification Stream

`GET /api/v1/notifications/stream`

Establishes a WebSocket connection for real-time notification updates. Clients subscribe to one or more displays and receive immediate notifications as they are dispatched. The displays query parameter accepts a comma-separated list (e.g., "1,:2,3") or "all" to subscribe to every display.

Parameters

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

Response

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade

The HTTP response that confirms the WebSocket handshake; subsequent frames carry notification payloads.

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

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

SDK Usage

cURL
SDK

curl -i -N \
  -H "Connection: Upgrade" \
  -H "Upgrade: websocket" \
  -H "Sec-WebSocket-Version: 13" \
  -H "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" \
  "https://myproj-cnt123-n-1.us-east.containers.hoody.icu/api/v1/notifications/stream?displays=all"

// Wire typed callbacks BEFORE calling connect()
const stream = await client.notifications.connectStream({ displays: "all" });

stream.onNotification((msg) => console.log("new:", msg.data));
stream.onHeartbeat(() => {});
stream.onDisconnect((code, reason) => {});
stream.onError((err) => console.error(err));

await stream.connect();

// later
stream.close();

Dismiss Notifications

`POST /api/v1/notifications/dismiss`

Marks one or more notifications as dismissed. Dismissed notifications are filtered from subsequent GET responses. Optionally scope the dismissal to a specific display with displayId.

Request Body

Field	Type	Required	Description
`notificationIds`	array of integer	Yes	Array of notification IDs to dismiss
`displayId`	string	No	Optional display ID to scope the dismissal

Response

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

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "notificationIds is required and must be a non-empty array"
}

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Failed to persist dismissal"
}

SDK Usage

cURL
SDK

curl -X POST "https://myproj-cnt123-n-1.us-east.containers.hoody.icu/api/v1/notifications/dismiss" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "notificationIds": [10, 11, 12],
    "displayId": "1"
  }'

// Pass the body directly — do not wrap it in { data: {...} }
await client.notifications.dismiss({
  notificationIds: [10, 11, 12],
  displayId: "1",
});

Clear Dismissed Notifications

`DELETE /api/v1/notifications/dismiss`

Clears the dismissed state, making previously dismissed notifications visible again in subsequent GET responses. Optionally scope the clear to a single display with displayId; omit it to clear across all displays.

Parameters

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

Response

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

SDK Usage

cURL
SDK

curl -X DELETE "https://myproj-cnt123-n-1.us-east.containers.hoody.icu/api/v1/notifications/dismiss?displayId=1" \
  -H "Authorization: Bearer <token>"

await client.notifications.clearDismissed({ displayId: "1" });

// or clear across every display
await client.notifications.clearDismissed();