The bell: a user's notifications, read and unread

GET

/v1/notifications/inbox

Newest first: this user’s own notifications, the groups they are in and the broadcasts of the last 30 days, with this user’s read, click and archive state, plus unread_count and poll_interval_seconds (Free 60, Indie 20, Builder 15). Archived ones are left out unless archived=only; category shows one tab.

Auth: Publishable key from the browser, with user_id and user_hash = HMAC-SHA256(signing secret, user_id) as lowercase hex, in the X-Nordva-User-Hash header or a user_hash parameter. A secret key may name any user_id and needs no hash. A wrong or missing hash answers USER_HASH_INVALID (403).

Rate limits: a browser call counts against 120 requests a minute per IP address (not the key’s budget), and the bell reads (/inbox, /unread, /unread/count) share a per-user hourly budget: Free 180, Indie 540, Builder 720 (RATE_LIMITED, 429, with Retry-After).

CORS: Access-Control-Allow-Origin: *.

Authorizations

PublishableApiKey
SecretApiKey

Parameters

Query Parameters

user_id

required

string

<= 256 characters

user_hash

string

The same hash, when a header is inconvenient.

limit

integer

default: 20 >= 1 <= 50

since

string format: date-time

Only notifications that showed after this.

category

string

archived

string

default: exclude

Allowed values: exclude only

Header Parameters

X-Nordva-User-Hash

string

HMAC-SHA256(signing secret, user_id), lowercase hex.

Responses

200

Inbox

object

data

object

notifications

Array<object>

What the bell needs. read, clicked and archived are this user’s.

object

string

title

string

body

string

action_url

string | null

icon

string

Allowed values: check warning info error

category

A short name the bell can show as a tab, such as billing.

string | null

/^[a-z][a-z0-9_-]{0,23}$/

actions

Up to two buttons. Each url is an http(s) URL or a path on your own site.

Array<object>

<= 2 items

object

label

required

string

<= 40 characters

url

required

string

<= 2048 characters

data

Anything your page needs with the item (at most 2,048 bytes as JSON). Never shown; the bell widget passes it in its events.

object | null

created_at

When it showed (the scheduled time for a scheduled one).

string format: date-time

read

boolean

read_at

string | null

clicked

boolean

archived

boolean

broadcast

boolean

changelog

Posted by a changelog entry; the widget labels it “What’s new”.

boolean

pinned

boolean

reactions

What this user can react with, in order, with everyone’s counts; null when it takes no reactions.

array | null

object

name

string

emoji

string

count

integer

my_reaction

This user’s reaction.

string | null

unread_count

integer

poll_interval_seconds

integer

error

null

meta

object

400

Error envelope. See error.code for the discriminator.

object

data

required

null

error

required

object

code

required

string

message

required

string

remediation

required

string

doc_url

string format: uri

param

string

request_id

string

meta

object

key

additional properties

401

Error envelope. See error.code for the discriminator.

object

data

required

null

error

required

object

code

required

string

message

required

string

remediation

required

string

doc_url

string format: uri

param

string

request_id

string

meta

object

key

additional properties

403

Error envelope. See error.code for the discriminator.

object

data

required

null

error

required

object

code

required

string

message

required

string

remediation

required

string

doc_url

string format: uri

param

string

request_id

string

meta

object

key

additional properties

429

Error envelope. See error.code for the discriminator.

object

data

required

null

error

required

object

code

required

string

message

required

string

remediation

required

string

doc_url

string format: uri

param

string

request_id

string

meta

object

key

additional properties