Skip to content
PocketbellAPI

Sync the inbox

GET
/v1/messages
curl --request GET \
  --url 'https://api.pocketbell.dev/v1/messages?limit=100' \
  --header 'Authorization: Bearer <token>'

Every message that changed since the cursor: new ones, and ones read, acknowledged or deleted on another device. Start with no cursor; keep next_cursor for next time.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
since

The next_cursor from the last page.

string
/^\d{1,18}$/
limit
integer
default: 100 >= 1 <= 200

Responses

Section titled “Responses”

200

Section titled “200”

A page of changes.

Media typeapplication/json
object
messages
required

In the order they changed, oldest change first.

Array<object>
object
id
required
string
source
required
object
id
required
string
name
required
string
title
required
string | null
message
required

The whole text, even when the push carried a shortened one.

string
markdown
required

The message uses markdown.

boolean
priority
required
string
Allowed values: silent quiet normal important critical
url
required
string | null
url_title
required
string | null
thread
required
string | null
tags
required
Array<string>
actions
required
Array<object>
object
label
required
string
url
required
string
attachment_url
required
string | null
created_at
required
string format: date-time
read_at
required
string | null format: date-time
acknowledged_at
required
string | null format: date-time
acknowledged_device
required

The name of the device it was acknowledged on, when known.

string | null
canceled_at
required

Canceled by the sender: no longer waiting for acknowledgment or an answer.

string | null format: date-time
options
required

A question’s answers, as buttons; empty for any other notification.

Array<string>
answer
required
string | null
answered_at
required
string | null format: date-time
answered_device
required
string | null
expires_at
required

A question stops waiting at this time; a Critical notification stops repeating.

string | null format: date-time
deleted
required

Out of the inbox. Without replaced_by, deleted: remove it; its text is empty.

boolean
replaced_by

Replaced by this newer message, with the same replace key: no longer in the inbox on its own, but kept, text and all, as an earlier update of that message.

string | null
next_cursor
required

Send as since next time, to get only what changed after this page.

string
has_more
required

More changes are waiting: ask again at once with since set to next_cursor.

boolean
Example
{
  "messages": [
    {
      "id": "msg_01jz9k6q8r3tfv0x2m4n5p7s8a",
      "priority": "silent",
      "created_at": "2026-09-27T21:00:41.750Z"
    }
  ]
}

400

Section titled “400”

The request was invalid.

Media typeapplication/json
object
error
required
object
code
required
string
message
required
string
details

Which fields were wrong, for invalid_request.

Array<object>
object
field
required
string
message
required
string
Example
{
  "error": {
    "code": "invalid_request"
  }
}

401

Section titled “401”

Missing or ended session.

Media typeapplication/json
object
error
required
object
code
required
string
message
required
string
details

Which fields were wrong, for invalid_request.

Array<object>
object
field
required
string
message
required
string
Example
{
  "error": {
    "code": "invalid_request"
  }
}