Send a notification

Send a POST to https://api.pocketbell.dev/v1/messages with the Source’s API key as a bearer token. Only message is required.

curl https://api.pocketbell.dev/v1/messages \
  -H "Authorization: Bearer pb_live_…" \
  -H "Content-Type: application/json" \
  -d '{"title": "Backup finished", "message": "db-1: 4.2 GB in 3m 12s"}'

Formatting

Add "markdown": true and the app shows bold, italic, code, links, and lists of lines starting with - or *. The notification on the lock screen shows the same text without the formatting.

curl https://api.pocketbell.dev/v1/messages \
  -H "Authorization: Bearer pb_live_…" \
  -H "Content-Type: application/json" \
  -d '{"title": "Deploy finished", "markdown": true,
       "message": "`main@4f2a91c` is live.\n\n- 14 commits\n- [Release notes](https://example.com/releases)"}'

Without it, text arrives exactly as sent, so snake_case_names and cron lines like */5 * * * * are left alone.

Limits

A Source can send 30 notifications in a burst, then one a second; all of an account’s Sources together, 60 in a burst, then two a second. Checking a notification’s status or canceling it has its own allowance of 60, then five a second. Past a limit the answer is 429 with the code rate_limited and a Retry-After header, in seconds: wait that long and send again. With an Idempotency-Key, retrying never sends twice.

Each plan also has a monthly allowance: 1,000 notifications on Free, 25,000 on Pro. Past it, the answer is 429 with monthly_limit_reached until the month turns (UTC), except for Critical notifications, which still go out and still count: on Pro always, and on Free for 100 more, so one looping script can’t send without end. The account owner is told at 80% and when it’s used up.

Every field, and every response, is in the API reference.