Notifications API
Durable recipient inbox and connected-browser preferences
Describe inbox and browser-delivery support
Requires notifications.read. In-app inbox delivery is mandatory; connected-browser foreground delivery plus polling and SSE are supported, while background delivery and Web Push are explicitly unavailable.
Read the complete category/channel preference matrix
Requires notifications.read. Returns the complete recipient category and channel matrix, including support flags, plus its deterministic revision in both the body and a strong ETag.
Update category/channel preferences optimistically
Requires notifications.manage, an exact same-origin proof for cookie requests, and the current strong ETag. One to ten unique category and channel updates apply atomically; omitted pairs remain unchanged and Web Push cannot be enabled.
List the recipient's durable notification inbox
Requires notifications.read. Results are scoped to the current recipient and current subject access; opaque keyset cursors are bound to that recipient and every active filter.
Dismiss selected notifications
Requires notifications.manage and an exact same-origin proof for cookie requests. One to one hundred unique recipient-scoped identifiers are handled atomically and idempotently; any unknown or inaccessible identifier rolls back the complete request.
Mark selected notifications read
Requires notifications.manage and an exact same-origin proof for cookie requests. One to one hundred unique recipient-scoped identifiers are handled atomically and idempotently; any unknown or inaccessible identifier rolls back the complete request.
Poll a resumable recipient-scoped notification change feed
Use tail=true without cursor/limit on first connection to suppress historical presentation. Expired cursors return resyncRequired=true.
Stream recipient-scoped durable notification changes
Authenticate with the same-origin HttpOnly cookie or an ordinary Authorization bearer session on fetch; credentials never belong in the URL. Personal access tokens use the polling endpoints instead, because this stream continually revalidates a rotating session without retaining a raw bearer. Supply a cursor in at most one of the cursor query parameter or Last-Event-ID header. With no cursor the stream starts at the current tail and emits ready. Each notification_changes event contains at most 50 ordered changes and its id is the next durable cursor. Missing retained history emits resync_required and closes. The server sends keepalive comments, revalidates authorization, limits concurrent streams, and relies on client polling as a lossless fallback.
Count unread durable notifications
Requires notifications.read. Counts only unread notifications still visible to the current recipient under current subject access.
Read one recipient-scoped notification
Requires notifications.read. Lookup is restricted to the current recipient and current subject access; unknown, inaccessible, and other-recipient identifiers are indistinguishable.
Dismiss one notification
Requires notifications.manage and an exact same-origin proof for cookie requests. The recipient-scoped command is idempotent: only unread or read notifications change, while terminal states return unchanged.
Mark one notification read
Requires notifications.manage and an exact same-origin proof for cookie requests. The recipient-scoped command is idempotent: a notification not currently unread returns unchanged, while an unknown or inaccessible identifier returns 404.