Merged inbox list (direct + broadcast), keyset-paginated
Newest first, ordered by `(occurred_at, id)` descending across both sources. `cursor` is the opaque keyset token from the previous page's `next_cursor`. Category mutes are applied server-side. Supports `ETag` / `If-None-Match`, so post-reconnect refetches (deploy thundering herd) are mostly 304s. The validator is a strong hash over: the request cursor, `subscriber_counters.updated_at` (bumped by EVERY read-state mutation — see the counter invariants in schema.sql), the subscriber's latest direct item `(visible_at, id)`, the environment's latest broadcast `(created_at, id)`, and `max(preferences.updated_at)` for the subscriber. Each input is one index-only lookup; anything that can change a page moves at least one of them. Responses are `Cache-Control: private, max-age=0` — inbox pages are per-user data and must never be cached by shared proxies.
Newest first, ordered by (occurred_at, id) descending across both
sources. cursor is the opaque keyset token from the previous page's
next_cursor. Category mutes are applied server-side.
Supports ETag / If-None-Match, so post-reconnect refetches
(deploy thundering herd) are mostly 304s. The validator is a strong
hash over: the request cursor, subscriber_counters.updated_at
(bumped by EVERY read-state mutation — see the counter invariants in
schema.sql), the subscriber's latest direct item (visible_at, id),
the environment's latest broadcast (created_at, id), and
max(preferences.updated_at) for the subscriber. Each input is one
index-only lookup; anything that can change a page moves at least
one of them.
Responses are Cache-Control: private, max-age=0 — inbox pages are
per-user data and must never be cached by shared proxies.
Authorization
SubscriberEnv SubscriberHash SubscriberId In: header
Optional when the environment has require_subscriber_hash = false.
In: header
In: header
Query Parameters
Opaque keyset cursor; omit for the first page.
Header Parameters
Response Body
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v1/inbox/items"{
"items": [
{
"category": "string",
"id": "notif_01h455vb4pex5vsknk084sn02q",
"occurred_at": "2019-08-24T14:15:22Z",
"payload": {
"action_url": "http://example.com",
"body": "string",
"icon_url": "http://example.com",
"title": "string"
},
"read": true,
"source": "notification"
}
],
"next_cursor": "string"
}{
"error": {
"code": "invalid_request",
"message": "string"
}
}{
"error": {
"code": "invalid_request",
"message": "string"
}
}{
"error": {
"code": "invalid_request",
"message": "string"
}
}