Skip to content
calternal docs

List Notifications inbox items

GET
/api/v1/notifications/inbox
curl --request GET \
  --url https://example.com/api/v1/notifications/inbox \
  --header 'Authorization: Bearer <token>'

Return the caller’s inbox items, newest first. Use cursor to continue from the last page and limit to choose the page size. The response also includes the unread count for the whole inbox. Route: /api/v1/notifications/inbox. Inputs: cursor, limit. Safe reads can use bounded retries.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
cursor
string

Opaque cursor returned by the previous page.

limit
integer format: int32

Requested page size. The server clamps this value to 100.

Responses

Section titled “Responses”

200

Section titled “200”
Media typeapplication/json

A page of inbox items and an optional cursor for the next page.

object
items
required

Newest items first.

Array<object>

One inbox item returned to the authenticated User.

object
action_label

Action label for a web toast while its Installation still owns the action.

string | null
body

Optional display detail.

string | null
created_ms
required

Creation time in Unix milliseconds.

integer format: int64
id
required

Stable notification identifier.

string
kind
required

Stable notification category.

string
link

Optional local deep link.

string | null
read_ms

Read time in Unix milliseconds, or null when unread.

integer | null format: int64
reminder_state

Per-User action state for an active block reminder, when this row owns one.

string | null
title
required

Short display title.

string
next_cursor

Opaque cursor for the next page.

string | null
unread_count
required

Unread items in the whole inbox, not only on this page. The web badge reads it from a one-item page, so it never pages the inbox to count.

integer format: int32
Examplegenerated
{
  "items": [
    {
      "action_label": "example",
      "body": "example",
      "created_ms": 1,
      "id": "example",
      "kind": "example",
      "link": "example",
      "read_ms": 1,
      "reminder_state": "example",
      "title": "example"
    }
  ],
  "next_cursor": "example",
  "unread_count": 1
}

400

Section titled “400”
Media typeapplication/json

The standard API error response: { "error": { ... } }.

object
error
required

Error details.

object
code
required

Stable machine-readable code.

string
Allowed values: bad_request unauthorized forbidden not_found conflict name_conflict_case name_too_long push_endpoint_rejected too_many_requests internal service_unavailable
details
One of:

Optional field or operation details.

object
key
additional properties
string
message
required

Safe text for logs or a user-facing error message.

string
Example
{
  "error": {
    "code": "bad_request"
  }
}

401

Section titled “401”
Media typeapplication/json

The standard API error response: { "error": { ... } }.

object
error
required

Error details.

object
code
required

Stable machine-readable code.

string
Allowed values: bad_request unauthorized forbidden not_found conflict name_conflict_case name_too_long push_endpoint_rejected too_many_requests internal service_unavailable
details
One of:

Optional field or operation details.

object
key
additional properties
string
message
required

Safe text for logs or a user-facing error message.

string
Example
{
  "error": {
    "code": "bad_request"
  }
}

403

Section titled “403”
Media typeapplication/json

The standard API error response: { "error": { ... } }.

object
error
required

Error details.

object
code
required

Stable machine-readable code.

string
Allowed values: bad_request unauthorized forbidden not_found conflict name_conflict_case name_too_long push_endpoint_rejected too_many_requests internal service_unavailable
details
One of:

Optional field or operation details.

object
key
additional properties
string
message
required

Safe text for logs or a user-facing error message.

string
Example
{
  "error": {
    "code": "bad_request"
  }
}