Class NotificationResource

Archive a notification Moves a notification to "archived" status regardless of whether it is currently "unread" or "read". Archived notifications are excluded from the default inbox view but remain retrievable by passing status: "archived" to the list endpoint. The authenticated user must own the notification. Passing a notification ID that belongs to a different user returns a 404. If the notification is already archived this call succeeds without error (idempotent). Requires an app-scoped token. Returns 204 No Content on success.

List a user's notifications Returns a cursor-paginated list of inbox notifications for the authenticated user, ordered by creation time descending (newest first). All status groups are included by default; pass status to narrow results to a specific group. Each notification's rendered field contains type-specific display data resolved at request time. Notifications whose type is no longer registered in the platform are rendered with kind: "unknown" rather than being omitted. Pagination is forward-only: supply after_cursor from a previous response to fetch the next (older) page. The before_cursor field is always null for this endpoint. Requires an app-scoped token.

Mark a notification as read Transitions a notification from "unread" to "read" status. If the notification is already "read" or "archived", the call succeeds without changing its status (idempotent). The authenticated user must own the notification. Passing a notification ID that belongs to a different user returns a 404. Requires an app-scoped token. Returns 204 No Content on success.

Mark all notifications as read Marks every "unread" notification belonging to the authenticated user as "read" in a single operation. Notifications that are already "read" or "archived" are not affected. This call is safe to retry — if there are no unread notifications, it succeeds without error. Requires an app-scoped token. Returns 204 No Content on success.

Send a custom notification to a user Delivers a custom-typed notification to one of the calling app's users. Apps define notification types by declaring NotificationType config objects in their bundle (one per lookup_key). Supply the type as "custom:<lookup_key>" and provide a data map that is merged with platform-provided context to render the notification's display fields. Only app-scoped tokens may call this endpoint — user tokens are rejected with 403. The app scope is stamped onto the notification automatically; an app cannot target recipients outside its tenant. Built-in platform types such as "app_info" and "billing_alert" are not accepted here. Pass idempotency_key to deduplicate sends. If you call this endpoint twice with the same idempotency_key for the same recipient, the second call returns the original notification without creating a duplicate. The key is scoped to the calling app, so the same raw key used by different apps cannot collide.

Unarchive a notification Restores an "archived" notification to its previous active status: "read" if the notification had been read before archiving, or "unread" otherwise. The notification will appear again in the default inbox view. The authenticated user must own the notification. Passing a notification ID that belongs to a different user returns a 404. If the notification is not currently archived this call succeeds without changing its status (idempotent). Requires an app-scoped token. Returns 204 No Content on success.

Get the unread notification count Returns the total number of "unread" notifications for the authenticated user. Useful for displaying a badge or indicator in your UI without fetching the full notification list. Notifications with "read" or "archived" status are not included in the count. Requires an app-scoped token.