Docs

Send your first push in a minute.

One bearer token, one URL. POST a JSON payload and your phone lights up. Use pushr cloud, or run the open-source backend yourself. Working with an AI agent? Give it pushr's skills or llms.txt.

Using an AI agent?

Install pushr's skills and ask in plain words, like "notify me when this build fails".

$npx skills add cpreston321/pushr-backend

Quickstart

Three steps on pushr cloud. Self-hosting? Jump to the self-hosting guide.

  1. 1
    Get the app

    Install pushr on your iPhone, sign up and allow notifications.

  2. 2
    Create a source app

    In the Apps tab, tap +, name it after what will send pushes, and copy the token. It is shown once.

  3. 3
    Send a request

    In the app's API & token sheet, tap Copy curl example: your notify URL is filled in. Run it anywhere.

bash
curl -X POST "$PUSHR_URL/notify" \
  -H "Authorization: Bearer $PUSHR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Hello","body":"from my terminal"}'
Try itPOST /notify
Idle
Priority

URL and token persist in this browser only. Nothing is logged server-side by the docs page.

Pending—

Fill in URL and token, then hit send. The actual HTTP response prints here: status, latency, body.

Effective curl
bash
curl -X POST https://site-convex.pushr.sh/notify \
  -H "Authorization: Bearer $PUSHR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Hello from the docs",
    "body": "It works.",
    "priority": "normal"
  }'

Every endpoint lives at your server's site URL, referenced below as $PUSHR_URL. On pushr cloud, the app's API & token sheet shows it and can copy a ready-to-run curl example; self-hosted, it's your Convex deployment's https://<your-deployment>.convex.site. Every authenticated endpoint takes a source-app bearer token (pshr_…) created from the mobile app's Apps tab and referenced as $PUSHR_TOKEN.


Endpoints at a glance


POST /notify

Sends one notification to every device the source app's owner has registered (and to every accepted member's devices, if the app is shared).

Minimal example

bash
curl -X POST "$PUSHR_URL/notify" \
  -H "Authorization: Bearer $PUSHR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Build succeeded",
    "body":  "ci.example.com / main → staging"
  }'

Request

Plain
POST /notify
Authorization: Bearer pshr_…
Content-Type: application/json
POST/notify
RequiredEvery push has these.
titleRequiredstring
Banner title.
bodyRequiredstring
Banner body.
messageAliasstring
Gotify-compatible alias for body.
ContentWhat the push says and opens.
urlstring
Tapping the banner opens this URL. See Links and images.
dataobject
Arbitrary JSON delivered alongside the push, to the app’s notification handler.
imagestring
Image URL attached as the banner’s thumbnail. See Links and images.
actionLegacyobject
One button, { label, url }. Replaced by actions when both are set.
replaceKeystring ≤ 128
A newer push with the same key replaces this one, on the phone and in the feed. See Replace keys.
DeliveryWhen and how loudly it arrives.
priority1–10 | string
1–6, low, normal or default deliver normally; 7–10 and high wake the device. Defaults to normal; anything else is a 400. See Priority and interruption.
deliverAtnumber (ms-epoch)
Sends it later. At least now − 60 s, and a number: an ISO string is ignored and it sends at once. Counts toward your quota when accepted. See Scheduled delivery.
ackobject
Ack-or-escalate alarm. See Ack-or-escalate.
criticalboolean
Rings through mute and Do Not Disturb, where the app allows critical alerts. See Critical alerts.
InteractionButtons, replies and Live Activities.
actionsarray ≤ 4
Buttons and replies. See Action buttons.
liveActivityobject
Drives an iOS Live Activity. See Live Activities.

Response

Body
{
  "id": "j97…",
  "scheduledFor": null
}
id
The notification, for logs and support.
scheduledFor
The deliverAt you sent, in ms, or null when it went at once.
202AcceptedIt’s on its way: delivered now, or at scheduledFor.
200ReplayedA retry with an Idempotency-Key already used. Same body, plus Idempotent-Replay: true. Nothing is sent again.

Anything else is an error; see Errors and retries.


Guides

Each one is a field (or two) on POST /notify.

Priority and interruption

bash
# Wake the device — banner + sound:
-d '{"title":"DB disk > 90%","body":"prod","priority":"high"}'

# Numeric (Gotify-style 1-10):
-d '{"title":"FYI","body":"nightly backups complete","priority":4}'
Try it: how hard it interrupts
On the phone
FocusWednesday, September 30
9:41
Cci.example.comTime sensitivenowDB disk > 90%prod-db-1 · 92% used
Time-sensitive: it breaks through Focus.
The request
json
{
  "title": "DB disk > 90%",
  "body": "prod-db-1 · 92% used",
  "priority": 8
}
What iOS does · time-sensitive
  • ✓Shows a banner
  • ✓Plays a sound
  • ✓Lights the screen
  • ✓Breaks through Focus

Priority also sets how hard the push may interrupt on iOS:

PriorityiOS interruption levelEffect
1–3, "low"passiveLands quietly in Notification Center, no screen wake
4–6, "normal" (default)activeA normal banner and sound
7–10, "high"time-sensitiveBreaks through Focus and the notification summary
any push with acktime-sensitiveSame, for every re-push until acknowledged
critical, where the app allows itcriticalPlays its sound even with the ringer off or in Do Not Disturb

During a source app's quiet hours, pushes are delivered as passive unless they need acknowledgment.

bash
-d '{
  "title": "PR #42 merged",
  "body":  "from peptide",
  "url":   "https://github.com/owner/repo/pull/42"
}'
bash
-d '{
  "title": "New deploy",
  "body":  "Build #382 passed",
  "image": "https://ci.example.com/badges/build-382.png"
}'
Try it: tap the banner
On the phone
Wednesday, September 30
9:41
Tap the notification.
The request
json
{
  "title": "PR #42 merged",
  "body": "Build #382 passed",
  "url": "https://github.com/owner/repo/pull/42",
  "image": "https://ci.example.com/badges/build-382.png"
}

A tap opens the link. The image shows as a thumbnail on the banner.

Action buttons

Up to 4 actions. Three kinds:

jsonc
{
  "title": "Staging deploy ready",
  "body":  "Merge main → staging?",
  "actions": [
    {
      "kind": "callback",
      "id": "approve",
      "label": "Approve",
      "callbackUrl": "https://ci.example.com/deploy/42/approve"
    },
    {
      "kind": "callback",
      "id": "reject",
      "label": "Reject",
      "callbackUrl": "https://ci.example.com/deploy/42/reject",
      "destructive": true
    },
    {
      "kind": "open_url",
      "id": "logs",
      "label": "View logs",
      "url": "https://ci.example.com/deploy/42"
    },
    {
      "kind": "reply",
      "id": "comment",
      "label": "Reply",
      "callbackUrl": "https://ci.example.com/deploy/42/comment",
      "placeholder": "Add a note…"
    }
  ]
}
kindBehavior
open_urlOpens url when tapped. Recorded as an event server-side.
callbackPOSTs to callbackUrl. HTTP status stored on the action event. Optional authRequired to lock-gate.
replyiOS inline text reply. POSTs { reply, ... } to callbackUrl. Optional placeholder.

Decisions: one answer per notification

The callback actions on a notification are treated as one choice, like Approve or Reject. Once one of them has gone through, the others are refused ("Already answered"), whether the second tap comes from the feed, the Lock Screen or another device, so your endpoint hears exactly one answer. A callback that fails (a network error or a 4xx/5xx from your endpoint) leaves the choice open to retry or change. reply and open_url actions aren't part of the decision and keep working afterwards.

In the app's feed, the callbacks sit together as a full-width pair: the first one that isn't destructive is the suggested action, and a destructive one is shown in red. Once answered, the pair becomes a single line with the answer and when it was given. Links and replies sit under the pair as smaller buttons. So for a yes/no question, send one callback for each answer and mark the risky one destructive:

jsonc
"actions": [
  { "kind": "callback", "id": "approve", "label": "Approve", "callbackUrl": "https://ci.example.com/deploy/42/approve" },
  { "kind": "callback", "id": "reject",  "label": "Reject",  "callbackUrl": "https://ci.example.com/deploy/42/reject", "destructive": true },
  { "kind": "open_url", "id": "logs",    "label": "View logs", "url": "https://ci.example.com/deploy/42" }
]

If you need several independent buttons rather than one answer, send them as separate notifications.

Try it: one answer
In the feed
C
ci.example.comnow
Staging deploy ready
Merge main → staging?
Your endpoint receives

Tap Approve or Reject to see the request pushr sends.

Callback request shape

When the user taps a callback or reply action, pushr POSTs to your callbackUrl:

Plain
POST /your/endpoint
Content-Type: application/json
User-Agent: pushr/1.0
X-Pushr-Source: pushr
X-Pushr-Notification: <notificationId>
X-Pushr-Action: <action.id>

{
  "notificationId": "...",
  "actionId":       "approve",
  "respondedAt":    1712160000000,
  "reply":          "LGTM"          ← only for kind=reply
}

callbackUrl must be a public https:// URL: localhost, private-network and link-local addresses are rejected, and redirects are not followed. pushr records only the response status, never the body. Members of a shared app can run callbacks and replies too. The owner can turn that off for a viewer (in the app's Sharing, tap the member): they can still open links, and their pushes arrive without the other buttons.

Outbound action callbacks are unsigned. To authenticate the request, embed a bearer token in the callbackUrl itself (e.g. https://api.example.com/hook?key=…) or terminate the URL on a server that already trusts the server's egress IP (pushr cloud's, or your own Convex deployment's if you self-host).

Inbound webhook signing (provider → pushr) is unrelated and configured per provider — see Webhook adapters → Signing secrets below.

Caveat: lockscreen labels

iOS requires notification categories to be pre-registered, so the lockscreen banner shows generic labels (Action 1, Action 2, Reply). The mobile feed renders the real labels you sent and is where users normally respond.

Ack-or-escalate

Turn a notification into an on-call-style alarm that re-pushes at high priority — ignoring quiet hours — until the user taps it. A muted source app stays silent.

jsonc
{
  "title":    "DB disk > 90%",
  "body":     "homelab/prod",
  "priority": "high",
  "ack": {
    "timeoutSec":  60,        // 10–86400, seconds between re-pushes
    "maxAttempts": 5          // 1–20, total re-pushes after the initial send
  }
}
Try it: keep pinging until answered
On the phone
Wednesday, September 30
9:41
Send it, then acknowledge it, or let it ring.
maxAttempts
The request
json
{
  "title": "api-prod is down",
  "body": "5xx rate 38% across 3 regions",
  "ack": {
    "timeoutSec": 60,
    "maxAttempts": 3
  }
}
What pushr sends

Press Send to start.

Tapping the notification (or opening its url) acknowledges it and stops the loop. Un-acked notifications are listed at the top of the feed with an "ack needed" badge.

On-call escalation

When a source app is shared with teammates, its owner can set an on-call rotation in the app (source app → On-call). An urgent push then reaches the first person on call only, and one more person each time it goes unacknowledged, instead of waking everyone at once.

Try it: page whoever's on call
Three phones on the rotation
YouOn call
Quiet
Ana
Quiet
Bo
Quiet
The request
The same push you'd send without on-call.
json
{
  "title": "api-prod is down",
  "body": "5xx on 38% of requests",
  "priority": "high"
}
What happened

Send an urgent push to page You.

  • Urgent means a push with ack, or priority 7 or higher. Everything else still goes to everyone on the app.
  • Each round waits the push's ack.timeoutSec, or the app's Escalate after time (1 to 60 minutes) when the push has no ack. pushr adds an ack loop long enough to reach everyone on the rotation.
  • Acknowledging on any phone stops it for everyone.
  • Weekly rotation moves who's first along by one person each week.
  • Heartbeat and uptime alerts escalate the same way; their recoveries go to everyone.
  • On-call is a Pro feature on pushr cloud, and needs at least two people and at most 10.

Nothing changes in the request: the same /notify call pages one person or everyone, depending on the app's settings.

Critical alerts

A critical alert plays its sound even when the phone is muted or in Do Not Disturb, like a severe weather alert. Because it overrides the user's own settings, the sender can't turn it on alone: the source app's owner chooses in the app (source app → Critical alerts) which pushes may ring through:

SettingWhat rings through
Off (default)Nothing
Marked criticalPushes sent with "critical": true
All urgentThose, plus every push with ack or priority 7+, including heartbeat and uptime alerts
jsonc
{ "title": "Freezer above -10°C", "body": "Walk-in #2 · 4°C", "priority": "high", "critical": true }
  • Critical alerts ignore quiet hours. A muted source app stays silent.
  • Each phone also asks its owner's permission the first time it's turned on.
  • iOS rings through mute only once Apple has approved pushr's critical-alerts entitlement. Until then these pushes arrive as time-sensitive.
  • Critical alerts are a Pro feature on pushr cloud.

Replace keys

Some notifications describe a state that keeps changing: disk usage, a deploy, a queue's depth. Give them the same replaceKey and each one replaces the last instead of stacking up.

jsonc
{ "title": "Disk 91%", "body": "db-1 /var", "replaceKey": "disk-db-1" }
// …later
{ "title": "Disk 97%", "body": "db-1 /var", "priority": "high", "replaceKey": "disk-db-1" }
// …and once it's fixed
{ "title": "Disk OK",  "body": "db-1 /var · 62%", "replaceKey": "disk-db-1" }
Try it: replace instead of stack
On the phone
Wednesday, September 30
9:41
Send the first reading.
The request
json
{
  "title": "Disk 91%",
  "body": "db-1 /var",
  "replaceKey": "disk-db-1"
}
In the feed

Nothing sent yet.

  • On the phone, the earlier notification is removed from Notification Center when the new one arrives, so the Lock Screen shows only the latest.
  • In the feed, only the latest shows, marked Updated 2×. Tap it to see the timeline of earlier versions with their times.
  • The badge counts the latest only: replaced versions are marked read.
  • Each push is still a full notification, with its own sound, priority and quota. Use a lower priority for routine updates and high when it gets worse.
  • Keys are per source app, so two apps can use the same key safely.
  • Send a key at most every few seconds. Many sends a second under one key contend with each other and some can fail with a 500; for that pace, use a Live Activity.
  • A scheduled push (deliverAt) replaces its predecessor when it's delivered, not when you send it.
  • An ack stops escalating once its notification is replaced.
  • Deleting the latest version from the feed deletes its timeline too.

For progress you want to watch live, such as a build, use a Live Activity instead. A replace key suits things that change every few minutes or hours, where a notification for each change is worth it.

Scheduled delivery

jsonc
{
  "title":     "Standup",
  "body":      "Time to gather",
  "deliverAt": 1714435200000   // ms-epoch
}

Returns 202 { id, scheduledFor } immediately; delivery happens at the target time via the Convex scheduler.

Try it: send it later
On the phone
Wednesday, September 30
9:41
Arrives 5 s after you send it.
The request
json
{
  "title": "Standup",
  "body": "Time to gather",
  "deliverAt": 1714435205000
}
The response, right away
Nothing sent yet
Press Send.

Live Activities

Drive iOS lockscreen / Dynamic Island progress indicators. Three actions: start / update / end, all keyed by your own activityId. state is required on every action, and progress must be between 0 and 1.

jsonc
{
  "title": "Deploy #42",
  "body":  "Building",
  "liveActivity": {
    "action":     "start",                    // start | update | end
    "activityId": "deploy-42",                // caller-chosen, reused for update/end
    "attributes": { "name": "ci.example.com" }, // immutable, only on start
    "state": {                                  // mutable ContentState
      "title":    "Deploy #42",
      "status":   "Running tests",
      "progress": 0.35,                         // 0..1, omit for indeterminate
      "icon":     "hammer.fill"                 // SF Symbol name
    },
    "staleDate":      1712200000000,            // ms-epoch (optional)
    "relevanceScore": 0.8                       // 0..1 (optional)
  }
}

Update:

json
{
  "title": "Deploy #42",
  "body":  "Deploying to staging",
  "liveActivity": {
    "action":     "update",
    "activityId": "deploy-42",
    "state":      { "title": "Deploy #42", "status": "Deploying", "progress": 0.85 }
  }
}

End:

json
{
  "title": "Deploy #42",
  "body":  "Shipped 🎉",
  "liveActivity": {
    "action":     "end",
    "activityId": "deploy-42",
    "state":      { "title": "Deploy #42", "status": "Complete", "progress": 1.0 }
  }
}

start requires the device to have registered a push-to-start token (the mobile client does this on first launch). update/end can fire even if the app is terminated. Set the APNS_* environment variables on your Convex deployment to enable this end-to-end (see .env.example).

A push with liveActivity shows as the Live Activity instead of a notification banner, so each step doesn't arrive twice; every step still appears in the feed. The banner is sent instead only when the activity can't be shown: APNS_AUTH_KEY isn't configured, no device has a push-to-start token, or Apple rejects the start for every device. Updates and ends never send a banner.

Ending, and failing

End with "outcome": "failure" in state and the activity turns red so it can't be mistaken for a running one: a solid red Failed label, a red glow, an ✕ beside the status, and the bar and ring stopped in red where the job failed.

jsonc
{
  "title": "Build #43",
  "body":  "3 tests failed",
  "liveActivity": {
    "action":     "end",
    "activityId": "build-43",
    "state":      { "status": "3 tests failed", "progress": 0.55, "icon": "xmark.octagon.fill", "outcome": "failure" }
  }
}
state.outcomeShows asStays on the Lock Screen
"success", or a full bar with no outcomeDone, green15 minutes
"failure"Failed, redUntil dismissed, up to iOS's 4 hours

dismissAfter on an end sets how long a finished activity stays instead, in seconds from 0 (gone at once) to 14400. A failure ignores it and stays until it's dismissed, so a failed job is never cleared before someone sees it. Always end an activity, failure included: one that's never ended stays until iOS removes it, still saying it's running.

Try it: drive a Live Activity
On the phone
Wednesday, September 30
9:41
No activity yet. Send start to begin one.
  1. start
  2. update
  3. update
  4. end
Next request · start
json
{
  "title": "Deploy #42",
  "body": "Building image",
  "liveActivity": {
    "action": "start",
    "activityId": "deploy-42",
    "attributes": {
      "name": "ci.acme"
    },
    "state": {
      "title": "Deploy #42",
      "status": "Building image",
      "progress": 0.15
    }
  }
}

Every request reuses the same activityId. attributes only go with start; each step after that just sends the new state.

Choosing an icon

state.icon is the name of any SF Symbol, Apple's icon set. It shows in the Dynamic Island and beside the status on the Lock Screen, so pick one that says what the job is. Filled symbols (….fill) read best at that size. Leave it out, or send a name iOS doesn't know, and the Dynamic Island shows the initial of attributes.name instead.

Icon picker66 SF Symbols
Builds and deploys
Transfers and backups
Orders and deliveries
Time and tracking
Home and devices
Media
Status
hammer.fill
Dynamic Island
Lock Screen
Cci.example.comLive
Deploy #42
Running tests
35%

Filled symbols read best at this size. Leave icon out, or send a name iOS doesn't know, and the Dynamic Island shows your app's initial instead.

json
{
  "title": "Deploy #42",
  "liveActivity": {
    "action": "start",
    "activityId": "deploy-42",
    "attributes": {
      "name": "ci.example.com"
    },
    "state": {
      "title": "Deploy #42",
      "status": "Running tests",
      "progress": 0.35,
      "icon": "hammer.fill"
    }
  }
}

Heartbeats

A heartbeat catches the failure no notification can report: a job that silently stopped running. Your job pings pushr each time it finishes, and pushr pushes to your phone when a ping is late, or when the job reports a failure. When it pings again, a recovery replaces the alert.

bash
# crontab: back up at 03:00 and check in afterwards
0 3 * * * /usr/local/bin/backup.sh && curl -fsS -H "Authorization: Bearer $PUSHR_TOKEN" "$PUSHR_URL/heartbeat/nightly-backup?every=1d"
Try it: a nightly job checks in
On the phone
Wednesday, September 30
9:41
Run the job: its first ping creates the heartbeat.
Status
Not created yet
Last ping
–
Alerts if no ping by
–
The request
Each button is what the job (or you, in the app) does.
Press Job runs.
In the feed

No alerts yet.

The response
The server’s answer shows here.

The first ping creates the heartbeat, so there's nothing to set up in the app. It's watched from then on.

Endpoints

RequestMeaning
GET or POST /heartbeat/<name>The job ran. Starts a new window.
POST /heartbeat/<name>/startThe job started. The next ping reports how long it took. Optional.
POST /heartbeat/<name>/failThe job failed. Alerts at once; a text body (up to 500 characters) becomes the alert's text.
DELETE /heartbeat/<name>Stop watching it.

<name> is up to 64 letters, digits, dots, dashes or underscores, and is unique within the source app.

QueryNotes
everyHow often the job runs: seconds, or a number with s, m, h or d, from 1m to 30d. Required on the first ping; send it again to change it.
graceHow long past every to wait before alerting, up to 7d. Defaults to 20% of every, between 1 minute and 1 hour.

The response is 200:

json
{ "ok": true, "name": "nightly-backup", "status": "up", "everySec": 86400, "graceSec": 3600, "dueAt": 1714525200000 }

dueAt is when pushr alerts if no ping arrives. It's null while the heartbeat is down or paused.

What you get

EventNotificationPriority
No ping by dueAtnightly-backup missed its check-in · Expected every 1d. Last ping 1d 1h ago.high
/failnightly-backup failed · your body, or "The job reported a failure."high
A ping after eithernightly-backup is back up · Down for 2h 14m. Took 3m 12s.normal
  • One alert per outage: further misses and failures stay quiet until it recovers. A heartbeat that flaps sends at most 3 down alerts an hour; past that its status still changes, without a push. Each down alert that was sent gets its recovery.
  • Alerts come from the token's source app and use the replace key heartbeat:<name>, so the recovery replaces the alert and the feed keeps the history. They follow the app's mutes and quiet hours like any push, and don't count toward your monthly quota.
  • Lateness is checked every minute.
  • Ping as often as you like: pings don't count toward your quota, and repeats within 10 seconds are ignored.
  • On pushr cloud, Free includes 3 heartbeats and Pro 100, across all your apps; a single source app holds at most 50. Heartbeats made before a downgrade keep running.

Report failures and durations

Wrap the job to report all three:

bash
url="$PUSHR_URL/heartbeat/nightly-backup"
auth="Authorization: Bearer $PUSHR_TOKEN"
curl -fsS -X POST -H "$auth" "$url/start?every=1d"
if out=$(/usr/local/bin/backup.sh 2>&1); then
  curl -fsS -X POST -H "$auth" "$url"
else
  printf '%s' "$out" | tail -c 500 | curl -fsS -X POST -H "$auth" --data-binary @- "$url/fail"
fi

With the SDK, withHeartbeat reports the start, success or failure of a job for you, and never fails the job if pushr can't be reached:

ts
import { heartbeat, withHeartbeat } from '@pushrsh/sdk';

await withHeartbeat('nightly-backup', { every: '1d' }, runBackup);
await heartbeat('queue-worker', { every: '5m' }); // a plain check-in

In the app

The Monitors tab lists every heartbeat with its status and last ping, and + → Heartbeat creates one with copy-ready setup for cron, the CLI, curl or the SDK. Pause one during maintenance so it can't alert. Pings while it's paused are recorded but don't lift the pause, so a job that keeps running during maintenance stays quiet; Resume starts a fresh window.


Uptime checks

Heartbeats catch jobs that stop running. Uptime checks catch sites and APIs that stop answering: pushr requests a URL on a schedule and pushes to your phone when it fails, then again when it's back.

bash
curl -X PUT "$PUSHR_URL/uptime/api" \
  -H "Authorization: Bearer $PUSHR_TOKEN" \
  -d '{"url":"https://api.example.com/health","every":"1m","keyword":"ok"}'
Try it: an API stops answering
On the phone
Wednesday, September 30
9:41
Quiet while every check passes.
The check
json
{
  "url": "https://api.example.com/health",
  "every": "1m",
  "keyword": "ok",
  "confirmAfter": 2
}
Each minute's check
Pending
  • Press a button to run a check.

Failures in a row: 0 of 2

You can also add and edit checks in the app: Monitors → + → Uptime check tests the URL as you type.

The check

FieldNotes
urlhttp or https, on a public host. The name is looked up before every check, and an address that's private, loopback or link-local, or a name that points to one, is refused. Redirects aren't followed.
everyHow often to check: 1m to 1h (seconds, or a number with s, m or h). On pushr cloud's Free plan, every 5 minutes at most.
methodGET (default) or HEAD.
keywordText the response body must contain, up to 200 characters. Not with HEAD.
timeoutSeconds to wait for a response, 1 to 30. Default 10.
confirmAfterFailed checks in a row before it alerts, 1 to 5. Default 2, so one blip doesn't page you.

A check passes when the response status is below 400 (redirects aren't followed, so a 301 passes) and, with keyword, the body contains it. It fails on a status of 400 or more, a missing keyword, an error, or no response within timeout.

PUT creates the check or changes it, and answers 200 with its state; GET answers the same; DELETE removes it:

json
{
  "ok": true, "name": "api", "url": "https://api.example.com/health", "method": "GET",
  "intervalSec": 60, "timeoutSec": 10, "keyword": "ok", "confirmAfter": 2,
  "status": "up", "lastCheckedAt": 1714525200000, "lastStatusCode": 200,
  "lastLatencyMs": 182, "lastError": null, "downSince": null
}

status is pending until the first check, then up, down or paused. The name follows the same rules as a heartbeat's.

What you get

EventNotificationPriority
confirmAfter failures in a rowapi is down · HTTP 503 · api.example.com/healthhigh
The next passing checkapi is back up · Down for 12m. Responded in 182ms.normal

Alerts work like a heartbeat's: one per outage, at most 3 down alerts an hour, the recovery replaces the alert (replace key uptime:<name>), and they follow the app's mutes, quiet hours, on-call and critical alerts. They don't count toward your quota. Checks come from pushr's servers (your own Convex deployment, if you self-host) with the user agent pushr-uptime/1.

FreePro
Uptime checks150
Most oftenEvery 5 minutesEvery minute

After a move from Pro to Free nothing is deleted. Your oldest check keeps running, no faster than every 5 minutes; the others are on hold and start again by themselves when you upgrade.


Status pages

A status page shows some of an app's heartbeats and uptime checks to anyone, at status.pushr.sh/<slug>: whether each is up now, 90 days of uptime, and recent incidents. Create one in the app (Monitors → + → Status page), choose its address, title and monitors, and give each monitor a public name if you like. Addresses are 3 to 40 lowercase letters, digits or dashes; a few, such as docs and status, are reserved. pushr's own status is at the root, status.pushr.sh.

Try it: a status page
status.pushr.sh/acme

Acme status

All systems operational

Live status for the Acme API and dashboard.

acme.com

Services

API

Operational
30 days ago100.00% uptimeToday

Website

Operational
30 days ago99.98% uptimeToday

Jobs

Nightly backup

Operational
30 days ago100.00% uptimeToday
Take a monitor down
GET /status-page/acme
json
{
  "title": "Acme status",
  "description": "Live status for the Acme API and dashboard.",
  "accent": "#14B8A6",
  "websiteUrl": "https://acme.com",
  "announcement": null,
  "overall": "operational",
  "monitors": [
    {
      "label": "API",
      "group": "Services",
      "kind": "uptime",
      "status": "up",
      "uptime": 0.9985,
      "days": "… 90 days"
    },
    {
      "label": "Website",
      "group": "Services",
      "kind": "uptime",
      "status": "up",
      "uptime": 1,
      "days": "… 90 days"
    },
    {
      "label": "Nightly backup",
      "group": "Jobs",
      "kind": "heartbeat",
      "status": "up",
      "uptime": 0.9958,
      "days": "… 90 days"
    }
  ]
}

Branding

Out of the box a page uses the source app's logo and color. In the page's editor you can also set:

OptionNotes
LogoUpload one for the page, or keep the app's.
Accent colorTints the page's banner and highlights. Status colors stay green, amber and red.
ThemeAuto (follows the visitor), light or dark.
WebsiteA link back to your site at the top.
DescriptionA line under the title, up to 160 characters.
AnnouncementPinned at the top until you clear it, up to 280 characters: info, maintenance or warning.
GroupsName a group on monitors to show them under headings, like API and Jobs.

Visitors never see URLs, error messages or a job's output: an incident reads as Failed, Missed its check-in, HTTP 503, Timed out or Not responding.

Incidents

Every outage of a monitor on the page is an incident. Outages that overlap across the page's monitors (or start within two minutes of each other) are one incident, like API and Website. Each opens to a timeline of what the checks saw: when the first check failed (or a heartbeat's check-in was due), when it was confirmed down, and when it came back, with the status code and response time. The page lists 90 days of them, newest first, grouped by day.

Updates. Tell visitors what's happening. In the dashboard or the app, open a monitor, then its incident: give it a title (up to 80 characters, like Checkout errors) and post updates as it goes, each marked Investigating, Identified, Monitoring or Resolved, up to 1,000 characters. Anyone who can edit the app can post, so whoever's on call can; an AI agent can too, with the incident_update tool. An incident holds up to 30 updates. The latest update's status is the incident's on the page; without one it shows Ongoing or Resolved. Updates are part of Pro, with status pages, and go with the incident: after 90 days, or when its monitor or app is deleted.

The page's data is public JSON, for your own page or a widget:

Plain
GET $PUSHR_URL/status-page/<slug>
json
{
  "title": "Acme status",
  "description": "Live status for Acme's API and dashboard.",
  "logoUrl": "https://…", "accent": "#3E7BFA", "theme": "auto",
  "websiteUrl": "https://acme.com",
  "announcement": { "text": "Maintenance Sunday 2–3am UTC", "tone": "maintenance", "updatedAt": 1714500000000 },
  "overall": "operational",
  "updatedAt": 1714525200000,
  "monitors": [
    {
      "label": "API", "group": "Services", "kind": "uptime", "status": "up", "downSince": null,
      "uptime": 0.9994,
      "days": [{ "date": "2026-07-05", "downMs": 0 }, "… 90 days, oldest first"]
    }
  ],
  "incidents": [
    {
      "title": "Checkout errors", "status": "resolved",
      "monitor": "API and Website", "reason": "HTTP 503",
      "startedAt": 1714500000000, "endedAt": 1714500720000,
      "monitors": [
        {
          "label": "API", "reason": "HTTP 503", "startedAt": 1714500000000, "endedAt": 1714500720000,
          "firstFailedAt": 1714499940000, "statusCode": 503, "latencyMs": 41,
          "recoveredStatusCode": 200, "recoveredLatencyMs": 96
        },
        "… one per monitor in the incident"
      ],
      "updates": [
        { "status": "investigating", "body": "Some checkouts are failing. We're looking into it.", "at": 1714500180000 },
        { "status": "resolved", "body": "Fixed. Sorry for the trouble.", "at": 1714500780000 }
      ]
    }
  ]
}
  • overall is operational, degraded (some monitors down) or outage (all of them).
  • days[].downMs is -1 for days before the monitor existed.
  • uptime is over the last 90 days, or since the monitor was created.
  • incidents are newest first, up to 50 from the last 90 days. endedAt is null while one is going on. title and status are null until someone writes an update; status is the latest update's. monitor (the monitors' names joined) and reason (the first outage's) are kept for readers of the older shape. firstFailedAt, statusCode and the recovered… fields are null when the check didn't see one (heartbeats have no status code).
  • Answers 404 for an unknown or disabled page, and may be cached for 30 seconds.
  • Status pages are a Pro feature on pushr cloud, up to 5 per account. After a move to Free a page is kept but offline (404), and comes back when you upgrade.
  • Self-hosted servers serve the JSON only; the app doesn't offer status pages there, since status.pushr.sh shows pushr cloud's pages.

Other ways to send

Webhook adapters

Forward provider webhooks straight to pushr without writing glue code. Adapters normalize the provider payload into the same internal shape and flow through the same delivery / quota / ack plumbing.

Plain
POST /hooks/github?token=$PUSHR_TOKEN
POST /hooks/sentry?token=$PUSHR_TOKEN
POST /hooks/grafana?token=$PUSHR_TOKEN

Auth: either Authorization: Bearer $PUSHR_TOKEN (when the provider lets you customize headers) or ?token=$PUSHR_TOKEN in the query string. Payloads must be JSON; a form-encoded delivery gets 400 Invalid JSON body.

Try it: what a webhook becomes
On the phone
Wednesday, September 30
9:41
Cci.example.comnowacme/api: 3 commits → mainFix flaky checkout test
Priority 5
Paste into GitHub
https://<deployment>/hooks/github?token=pshr_…
  1. 1Repo or org → Settings → Webhooks → Add webhook
  2. 2Payload URL: the URL above
  3. 3Content type: application/json
  4. 4Secret: the one you save in the app
GitHub sends · X-GitHub-Event: push
json
{
  "ref": "refs/heads/main",
  "commits": [
    {
      "message": "Fix flaky checkout test"
    },
    {
      "message": "Bump deps"
    },
    {
      "message": "Tidy logs"
    }
  ],
  "repository": {
    "full_name": "acme/api"
  },
  "sender": {
    "login": "ana"
  }
}
pushr answers
202 { "id": "k57…", "scheduledFor": null }

Signing: X-Hub-Signature-256: sha256=<hex>

GitHub

Paste $PUSHR_URL/hooks/github?token=$PUSHR_TOKEN into your repo or org webhook settings. Set the content type to application/json (GitHub defaults to form-encoded). Subscribe to events you care about:

EventSent whenTitlePriority
pushAlways"{repo}: N commits → {branch}"5
pull_requestOpened, reopened, ready for review, closed"{repo} PR #N {opened|merged|closed}"6 when opened, else 5
issuesOpened or reopened"{repo} issue #N {action}"5
releasePublished"{repo} release {tag}"7
workflow_runFailed or timed out"{repo}: {name} failed"8
check_runFailed or timed out"{repo}: {name} failed"8
deployment_statusFinished (not queued or in progress)"{repo}: deploy to {env} → {state}"8 on failure or error, else 6
Any other eventAlways"{repo}: {event}"5

Everything else (other pull_request and issues actions, releases that aren't published, successful runs, deployments still queued or in progress, and ping) is acknowledged with 200 { ignored: true } and sends nothing.

To sign deliveries, open the source app in the iOS app → API & token → Webhooks → GitHub and paste the same secret you set in GitHub. Once it's saved, pushr checks X-Hub-Signature-256 on every delivery and a mismatch returns 401.

Sentry

Add an Internal Integration (or legacy plugin webhook) at /hooks/sentry?token=…. An issue becomes {project}: {action} — {title} with its culprit as the body; an alert uses the event's own title; a legacy plugin webhook is sentry: {project}. A payload of any other shape is acknowledged with 200 { ignored: true }. Severity maps to pushr priority:

Sentry levelpushr priority
debug2
info4
warning6
error8
fatal9
anything else5

To verify Sentry signatures, set the integration's client secret in API & token → Webhooks → Sentry. Once it's saved, pushr checks Sentry-Hook-Signature (bare hex HMAC-SHA256 of the raw body) on every delivery.

Grafana

Contact point → Webhook → URL $PUSHR_URL/hooks/grafana?token=…. The adapter collapses the alert batch into one push titled <ruleName> (<n> firing), or <ruleName> resolved at priority 4 once it clears. commonLabels.severity (else the first alert's severity label) sets the priority: info 5, warning 6, high/error 8, critical/emergency 9; anything else is 6. Grafana doesn't HMAC-sign webhook payloads, so the bearer token is the only authenticator — keep the URL private.

Signing secrets

A single source app can be wired to multiple providers — each with its own signing secret. Configure them independently in API & token → Webhooks.

ProviderHeaderFormatNotes
GitHubX-Hub-Signature-256sha256=<hex>Required when set
SentrySentry-Hook-Signaturebare <hex>Required when set
Grafana——Bearer-only (no signing)

When a secret is set for a provider that supports signing, every inbound delivery to /hooks/{provider} must carry a valid signature or pushr returns 401 { error: "Invalid signature" }. Clearing the secret falls back to bearer-only auth.

Adapter response

CodeBodyWhen
202{ id, scheduledFor: null }Adapter normalized the event and the push was queued.
200{ ignored: true, provider }The adapter chose to ignore this event (e.g. GitHub ping).

Errors are listed under Errors and retries.

CLI and SDK

Both read PUSHR_URL and PUSHR_TOKEN from the environment and call POST /notify for you.

CLI (brew install cpreston321/tap/pushrsh):

bash
pushrsh "Deploy finished" "main → production" -p high
tail -n 5 deploy.log | pushrsh "Cron failed"         # stdin becomes the body
pushrsh "PR ready" "+812 / -96" -a "View=https://github.com/owner/repo/pull/318"
pushrsh la start deploy-42 --title "Deploy #42" --status Building --progress 0
pushrsh "Disk 94%" "db-1 /var" -r disk-db-1           # replaces the last disk-db-1
pushrsh hb nightly-backup --every 1d -- ./backup.sh    # heartbeat around a command
pushrsh uptime api https://api.example.com/health --every 1m --keyword ok

pushrsh hb NAME -- COMMAND runs the command between a start and a success or fail ping, sends the last 500 characters of its output on failure, and exits with the command's status.

TypeScript SDK (bun add @pushrsh/sdk, any fetch runtime):

ts
import { notify, liveActivity, withHeartbeat } from "@pushrsh/sdk";

await notify({ title: "New sale", body: "$42 from Acme", priority: 9 });

const la = liveActivity("deploy-42");
await la.start({ status: "Building", progress: 0 });
await la.end({ status: "Live" });

await withHeartbeat("nightly-backup", { every: "1d" }, runBackup);

Gotify compatibility

pushr accepts Gotify's message and extras click URL. See From Gotify or iGotify for the full mapping.


Connect AI agents

pushr is an MCP server, so Claude, ChatGPT, Cursor and other AI agents can reach you on your iPhone: ask before they do something you'd want a say in, wait for your tap, tell you when they're done, and show long tasks on your Lock Screen. There's no token to copy: the agent signs in to your pushr account, and you choose which apps it may use. This is a pushr cloud feature.

Add pushr to your agent

Server addresspushr cloud
https://mcp.pushr.sh

Also answers at https://mcp.pushr.sh/mcp, and at https://pushr.sh/mcp for agents connected before. No token to paste: the agent signs in to your account.

  1. 1Open Settings›Connectors›Add custom connector
  2. 2Paste , name it pushr
  3. 3Sign in when Claude opens pushr, and choose the apps it may use

On claude.ai, Claude Desktop and the Claude mobile apps.

The agent opens pushr.sh/connect in your browser:

  1. 1Sign in

    With your pushr email and password, or Email me a sign-in link if you made your account with Apple. Accounts are made in the app.

  2. 2Choose the apps

    The agent sends as these apps and can read their monitors. With more than one, it picks the app for each message.

  3. 3Allow

    You’re sent back to the agent, connected. Settings → AI agents in the app lists it.

The app's Settings → AI agents lists what's connected, which apps each one uses and when it was last used. Tap one to disconnect it; it has to sign in again to come back. Deleting an app removes it from every agent.

The tools

askwaits for you

Pushes a question with a button for each choice (Approve and Reject unless it gives others, up to 4) and an optional Reply, then waits for your tap. urgent: true pushes it again every minute, up to 5 times, until you answer.

titlebodychoicesreplyurgenturlwait_seconds
Claude · DeploysnowDeploy main to production?4 commits, tests green.
Agent getsWaiting
{"status": "waiting","id": "q_8f2c41"}
get_answer

Keeps waiting for, or checks, the answer to an ask.

idwait_seconds
notify

Sends a notification, like POST /notify.

titlebodypriorityurlreplace_key
progress

Shows a task as a Live Activity. Call it again with the same id to move it on; outcome success or failure ends it.

idtitlestatusprogressoutcome
monitors

The state of the chosen apps’ uptime checks and heartbeats, worst first.

incident_updatePro

Posts an update to a monitor’s current or latest status page incident, within the last day. Needs edit access to the app.

monitorstatusmessagetitle

ask, notify and progress take an app argument when the agent has more than one app. It only ever sees the apps you chose.

How ask waits
  1. ask0sThe question lands on your phone and in the feed.
  2. One call waitsup to 90swait_seconds, at most 240. The first tap is the answer.
  3. get_answerafterNo tap yet: the agent gets the id and keeps waiting. It never assumes an answer.

A late tap still counts. The buttons work like action buttons, with no callback URL: the answer goes straight back to the agent.

Plans

Each ask, notify and progress step is a notification, and counts toward your monthly pushes.

An app paused on the Free plan can’t send, and the agent is told why.


Use with AI agents

pushr ships agent skills: task-focused guides that teach coding agents (Claude Code, Cursor, Codex and others) how to integrate pushr the right way, from picking a priority to building a callback endpoint. Install them into your project once, then just ask.

Set up the skills

  1. 1
    Add your credentials
    Put PUSHR_URL and PUSHR_TOKEN in the project’s .env and your CI secrets. The skills read them from the environment, like the SDK and CLI, and never paste a token into code.
  2. 2
    Install the skills
    $ npx skills add cpreston321/pushr-backend
    Then choose which agents get them. For Claude Code by hand, copy the folders from skills/ into .claude/skills/, or ~/.claude/skills/ for every project.
  3. 3
    No skills support?
    Give your tool the docs instead: add https://pushr.sh/llms-full.txt as a docs source (in Cursor, @Docs → Add new doc), or this line to your AGENTS.md or CLAUDE.md: For push notifications, follow https://pushr.sh/llms.txt
  4. 4
    Check it works
    Ask your agent “Send me a test push with pushr.” A notification should arrive on your phone.

The skills

pushr-notify

Setup and secrets, request fields, choosing a priority, replace keys, the SDK, CLI, Python, Go and GitHub Actions, errors and safe retries

Notify my phone when this build finishesPing me if the nightly backup fails
pushr-actions

Buttons and replies, the callback request, building and securing the endpoint (Hono, Express, Next.js, FastAPI), approval gates

Let me approve this deploy from my phoneAdd a Retry button to the failure alert
pushr-live-activities

Start, update and end, choosing an icon, always ending on failure, update pacing

Show this upload’s progress on my Lock ScreenTrack the deploy in the Dynamic Island
pushr-alerts

Urgency levels, ack-or-escalate, on-call rotations, critical alerts, quiet hours and mutes, GitHub, Sentry and Grafana webhooks with signing

Wake me up if prod goes downSend failed GitHub workflows to my phone
pushr-heartbeats

Heartbeats for cron jobs and workers, uptime checks for sites and APIs, status pages, the CLI wrapper, SDK and CI

Tell me if the nightly backup stops runningAlert me if the API goes down
pushr-types

Drop-in TypeScript types and a dependency-free client with idempotent retries, Python types, a Zod schema

Add a typed pushr client without the SDKValidate pushr payloads

The agent loads the right skill from what you ask, so you don’t need to name it. Each reads PUSHR_URL and PUSHR_TOKEN from the environment.

Docs for LLM tools

pushr.sh/llms.txtAn index of the docs and skills, in the llms.txt format
pushr.sh/llms-full.txtThis whole reference plus every skill, in one file
pushr.sh/docs.mdThis reference as plain Markdown
pushr.sh/skills/<skill>/SKILL.mdOne skill, like pushr-notify

All of them are generated from this page, so they stay in step with it.


Errors and retries

Status codes

Every error body has an error string; some also carry a code to branch on.

400error: "<reason>"Validation error: missing fields or a bad shape.Fix, don’t retry
401Invalid token / Missing bearer tokenBad or absent token.Fix, don’t retry
401Invalid signatureThe provider’s signature didn’t match the signing secret you set.Fix, don’t retry
403Source app disabledThe token is valid, but the app was turned off.Fix, don’t retry
403APP_PAUSEDpushr cloudThe app is on hold: the account is on Free with more apps than Free allows. Choose the active app in the iPhone app, or upgrade.Fix, don’t retry
409IDEMPOTENCY_KEY_REUSEDThe Idempotency-Key was used with a different payload.Fix, don’t retry
400EVERY_REQUIREDThe first ping to a new name didn’t say every.Fix, don’t retry
404errorNot /heartbeat/<name>, /start or /fail, or a DELETE of a name that doesn’t exist.Fix, don’t retry
403PRO_REQUIREDpushr cloudA new heartbeat past Free’s 3.Fix, don’t retry
409HEARTBEAT_LIMITPro’s 100, or 50 on one source app, are in use.Fix, don’t retry
403PRO_REQUIREDpushr cloudA second check, or checking more often than every 5 minutes, on Free.Fix, don’t retry
409UPTIME_LIMITThe account already has 50 uptime checks.Fix, don’t retry
429QUOTA_EXCEEDEDpushr cloudThe month’s pushes are used up; it resets on the 1st (UTC). See Rate limits and quotas.Next month
500error: "<message>"Unexpected server error.Retry with a key

Retries and Idempotency-Key

Send an Idempotency-Key header (any string up to 255 characters, such as a job id or UUID) to make retries safe:

bash
curl -X POST "$PUSHR_URL/notify" \
  -H "Authorization: Bearer $PUSHR_TOKEN" \
  -H "Idempotency-Key: deploy-482-finished" \
  -d '{"title":"Deploy #482 finished"}'
200Same key, same bodyThe original id comes back with Idempotent-Replay: true. Not pushed again, and not counted.
409Same key, different bodyA bug in the sender, not a retry, so it’s refused.
24h+How long keys lastKeys are per source app, remembered for at least a day.

GET /healthz

Plain
GET /healthz
json
{ "ok": true, "version": "0.1.0", "selfHosted": false, "appleSignIn": true }

version is the backend release, and appleSignIn says whether Sign in with Apple is enabled on this server. A self-hosted server answers "selfHosted": true, with appleSignIn false unless you've enabled it. Use this from a monitor to check that your deployment is reachable.


Tokens and limits

Source-app token format

Tokens always start with pshr_ followed by a base64url payload. They're shown once at creation time in the mobile app's Apps tab — the server only stores the sha256(token) hash. Revoking an app invalidates its token for good; rotating the token issues a new one and invalidates the old.

tokenPrefix (e.g. pshr_abcd1234) is safe to display in logs and CI config; the full token is not.

Rate limits and quotas

Self-hosted: there are no plans and no push quota. Every account on your deployment gets every feature. A few fixed limits remain: 50 uptime checks per account, 50 heartbeats per source app, and notification history is kept 90 days (a daily sweep deletes older pushes).

Push limits, on both: each source app can send 120 pushes a minute; past that, /notify answers 429 with code: "RATE_LIMITED" and a Retry-After header. title is at most 256 characters, body 4096, url, image, appUrl and action URLs 2048, an action's label and id 64, and data 4 KB as JSON. url and image must be http or https; appUrl and open_url actions may use any app scheme (myapp://…) but never javascript:, data:, file: or vbscript:. Provider webhooks (/hooks/*) have over-long titles and bodies shortened instead of refused.

Logos, for an app or a status page, are PNG, JPEG, WebP or HEIC images up to 5 MB. An upload that isn't attached to an app or page within a day is deleted.

Signing in, on both: after 10 wrong passwords for one email address within 15 minutes, password sign-in for that address answers 429 with code: "TOO_MANY_SIGN_IN_ATTEMPTS" until the 15 minutes pass. Password reset and Sign in with Apple still work, and signing in before the limit starts the count over.

pushr cloud
Free
  • Pushes per month1,000
  • Source apps1
  • History7 days
  • People per shared app1
  • Quiet hours, Slack and Discord forwarding—
  • Uptime checks1, every 5 minutes
  • Heartbeats3
  • Status pages—
  • On-call escalation and critical alerts—
ProPRO
  • Pushes per month10,000
  • Source appsUnlimited
  • History90 days
  • People per shared appUnlimited
  • Quiet hours, Slack and Discord forwarding✓
  • Uptime checks50, every minute
  • Heartbeats100
  • Status pages5
  • On-call escalation and critical alerts✓

Past the monthly limit, /notify answers 429:

json
{
  "error": "Monthly quota exceeded",
  "code": "QUOTA_EXCEEDED",
  "tier": "free",
  "count": 1000,
  "limit": 1000
}

The count resets at the start of each month (UTC). Replays with an Idempotency-Key don't count.


Migrating from other apps

Every guide below ends the same way: create a source app in the iPhone app (Apps → +), copy its token, and send JSON to POST /notify with Authorization: Bearer $PUSHR_TOKEN. A source app plays the part of a Pushover application, an ntfy topic, a Gotify app or a Hark service: give each sender its own, with its own name, logo and colour.

From Pushover

Form fields → JSONA Pushover application becomes a pushr source app

Same idea, one less key: there's no user key, and emergency priority becomes an alert that repeats until you acknowledge it.

  1. 1Make a source app for each Pushover application
  2. 2Send JSON to /notify with its token as a bearer header
  3. 3Map message to body and the priorities below
Before · Pushover
bash
curl -s https://api.pushover.net/1/messages.json \
  --form-string "token=$APP_TOKEN" \
  --form-string "user=$USER_KEY" \
  --form-string "title=Backup failed" \
  --form-string "message=exit 2" \
  --form-string "priority=1"
After · pushr
bash
curl -X POST "$PUSHR_URL/notify" \
  -H "Authorization: Bearer $PUSHR_TOKEN" \
  -d '{
    "title":    "Backup failed",
    "body":     "exit 2",
    "priority": "high"
  }'
Same idea, new name4
  • titletitle
  • messagebody
  • urlurl
  • Priority -2 -1 0 11 3 5 8
Works a little differently7
  • token (application)The source app's token, as a bearer header
  • user or group keyNot needed: a push reaches everyone the source app is shared with
  • priority=2 with retry, expire"high" plus ack: timeoutSec = retry, maxAttempts = expire ÷ retry (up to 20). See Ack-or-escalate
  • url_titleAn open_url action with your label
  • soundChosen per priority level in Settings → Sounds
  • attachment uploadimage, a public URL
  • deviceChosen on the phone instead: each person switches delivery off for any of their devices in Settings → Devices
Not in pushr1
  • html, ttl, timestampNot available
What you get by switching✓Live Activities✓Approve and reply buttons✓Uptime checks✓Self-host for free

From ntfy

Headers → JSONA ntfy topic becomes a pushr source app

Instead of a topic and headers, send one JSON object. Priorities, links, images, buttons and delays all have a direct match.

  1. 1Make a source app for each topic
  2. 2Move the headers into a JSON body on /notify
  3. 3Swap the topic or tk_ token for the source app's token
Before · ntfy
bash
curl -H "Title: Backup failed" \
     -H "Priority: high" \
     -H "Click: https://homelab.lan" \
     -d "exit 2" ntfy.sh/homelab-backups
After · pushr
bash
curl -X POST "$PUSHR_URL/notify" \
  -H "Authorization: Bearer $PUSHR_TOKEN" \
  -d '{
    "title":    "Backup failed",
    "body":     "exit 2",
    "priority": "high",
    "url":      "https://homelab.lan"
  }'
Same idea, new name5
  • Message (request body)body
  • Titletitle, required
  • Clickurl
  • Attach (a URL)image
  • Priority 1…51 3 5 8 10
Works a little differently5
  • Topic in the URLA source app, with its own token
  • Actions viewAn open_url action
  • Actions httpA callback action: a POST with pushr's JSON, no custom method or headers
  • Delay / AtdeliverAt, in milliseconds
  • GitHub, Grafana templatesWebhook adapters for GitHub, Grafana and Sentry
Not in pushr2
  • Tags (emoji)Put the emoji in the title
  • Markdown, Email, CallNot available

Piping into curl -d? The CLI reads stdin the same way: tail -n 5 backup.log | pushrsh "Backup failed"

What you get by switching✓Buttons that work on iOS✓Live Activities✓Repeat until acknowledged✓Uptime checks

From Gotify or iGotify

New URL and headerA Gotify app becomes a pushr source app

pushr already reads Gotify's field names, so most senders only need a new address and header. No Gotify server to run, and no iGotify bridge.

  1. 1Make a source app for each Gotify app
  2. 2Point the sender at /notify instead of /message
  3. 3Send the token as Authorization: Bearer
Before · Gotify
bash
curl -X POST "https://gotify.lan/message?token=$APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title":    "Backup failed",
    "message":  "exit 2",
    "priority": 8
  }'
After · pushr
bash
curl -X POST "$PUSHR_URL/notify" \
  -H "Authorization: Bearer $PUSHR_TOKEN" \
  -d '{
    "title":    "Backup failed",
    "message":  "exit 2",
    "priority": 8
  }'
Same idea, new name3
  • title, messagetitle (required), message or body
  • Priority 1…10The same scale
  • extras client::notification click.urlurl
Works a little differently3
  • ?token= or X-Gotify-KeyAuthorization: Bearer
  • Priority 0Rejected: send 1, or leave priority out
  • bigImageUrlNot read: send image
Not in pushr1
  • client::display MarkdownBodies are plain text
What you get by switching✓A hosted option✓Live Activities✓Approve and reply buttons✓Repeat until acknowledged

From Hark

Same fields, new URLA Hark service becomes a pushr source app

Both are webhook-to-iPhone services, so most fields carry straight over. Prompts become buttons, and Live Activities become a field on /notify.

  1. 1Make a source app for each Hark service
  2. 2Send to /notify with its token instead of the webhook URL
  3. 3Turn prompts into buttons, as below
Before · Hark
bash
curl -X POST https://hark.ryan.ceo/hooks/whk_your_token \
  -H "Content-Type: application/json" \
  -d '{
    "title": "GitHub",
    "body":  "Production deployed"
  }'
After · pushr
bash
curl -X POST "$PUSHR_URL/notify" \
  -H "Authorization: Bearer $PUSHR_TOKEN" \
  -d '{
    "title": "GitHub",
    "body":  "Production deployed"
  }'
Same idea, new name2
  • body, title, urlThe same, but title is required
  • Idempotency-KeyThe same header
Works a little differently7
  • response approval, yes_noTwo callback actions, the risky one destructive
  • response textA reply action
  • callback.tokenPut it in the callbackUrl: callbacks are unsigned
  • imageUrl avatarThe source app's logo, set once in the app
  • projectOne source app per project
  • Withdraw a notificationSend a newer one with the same replaceKey
  • deviceIdsChosen on the phone instead of per push: each person switches delivery off for any of their devices in Settings → Devices, and a source app can be muted or given quiet hours
Live Activities4

One endpoint instead of three: send liveActivity.action start, update or end on /notify, with an activityId you choose. See Live Activities.

  • title, status, progressstate.title, state.status, state.progress
  • symbolstate.icon, any SF Symbol
  • Failure on endstate.outcome: "failure"
  • accentColor, style, ifSequenceNot available
Not in pushr2
  • Reading a response over HTTPAgents wait with ask
  • bodyFormat Markdown, summaryNot available

harkctl notify becomes pushrsh "Title" "Body" and harkctl activity becomes pushrsh la. For coding agents, add https://mcp.pushr.sh to Claude, ChatGPT or Cursor and they ask with ask.

What you get by switching✓Free buttons and replies✓Repeat until acknowledged✓Uptime checks and status pages✓Self-host for free

Self-hosting

pushr's backend is open source. You can run it on your own Convex deployment and point the iPhone app at it, so your notifications never touch pushr's servers. Self-hosted backends have no plans or push quota: every feature is unlocked, for free, within a few fixed limits.

What you need

Choose your path

Both run the same pushr backend. Pick one and every step below shows only what applies to it; you can switch at any time.

Then, in five steps
  1. 1Create your deploymentClone, install, deploy
  2. 2Set the server secretsBETTER_AUTH_SECRET, SITE_URL
  3. 3Create your accountseed:createAdmin
  4. 4Connect the appServer settings and a code
  5. 5Send a pushcurl your own /notify

1Create your deployment

Convex cloud
bash
git clone https://github.com/cpreston321/pushr-backend
cd pushr-backend
bun install
bun run dev

The first bun run dev signs you in to Convex, creates a deployment and pushes the schema and functions. It writes CONVEX_URL (ends in .convex.cloud) and CONVEX_SITE_URL (ends in .convex.site) to .env.local. You'll need both.

2Set the server secrets

These live in the Convex deployment, not in .env.local:

Convex cloud
bash
bunx convex env set BETTER_AUTH_SECRET "$(openssl rand -hex 32)"
bunx convex env set SITE_URL "https://<your-deployment>.convex.site"

3Create your account

bash
bunx convex run seed:createAdmin '{"email":"you@example.com","password":"<a strong password>"}'

4Connect the app

Convex cloud
  1. In pushr, open Settings → Server.
  2. Under Custom Convex Deployment, paste your .convex.cloud URL. The .convex.site URL is filled in from it.
  1. Tap Test connection. It checks that /healthz answers from your deployment.

  2. Make a connection code on the computer you deploy from, and type it into the app:

    bash
    bunx convex run pairing:createCode
    # { "code": "P4QM-2B2V", "expiresInMinutes": 15 }
  3. Tap Save & sign out. The app switches to your server right away; sign in with the account from step 3.

Connection codes

A self-hosted server only accepts new accounts that its owner lets in, so it can't quietly turn into a public pushr. Only someone with access to the Convex deployment can run pairing:createCode. Each code:

  • lasts 15 minutes and works once;
  • lets one new account sign up, in the app or with Sign in with Apple, within the next hour;
  • isn't needed for accounts that already exist, or for ones you make with seed:createAdmin.

After 20 wrong codes in 15 minutes, /pair answers further wrong codes with 429 (PAIRING_LOCKED) until the window passes. A real code always works.

The server's owner is any account seed:createAdmin made; run it again with an existing account's email to make that account an owner too. On a server set up before owners were recorded, the first account is the owner. Anyone on the server can share an app with someone who already has an account, but only the owner's invites let someone new sign up without a code.

To go back, return to the same screen and tap Use pushr cloud.

If you change BETTER_AUTH_SECRET

The key that signs the app's Convex tokens is stored encrypted with the secret. After changing it, sign-in still works but the app can't load anything, and the logs show Failed to decrypt private key. Generate a new key with:

bash
bunx convex run maintenance:resetAuthKeys

5Send a push

Create a source app in the Apps tab and copy its token, then:

Convex cloud
bash
curl -X POST "https://<your-deployment>.convex.site/notify" \
  -H "Authorization: Bearer $PUSHR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Hello","body":"from my own server"}'

Updating

Pull the latest source and run bun run push: it updates the deployment from step 1, the one your app and variables are on. Schema changes deploy with the functions; there's no separate migration step. If you run a separate production deployment (bun run deploy), it starts empty: set its variables with bunx convex env set --prod …, create your account with bunx convex run --prod seed:createAdmin …, point the app at its URLs, and update it with bun run deploy.

Differences from pushr cloud

  • Live Activities are not available with the App Store app. Starting and updating them needs an APNs key from the team that publishes the app. A push with liveActivity is still accepted and arrives as a normal push. Everything else (pushes, actions, ack-or-escalate, widgets, webhooks) works.
  • Delivery goes through Expo's push service, the same as pushr cloud. Your server only needs outbound HTTPS.
  • Plans don't apply. Pro features are on for every account on your deployment.
  • AI agents connect to pushr cloud only. mcp.pushr.sh signs in to a pushr cloud account. On your own server, agents send with the skills, SDK or CLI and a token instead.
  • Status pages are served as JSON at /status-page/<slug> on your deployment; the status.pushr.sh/<slug> page shows pushr cloud's pages only.
  • The web dashboard works with your server. At app.pushr.sh, choose Change server and enter your .convex.cloud address, then sign in with your email and password (no emailed links or Apple there). Status pages and plans are hidden. The server must allow the dashboard's origin: https://app.pushr.sh by default, or set DASHBOARD_URL if you host the dashboard yourself.
  • Sign in with Apple is off unless you set APPLE_SIGN_IN=enabled. Apple gives every server for the pushr app the same identifier for a person, so signing in to your server would link their Apple ID to their pushr cloud account. Deletion also can't revoke the Apple sign-in (that needs the publisher's key), and Hide My Email addresses only get email if your sending domain is registered with Apple.

That's the whole API. Go send one.

Paste a token into the console at the top and watch it land on your phone.

Wire it up tonight.

Free to start. 1,000 pushes a month and one source app are on us.

Download on the App Store

iPhone app

Feed, Live Activities, widgets and per-app sounds.

CLI

Send from the shell, pipe stdin, drive Live Activities.

$brew install cpreston321/tap/pushrsh

SDK

Typed notify() and liveActivity() for any fetch runtime.

$bun add @pushrsh/sdk
Suggested
Quickstart
POST /notify
Action buttons
Live Activities
Webhook adapters
CLI and SDK
Self-hosting
60 sections