# pushr HTTP API 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://.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 | Method | Path | Purpose | Auth | | ------ | --------------------- | ---------------------------------------------------- | ----------------------------------- | | POST | `/notify` | Send a notification | `Authorization: Bearer $PUSHR_TOKEN` | | POST | `/hooks/github` | GitHub webhook adapter | Bearer **or** `?token=` | | POST | `/hooks/sentry` | Sentry webhook adapter | Bearer **or** `?token=` | | POST | `/hooks/grafana` | Grafana webhook adapter | Bearer **or** `?token=` | | GET, POST | `/heartbeat/` | A job checked in; also `/start` and `/fail` | `Authorization: Bearer $PUSHR_TOKEN` | | DELETE | `/heartbeat/` | Stop watching a heartbeat | `Authorization: Bearer $PUSHR_TOKEN` | | PUT, GET, DELETE | `/uptime/` | Create, read or remove an uptime check | `Authorization: Bearer $PUSHR_TOKEN` | | GET | `/status-page/` | A status page's public data | none | | GET | `/healthz` | Health check, backend version and server features | none | | POST | `https://mcp.pushr.sh` | The MCP server for [AI agents](#connect-ai-agents) (pushr cloud) | OAuth, set up by the agent | Self-hosted servers also answer `POST /pair`, which the app uses to redeem a connection code; see [Self-hosting](#self-hosting). --- ## `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 ``` POST /notify Authorization: Bearer pshr_… Content-Type: application/json ``` #### Required fields | Field | Type | Notes | | ------- | ------ | -------------------------------------------------------------------- | | `title` | string | Banner title. | | `body` | string | Banner body. **Or** `message` (Gotify-compatible alias). | #### Content | Field | Type | Notes | | ----- | ---- | ----- | | `url` | string | Tapping the banner opens this URL. See [Links and images](#links-and-images). | | `data` | object | Arbitrary JSON delivered alongside the push (forwarded to the app's notification handler). Up to 4 KB as JSON, nested at most 8 levels, with no keys that start with `$`. A push must fit in Apple's 4 KB: if it wouldn't, `data` is left out of the push itself and then the body shortened; the app still shows both in full. | | `image` | string | URL of an image to attach as a banner thumbnail. See [Links and images](#links-and-images). | | `action` | object | Single action button (legacy). `{ label: string, url: string }`. Replaced by `actions` if both are set. | | `replaceKey` | string (max 128) | A newer notification with the same key replaces this one, on the phone and in the feed. See [Replace keys](#replace-keys). | #### Delivery | Field | Type | Notes | | ----- | ---- | ----- | | `priority` | number 1–10 \| string | `1`–`6` and `"low"`/`"normal"`/`"default"` deliver at default priority. `7`–`10` and `"high"` wake the device with a high-priority push. Defaults to normal. Anything else is a `400`. See [Priority and interruption](#priority-and-interruption). | | `deliverAt` | number (ms-epoch) | Schedule the push for a future time. Must be ≥ now − 60 s and within the next 365 days. Must be a number: an ISO string is ignored and the push sends at once. On pushr cloud, counts toward your monthly quota when accepted. See [Scheduled delivery](#scheduled-delivery). | | `ack` | object | Ack-or-escalate alarm — see [Ack-or-escalate](#ack-or-escalate). | | `critical` | boolean | Ring through mute and Do Not Disturb, where the source app allows critical alerts. See [Critical alerts](#critical-alerts). | #### Interaction | Field | Type | Notes | | ----- | ---- | ----- | | `actions` | array (max 4) | Rich interactive actions — see [Action buttons](#action-buttons). | | `liveActivity` | object | Drive an iOS Live Activity — see [Live Activities](#live-activities). | ### Response ```json { "id": "j97...", "scheduledFor": null } ``` | Code | Body | When | | ---- | ---- | ---- | | 202 | `{ id, scheduledFor }` | Accepted. `scheduledFor` is the `deliverAt` ms-epoch (or `null`). | | 200 | `{ id, scheduledFor }` plus an `Idempotent-Replay: true` header | A retry with an `Idempotency-Key` already used. Nothing is sent again. | Anything else is an error; see [Errors and retries](#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}' ``` Priority also sets how hard the push may interrupt on iOS: | Priority | iOS interruption level | Effect | | ------------------------------ | ---------------------- | --------------------------------------------------- | | `1`–`3`, `"low"` | passive | Lands quietly in Notification Center, no screen wake | | `4`–`6`, `"normal"` (default) | active | A normal banner and sound | | `7`–`10`, `"high"` | time-sensitive | Breaks through Focus and the notification summary | | any push with `ack` | time-sensitive | Same, for every re-push until acknowledged | | critical, where the app allows it | critical | Plays 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. ### Links and images ```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" }' ``` ### 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…" } ] } ``` | `kind` | Behavior | | ---------- | ----------------------------------------------------------------------------------------------------- | | `open_url` | Opens `url` when tapped. Recorded as an event server-side. | | `callback` | POSTs to `callbackUrl`. HTTP status stored on the action event. Optional `authRequired` to lock-gate. | | `reply` | iOS 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. #### Callback request shape When the user taps a `callback` or `reply` action, pushr POSTs to your `callbackUrl`: ``` POST /your/endpoint Content-Type: application/json User-Agent: pushr/1.0 X-Pushr-Source: pushr X-Pushr-Notification: X-Pushr-Action: { "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](#webhook-adapters) > 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 } } ``` 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. - **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: | Setting | What rings through | | ------- | ------------------ | | Off (default) | Nothing | | Marked critical | Pushes sent with `"critical": true` | | All urgent | Those, 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" } ``` - **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](#live-activities) 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. ### 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.outcome` | Shows as | Stays on the Lock Screen | | --------------- | -------- | ------------------------ | | `"success"`, or a full bar with no outcome | Done, green | 15 minutes | | `"failure"` | Failed, red | Until 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. #### Choosing an icon `state.icon` is the name of any [SF Symbol](https://developer.apple.com/sf-symbols/), 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. | Job | Icons | | --- | --- | | Builds and deploys | `hammer.fill` `gearshape.2.fill` `terminal.fill` `testtube.2` `server.rack` | | Transfers and backups | `arrow.up.circle.fill` `arrow.down.circle.fill` `arrow.triangle.2.circlepath` `externaldrive.fill` | | Orders and deliveries | `shippingbox.fill` `box.truck.fill` `cart.fill` `creditcard.fill` `fork.knife` | | Time and tracking | `timer` `hourglass` `calendar` `flag.checkered` `figure.run` | | Home and devices | `house.fill` `lightbulb.fill` `thermometer.medium` `bolt.fill` `printer.fill` | | Media | `play.fill` `film.fill` `music.note` `camera.fill` | | Status | `checkmark.circle.fill` `xmark.octagon.fill` `exclamationmark.triangle.fill` `sparkles` | --- ## 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" ``` The first ping creates the heartbeat, so there's nothing to set up in the app. It's watched from then on. ### Endpoints | Request | Meaning | | ------- | ------- | | `GET` or `POST /heartbeat/` | The job ran. Starts a new window. | | `POST /heartbeat//start` | The job started. The next ping reports how long it took. Optional. | | `POST /heartbeat//fail` | The job failed. Alerts at once; a text body (up to 500 characters) becomes the alert's text. | | `DELETE /heartbeat/` | Stop watching it. | `` is up to 64 letters, digits, dots, dashes or underscores, and is unique within the source app. | Query | Notes | | ----- | ----- | | `every` | How 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. | | `grace` | How 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 | Event | Notification | Priority | | ----- | ------------ | -------- | | No ping by `dueAt` | *nightly-backup missed its check-in* · Expected every 1d. Last ping 1d 1h ago. | high | | `/fail` | *nightly-backup failed* · your body, or "The job reported a failure." | high | | A ping after either | *nightly-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:`, 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](#cli-and-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"}' ``` You can also add and edit checks in the app: **Monitors → + → Uptime check** tests the URL as you type. ### The check | Field | Notes | | ----- | ----- | | `url` | `http` 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. | | `every` | How 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. | | `method` | `GET` (default) or `HEAD`. | | `keyword` | Text the response body must contain, up to 200 characters. Not with `HEAD`. | | `timeout` | Seconds to wait for a response, 1 to 30. Default 10. | | `confirmAfter` | Failed 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 | Event | Notification | Priority | | ----- | ------------ | -------- | | `confirmAfter` failures in a row | *api is down* · HTTP 503 · api.example.com/health | high | | The next passing check | *api 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:`), and they follow the app's mutes, quiet hours, [on-call](#on-call-escalation) and [critical alerts](#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`. | | Free | Pro | | --- | --- | --- | | Uptime checks | 1 | 50 | | Most often | Every 5 minutes | Every 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/`: 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](https://status.pushr.sh). ### Branding Out of the box a page uses the source app's logo and color. In the page's editor you can also set: | Option | Notes | | ------ | ----- | | Logo | Upload one for the page, or keep the app's. | | Accent color | Tints the page's banner and highlights. Status colors stay green, amber and red. | | Theme | Auto (follows the visitor), light or dark. | | Website | A link back to your site at the top. | | Description | A line under the title, up to 160 characters. | | Announcement | Pinned at the top until you clear it, up to 280 characters: info, maintenance or warning. | | Groups | Name 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](#the-tools). 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: ``` GET $PUSHR_URL/status-page/ ``` ```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. ``` 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`. #### 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: | Event | Sent when | Title | Priority | | ------------------- | ------------------------------------------ | -------------------------------------- | -------- | | `push` | Always | "{repo}: N commits → {branch}" | 5 | | `pull_request` | Opened, reopened, ready for review, closed | "{repo} PR #N {opened\|merged\|closed}" | 6 when opened, else 5 | | `issues` | Opened or reopened | "{repo} issue #N {action}" | 5 | | `release` | Published | "{repo} release {tag}" | 7 | | `workflow_run` | Failed or timed out | "{repo}: {name} failed" | 8 | | `check_run` | Failed or timed out | "{repo}: {name} failed" | 8 | | `deployment_status` | Finished (not queued or in progress) | "{repo}: deploy to {env} → {state}" | 8 on failure or error, else 6 | | Any other event | Always | "{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 level | pushr priority | | ------------ | -------------- | | debug | 2 | | info | 4 | | warning | 6 | | error | 8 | | fatal | 9 | | anything else | 5 | 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 ` ( firing)`, or ` 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**. | Provider | Header | Format | Notes | | -------- | ----------------------- | -------------- | ---------------------- | | GitHub | `X-Hub-Signature-256` | `sha256=` | Required when set | | Sentry | `Sentry-Hook-Signature` | bare `` | 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 | Code | Body | When | | ---- | ----------------------------- | --------------------------------------------------------- | | 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](#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](#from-gotify-or-igotify) for the full mapping. --- ## Connect AI agents pushr is an [MCP](https://modelcontextprotocol.io) 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 The server's address is **`https://mcp.pushr.sh`**. `https://mcp.pushr.sh/mcp`, the usual `/mcp` form, works the same, and so does `https://pushr.sh/mcp`, its earlier address, for agents connected there. | Agent | How | | ----- | --- | | Claude (claude.ai, Desktop, mobile) | **Settings → Connectors → Add custom connector**, paste the address | | Claude Code | `claude mcp add --transport http pushr https://mcp.pushr.sh`, then run `/mcp` and choose **Authenticate** | | ChatGPT | Add it as a connector (MCP server) in developer mode | | Cursor | In `~/.cursor/mcp.json`: `{ "mcpServers": { "pushr": { "url": "https://mcp.pushr.sh" } } }` | | VS Code | In `.vscode/mcp.json`: `{ "servers": { "pushr": { "type": "http", "url": "https://mcp.pushr.sh" } } }` | | Anything else | Any client that speaks MCP's Streamable HTTP transport with OAuth | The agent then opens **pushr.sh/connect** in your browser: 1. **Sign in** with your pushr email and password. Made your account with Sign in with Apple? Choose **Email me a sign-in link** instead. Accounts are created in the app, not here. 2. **Choose the apps** the agent may send as, one or more. Its notifications come from those apps, like any other push, and it can read their monitors. With more than one, the agent picks the app for each message. 3. **Allow.** You're sent back to the agent, connected. 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 | Tool | What it does | | ---- | ------------ | | `ask` | Pushes a question with a button per choice (default **Approve** / **Reject**, up to 4) and an optional **Reply** button, then waits for your tap. `urgent: true` re-pushes every minute, up to 5 times, until you answer. | | `get_answer` | Keeps waiting for, or checks, the answer to an `ask` | | `notify` | Sends a notification: `title`, `body`, `priority` (`low`, `normal`, `high`), `url`, `replace_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 | | `monitors` | The state of the chosen apps' uptime checks and heartbeats, worst first | | `incident_update` | Posts an update to a monitor's current or latest [status page incident](#incidents) (within the last day): `monitor` (its name), `status` (`investigating`, `identified`, `monitoring`, `resolved`), `message`, optional `title`. Needs edit access to the app, and Pro | `ask`, `notify` and `progress` take an `app` argument when the agent has more than one app. The agent sees only the apps you chose. **How `ask` waits.** The first button you tap is the answer. One call waits up to `wait_seconds` (default 90, at most 240). If you haven't answered by then, the agent gets the question's `id` and keeps waiting with `get_answer`; it's told never to assume an answer. Tapping later still counts. The buttons appear on the notification and in the feed, like [action buttons](#action-buttons), except no callback URL is involved: the answer goes straight back to the agent. **Plans.** Each `ask`, `notify` and `progress` step is a notification and counts toward your monthly limit. An app that's paused on the Free plan can't send, and the agent is told so. --- ## 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. **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 won't paste a token into code. 2. **Install the skills.** In your project, run: ```bash npx skills add cpreston321/pushr-backend ``` and follow the prompts to choose which agents get them. For Claude Code by hand, copy the folders from [`skills/`](https://github.com/cpreston321/pushr-backend/tree/main/skills) into `.claude/skills/` in your project, or `~/.claude/skills/` for every project. 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 add one line to your `AGENTS.md` or `CLAUDE.md`: `For push notifications, follow https://pushr.sh/llms.txt`. 4. **Check it works.** Ask your agent *"Send me a test push with pushr."* A notification should arrive on your phone. ### The skills | Skill | What it covers | Ask things like | | ----- | -------------- | --------------- | | `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 finishes", "Ping 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 phone", "Add 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 Screen", "Track 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 down", "Send 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 running", "Alert 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 SDK", "Validate pushr payloads" | The agent loads the right skill from what you ask, so you don't need to name it. The skills use `PUSHR_URL` and `PUSHR_TOKEN` from the environment, the same as the SDK and CLI: add them to your project's secrets first. ### Docs for LLM tools Point any tool that takes a URL as context at these: | URL | What it is | | --- | ---------- | | [`pushr.sh/llms.txt`](https://pushr.sh/llms.txt) | An index of pushr's docs and skills, in the [llms.txt](https://llmstxt.org) format | | [`pushr.sh/llms-full.txt`](https://pushr.sh/llms-full.txt) | This whole reference plus every skill, in one file | | [`pushr.sh/docs.md`](https://pushr.sh/docs.md) | This reference as plain Markdown | | `pushr.sh/skills//SKILL.md` | One skill, e.g. [`pushr-notify`](https://pushr.sh/skills/pushr-notify/SKILL.md) | 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. | Code | Body | Applies to | When | | ---- | ---- | ---------- | ---- | | 400 | `{ error: "" }` | `/notify` and adapters | Validation error (missing fields, bad shape). | | 401 | `{ error: "Invalid token" }` / `"Missing bearer token"` | `/notify` and adapters | Bad or absent token. | | 401 | `{ error: "Invalid signature" }` | Webhook adapters | The provider's signature didn't match the signing secret you set. | | 403 | `{ error: "Source app disabled" }` | `/notify` and adapters | Token is valid but the app was disabled. | | 403 | `{ error, code: "APP_PAUSED" }` | `/notify` and adapters | pushr cloud only: the app is on hold because the account is on Free with more apps than Free allows. Choose the active app in the iOS app, or upgrade. | | 409 | `{ error, code: "IDEMPOTENCY_KEY_REUSED" }` | `/notify` | The `Idempotency-Key` was used with a different payload. | | 400 | `{ error, code: "EVERY_REQUIRED" }` | `/heartbeat` | The first ping to a new name didn't say `every`. | | 404 | `{ error }` | `/heartbeat` | Not `/heartbeat/`, `/start` or `/fail`, or `DELETE` of a name that doesn't exist. | | 403 | `{ error, code: "PRO_REQUIRED" }` | `/heartbeat` | pushr cloud only: a new heartbeat past Free's 3. | | 409 | `{ error, code: "HEARTBEAT_LIMIT" }` | `/heartbeat` | Pro's 100, or 50 on one source app, are in use. | | 403 | `{ error, code: "PRO_REQUIRED" }` | `/uptime` | pushr cloud only: a second check, or checking more often than every 5 minutes, on Free. | | 409 | `{ error, code: "UPTIME_LIMIT" }` | `/uptime` | The account already has 50 uptime checks. | | 400 | `{ error }` | `/notify` | A field is over its [limit](#rate-limits-and-quotas), a link uses a forbidden scheme, or `deliverAt` is more than a year away. The message names the field and its limit. | | 429 | `{ error, code: "RATE_LIMITED" }` with `Retry-After` | `/notify` and adapters | The source app sent more than 120 pushes in a minute. Wait `Retry-After` seconds. Replays with an `Idempotency-Key` don't count. | | 429 | `{ error, code: "QUOTA_EXCEEDED", tier, count, limit }` | `/notify` and adapters | pushr cloud only: the monthly push limit is reached. See [Rate limits and quotas](#rate-limits-and-quotas). | | 500 | `{ error: "Internal error" }` | `/notify`, `/heartbeat`, `/uptime` and adapters | Something failed on the server. Safe to retry with the same `Idempotency-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"}' ``` - A retry with the same key and the same body returns the original `id` with `200` and `Idempotent-Replay: true`. It isn't pushed again and doesn't count toward your quota. - The same key with a different body is a `409`, because that's a bug in the sender, not a retry. - Keys are per source app and are remembered for at least 24 hours. --- ## `GET /healthz` ``` 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 | Pro | | --- | --- | --- | | Pushes per month | 1,000 | 10,000 | | Source apps | 1 | Unlimited | | History | 7 days | 90 days | | People per shared app | 1 | Unlimited | | Quiet hours, Slack and Discord forwarding | No | Yes | | Uptime checks | 1, every 5 minutes | 50, every minute | | Heartbeats | 3 | 100 | | Status pages | No | 5 | | On-call escalation and critical alerts | No | Yes | 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. Two things differ from most of these services: - **`title` and `body` are both required.** Where you relied on a default title, send one. - **Bodies are JSON, and plain text.** Form fields, a raw text body and Markdown aren't read. ### From Pushover ```bash # Before 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 curl -X POST "$PUSHR_URL/notify" \ -H "Authorization: Bearer $PUSHR_TOKEN" \ -d '{ "title": "Backup failed", "body": "exit 2", "priority": "high" }' ``` | Pushover | pushr | | -------- | ----- | | `token` (application) | The source app's token, as a bearer header | | `user` / group key | Not needed: a push reaches everyone the source app is [shared](#post-notify) with | | `title`, `message` | `title`, `body` | | `url`, `url_title` | `url`, or an `open_url` [action](#action-buttons) with your own label | | `priority` `-2` / `-1` / `0` / `1` | `1` / `3` / `5` / `8` (see [Priority and interruption](#priority-and-interruption)) | | `priority=2` with `retry` and `expire` | `"priority": "high"` plus `ack: { timeoutSec: retry, maxAttempts: expire ÷ retry }` (at most 20), see [Ack-or-escalate](#ack-or-escalate) | | `sound` | Picked per priority level in the app, under **Settings → Sounds** | | `attachment` (uploaded file) | `image`: a public URL rather than an upload | | `device` | Chosen on the phone instead: each person switches delivery off for any of their devices in **Settings → Devices** | | `html`, `ttl`, `timestamp` | Not available | ### From ntfy ntfy publishes to a topic with the message as the request body and the rest as headers. pushr takes one JSON object instead. ```bash # Before curl -H "Title: Backup failed" -H "Priority: high" \ -H "Click: https://homelab.lan" -d "exit 2" ntfy.sh/homelab-backups # After curl -X POST "$PUSHR_URL/notify" \ -H "Authorization: Bearer $PUSHR_TOKEN" \ -d '{ "title": "Backup failed", "body": "exit 2", "priority": "high", "url": "https://homelab.lan" }' ``` | ntfy | pushr | | ---- | ----- | | Topic in the URL | A source app; its token replaces the topic name and any `tk_` access token | | Request body (the message) | `body` | | `Title` | `title` (required) | | `Priority` `1` min / `2` low / `3` default / `4` high / `5` max | `1` / `3` / `5` / `8` / `10` | | `Click` | `url` | | `Attach` (a URL) | `image` | | `Actions` `view` | `open_url` [action](#action-buttons) | | `Actions` `http` | `callback` action: a `POST` with pushr's own JSON body, no custom method, headers or body | | `Delay` / `At` | `deliverAt`, as a millisecond timestamp | | `Tags` (emoji) | Not available: put the emoji in the `title` | | `Markdown`, `Email`, `Call` | Not available | | GitHub and Grafana templates | `/hooks/github` and `/hooks/grafana`, plus Sentry: see [Webhook adapters](#webhook-adapters) | Scripts that pipe into `curl -d` read naturally with the [CLI](#cli-and-sdk): `tail -n 5 backup.log | pushrsh "Backup failed"`. ### From Gotify or iGotify pushr accepts Gotify's field names, so a sender usually needs only a new URL and header. Point it at `/notify` and send the token as a bearer header: Gotify's `/message` route, `?token=` parameter and `X-Gotify-Key` header aren't supported. ```bash curl -X POST "$PUSHR_URL/notify" \ -H "Authorization: Bearer $PUSHR_TOKEN" \ -d '{ "title": "Backup failed", "message": "exit 2", "priority": 8, "extras": { "client::notification": { "click": { "url": "https://homelab.lan" } } } }' ``` | Gotify | pushr | | ------ | ----- | | App token | Source app token, as a bearer header | | `title`, `message` | `title` (required), `message` (or `body`) | | `priority` `1`–`10` | The same scale | | `priority` `0` | Rejected: send `1`, or leave `priority` out | | `extras["client::notification"].click.url` | `url` | | `extras["client::notification"].bigImageUrl` | Not read: send `image` | | `extras["client::display"]` Markdown | Not available: bodies are plain text | There's no Gotify server to keep running, and iGotify's bridge isn't needed: pushr delivers to the iPhone app itself. ### From Hark Hark and pushr are both webhook-to-iPhone services, so most fields carry straight over. A Hark service is a pushr source app, and the secret webhook URL becomes `POST /notify` with a bearer token. ```bash # Before curl -X POST https://hark.ryan.ceo/hooks/whk_your_token \ -H 'Content-Type: application/json' \ -d '{ "title": "GitHub", "body": "Production deployed", "url": "https://github.com/acme/app/actions" }' # After curl -X POST "$PUSHR_URL/notify" \ -H "Authorization: Bearer $PUSHR_TOKEN" \ -d '{ "title": "GitHub", "body": "Production deployed", "url": "https://github.com/acme/app/actions" }' ``` | Hark | pushr | | ---- | ----- | | Webhook URL (`/hooks/whk_…`) | `POST /notify` with the source app's token | | `body`, `title`, `url` | The same; `title` is required | | `imageUrl` (sender avatar) | The source app's logo, set once in the app. `image` is a picture attached to one push | | `project` | One source app per project | | `Idempotency-Key` header | The same header, see [Retries and `Idempotency-Key`](#retries-and-idempotency-key) | | `response` `approval` / `yes_no` | Two `callback` [actions](#action-buttons), the risky one `destructive` | | `response` `text` | A `reply` action | | `callback.url` with `callback.token` | Each action's `callbackUrl`; put the token in the URL, since callbacks are unsigned | | Reading or cancelling a response | Not available over HTTP; agents wait for answers with [`ask`](#connect-ai-agents) | | Withdrawing a notification | Send a newer one with the same [`replaceKey`](#replace-keys) | | `deviceIds` | Chosen 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 | | `bodyFormat` Markdown, `summary` | Not available | Live Activities are a field on `/notify` rather than their own endpoints. You choose the `activityId` instead of reading one back, and send `liveActivity.action` `start`, `update` or `end`: | Hark | pushr | | ---- | ----- | | Start, update, end endpoints | `liveActivity.action`: `start` / `update` / `end` on `/notify` | | `title`, `status`, `progress` (0–1) | `state.title`, `state.status`, `state.progress` (0–1) | | `symbol` | `state.icon`: any SF Symbol name | | Failure on end | `state.outcome: "failure"` | | `accentColor`, `style`, `ifSequence` | Not available | See [Live Activities](#live-activities) for the full shape. With the CLIs, `harkctl notify` becomes `pushrsh "Title" "Body"` and `harkctl activity start|update|end` becomes `pushrsh la start|update|end` (see [CLI and SDK](#cli-and-sdk)). Instead of `harkctl permissions setup`, add `https://mcp.pushr.sh` to Claude, ChatGPT or Cursor and they ask on your phone with the `ask` tool: see [Connect AI agents](#connect-ai-agents). --- ## 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](#rate-limits-and-quotas). ### What you need - [Bun](https://bun.sh). - A Convex backend: a free [Convex](https://convex.dev) account, or Convex itself in Docker on your own server (see [Run Convex yourself](#run-convex-yourself-with-docker)). - The pushr iPhone app. - The [`pushr-backend`](https://github.com/cpreston321/pushr-backend) source. ### 1. Create your deployment ```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. #### Run Convex yourself with Docker A Convex account is optional: Convex's backend is open source too, and runs in Docker. Two addresses matter, and the iPhone needs both over HTTPS: | Port | Convex calls it | pushr calls it | | ---- | --------------- | -------------- | | `3210` | `CONVEX_CLOUD_ORIGIN` | Convex URL | | `3211` | `CONVEX_SITE_ORIGIN` | Site URL (`/notify`, `/healthz`) | Put a reverse proxy such as Caddy or nginx in front, with a hostname for each, for example `convex.example.com` → `3210` and `push.example.com` → `3211`. ##### Recommended server Any VPS that runs Docker works: Hetzner Cloud, DigitalOcean, Vultr, Linode or AWS Lightsail all fit. An x86-64 (Intel or AMD) plan is the safest choice. Size it by how much you send: | Use | vCPU | Memory | Disk | | --- | ---- | ------ | ---- | | Just you, or a small team | 2 | 4 GB | 40 GB SSD | | A busy team, many monitors | 4 | 8 GB | 80 GB SSD | | Heavy production traffic | 8 | 16 GB | 160 GB SSD | Pick a region near where your servers send from: pushes go phone-ward through Apple, so the VPS's distance to your phones matters little. The templates below are sized for the largest row. On a smaller server, lower `cpus` and `mem_limit` to fit it: Docker won't start a container that asks for more CPUs than the machine has. On a 2 vCPU, 4 GB server, for example, give the backend `cpus: 1.5` and `mem_limit: 2G`, and Postgres `cpus: 0.5`, `mem_limit: 1G` and `shm_size: 256mb`. Pick a template. Both keep the database in Postgres; they differ in where Convex keeps files (uploaded logos, function code, search indexes and exports). ##### Postgres Start here. Files stay on a `convex-data` volume on the same machine. ```yaml services: backend: image: 'ghcr.io/get-convex/convex-backend:latest' stop_grace_period: 10s stop_signal: SIGINT cpus: 8 mem_limit: 10G ports: - '127.0.0.1:3210:3210' - '127.0.0.1:3211:3211' volumes: - 'convex-data:/convex/data' environment: - 'INSTANCE_NAME=${INSTANCE_NAME:-convex-self-hosted}' - 'INSTANCE_SECRET=${INSTANCE_SECRET:-}' - 'CONVEX_RELEASE_VERSION_DEV=${CONVEX_RELEASE_VERSION_DEV:-}' - 'ACTIONS_USER_TIMEOUT_SECS=${ACTIONS_USER_TIMEOUT_SECS:-}' - 'CONVEX_CLOUD_ORIGIN=${CONVEX_CLOUD_ORIGIN:-http://127.0.0.1:3210}' - 'CONVEX_SITE_ORIGIN=${CONVEX_SITE_ORIGIN:-http://127.0.0.1:3211}' - 'POSTGRES_URL=${POSTGRES_URL:-}' - 'DISABLE_BEACON=${DISABLE_BEACON:-true}' - 'REDACT_LOGS_TO_CLIENT=${REDACT_LOGS_TO_CLIENT:-true}' - 'RUST_LOG=${RUST_LOG:-info}' - 'RUST_BACKTRACE=${RUST_BACKTRACE:-}' - 'DO_NOT_REQUIRE_SSL=${DO_NOT_REQUIRE_SSL:-1}' - EXPORT_STORAGE_GET_CONCURRENCY=4 - EXPORT_MAX_INFLIGHT_PREFETCH_BYTES=8388608 - EXPORT_WORKER_PAGE_SIZE=100 - MALLOC_ARENA_MAX=2 depends_on: postgres: condition: service_healthy healthcheck: test: 'curl -f http://localhost:3210/version' interval: 5s start_period: 5s postgres: image: 'postgres:17-alpine' cpus: 3 mem_limit: 6G shm_size: 1gb environment: - POSTGRES_USER=postgres - 'POSTGRES_PASSWORD=${DB_PASSWORD}' - POSTGRES_DB=convex_self_hosted volumes: - 'postgres-data:/var/lib/postgresql/data' healthcheck: test: - CMD-SHELL - 'pg_isready -U postgres' interval: 5s timeout: 5s retries: 5 volumes: convex-data: null postgres-data: null ``` ##### Postgres and S3 For a production server where files should live in S3-compatible storage (AWS S3, Cloudflare R2, MinIO…), so the machine itself holds nothing you'd lose. Create the five buckets first. ```yaml services: backend: image: 'ghcr.io/get-convex/convex-backend:latest' stop_grace_period: 10s stop_signal: SIGINT cpus: 8 mem_limit: 10G ports: - '127.0.0.1:3210:3210' - '127.0.0.1:3211:3211' environment: - AWS_REGION=us-east-1 - 'AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID}' - 'AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY}' - S3_STORAGE_EXPORTS_BUCKET=convex-snapshot-exports - S3_STORAGE_SNAPSHOT_IMPORTS_BUCKET=convex-snapshot-imports - S3_STORAGE_MODULES_BUCKET=convex-modules - S3_STORAGE_FILES_BUCKET=convex-user-files - S3_STORAGE_SEARCH_BUCKET=convex-search-indexes - 'S3_ENDPOINT_URL=${S3_ENDPOINT_URL}' - 'INSTANCE_NAME=${INSTANCE_NAME:-convex-self-hosted}' - 'INSTANCE_SECRET=${INSTANCE_SECRET:-}' - 'CONVEX_RELEASE_VERSION_DEV=${CONVEX_RELEASE_VERSION_DEV:-}' - 'ACTIONS_USER_TIMEOUT_SECS=${ACTIONS_USER_TIMEOUT_SECS:-}' - 'CONVEX_CLOUD_ORIGIN=${CONVEX_CLOUD_ORIGIN:-http://127.0.0.1:3210}' - 'CONVEX_SITE_ORIGIN=${CONVEX_SITE_ORIGIN:-http://127.0.0.1:3211}' - 'POSTGRES_URL=${POSTGRES_URL:-}' - 'DISABLE_BEACON=${DISABLE_BEACON:-true}' - 'REDACT_LOGS_TO_CLIENT=${REDACT_LOGS_TO_CLIENT:-true}' - 'RUST_LOG=${RUST_LOG:-info}' - 'RUST_BACKTRACE=${RUST_BACKTRACE:-}' - 'DO_NOT_REQUIRE_SSL=${DO_NOT_REQUIRE_SSL:-1}' - EXPORT_STORAGE_GET_CONCURRENCY=4 - EXPORT_MAX_INFLIGHT_PREFETCH_BYTES=8388608 - EXPORT_WORKER_PAGE_SIZE=100 - MALLOC_ARENA_MAX=2 depends_on: postgres: condition: service_healthy healthcheck: test: 'curl -f http://localhost:3210/version' interval: 5s start_period: 5s postgres: image: 'postgres:17-alpine' cpus: 3 mem_limit: 6G shm_size: 1gb environment: - POSTGRES_USER=postgres - 'POSTGRES_PASSWORD=${DB_PASSWORD}' - POSTGRES_DB=convex_self_hosted volumes: - 'postgres-data:/var/lib/postgresql/data' healthcheck: test: - CMD-SHELL - 'pg_isready -U postgres' interval: 5s timeout: 5s retries: 5 volumes: postgres-data: null ``` Put the values in a `.env` beside the compose file. `POSTGRES_URL` points at the `postgres` service without a database name, because Convex uses `INSTANCE_NAME` with `-` turned into `_` (`convex_self_hosted`, matching `POSTGRES_DB`; change both together). The origins are your two public HTTPS addresses: ```bash INSTANCE_SECRET= DB_PASSWORD= POSTGRES_URL=postgresql://postgres:@postgres:5432 CONVEX_CLOUD_ORIGIN=https://convex.example.com CONVEX_SITE_ORIGIN=https://push.example.com # Postgres and S3 only AWS_ACCESS_KEY_ID=… AWS_SECRET_ACCESS_KEY=… S3_ENDPOINT_URL=https:// ``` For a single machine without Postgres either, Convex's own [self-hosting guide](https://github.com/get-convex/convex-backend/tree/main/self-hosted) has a smaller compose file. Start it, make an admin key, and point the pushr backend at it instead of running `bun run dev`: ```bash docker compose up -d docker compose exec backend ./generate_admin_key.sh git clone https://github.com/cpreston321/pushr-backend cd pushr-backend bun install # in pushr-backend/.env.local CONVEX_SELF_HOSTED_URL=https://convex.example.com CONVEX_SELF_HOSTED_ADMIN_KEY= bun run push ``` `bun run push` deploys the schema and functions to your backend, and the `bunx convex` commands in the next steps use it too. Wherever they mention the `.convex.cloud` URL, use your Convex URL; for the `.convex.site` URL, your Site URL. ### 2. Set the server secrets These live in the Convex deployment, not in `.env.local`: ```bash bunx convex env set BETTER_AUTH_SECRET "$(openssl rand -hex 32)" bunx convex env set SITE_URL "https://.convex.site" ``` With your own Convex, `SITE_URL` is your Site URL: ```bash bunx convex env set BETTER_AUTH_SECRET "$(openssl rand -hex 32)" bunx convex env set SITE_URL "https://push.example.com" ``` ### 3. Create your account ```bash bunx convex run seed:createAdmin '{"email":"you@example.com","password":""}' ``` ### 4. Connect the app 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. In pushr, open **Settings → Server**. 2. Under **Custom Convex Deployment**, tap **Custom domain?** and enter your Convex URL (`https://convex.example.com`) and Site URL (`https://push.example.com`). 3. Tap **Test connection**. It checks that `/healthz` answers from your deployment. 4. 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 } ``` 5. 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 ``` ### 5. Send a push Create a source app in the **Apps** tab and copy its token, then: ```bash curl -X POST "https://.convex.site/notify" \ -H "Authorization: Bearer $PUSHR_TOKEN" \ -H "Content-Type: application/json" \ -d '{"title":"Hello","body":"from my own server"}' ``` ```bash curl -X POST "https://push.example.com/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](#use-with-ai-agents), SDK or CLI and a token instead. - **Status pages** are served as JSON at `/status-page/` on your deployment; the `status.pushr.sh/` page shows pushr cloud's pages only. - **The web dashboard works with your server.** At [app.pushr.sh](https://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. --- # Agent skills Task-focused guides for coding agents. Install with `npx skills add cpreston321/pushr-backend`. --- name: pushr-notify description: Send push notifications to the user's phone (iPhone or Android) with pushr (POST /notify), from any language, script, server, CI job or cron. Use when the user asks to "notify me when…", "send a push to my phone", "ping me when the build/deploy/job finishes", "alert me if this fails", "add pushr to my app/script", or wants notifications from GitHub Actions, a cron job, a backend or a CLI. Covers setup (URL and token), the request fields, priority, links and images, scheduling, idempotent retries, errors, the TypeScript SDK and the pushrsh CLI. --- # Send notifications with pushr pushr turns one HTTP request into a push notification on the user's iPhone or Android phone. Everything goes through `POST $PUSHR_URL/notify` with a source-app bearer token. Full reference: https://pushr.sh/llms-full.txt ## 1. Setup: URL and token Two values, always from the environment, never hard-coded or committed: | Variable | What it is | | ------------- | -------------------------------------------------------------------------- | | `PUSHR_URL` | The server's site URL. pushr cloud: shown in the app's **API & token** sheet. Self-hosted: `https://.convex.site`. | | `PUSHR_TOKEN` | A source-app token, `pshr_…`, created in the app's **Apps** tab. Shown once. | Each source app is one sender (a CI, a service, a script). Use one token per sender so the user can mute or revoke it alone. If the user hasn't got a token yet, tell them: open pushr → Apps → + → name it → copy the token. When adding pushr to a project: read these from env (`.env`, CI secrets, your platform's secret store), add them to `.env.example` without values, and make sure `.env` is git-ignored. ## 2. The request ```bash curl -X POST "$PUSHR_URL/notify" \ -H "Authorization: Bearer $PUSHR_TOKEN" \ -H "Content-Type: application/json" \ -d '{"title":"Build succeeded","body":"main → staging"}' ``` Required: `title` and `body` (`message` is accepted as an alias for `body`). | Field | Type | Use it for | | ------------ | --------------------- | ---------- | | `priority` | `1`–`10`, or `"low"`/`"normal"`/`"default"`/`"high"` | How hard it interrupts. See below. Default normal. | | `url` | string | Opened when the notification is tapped. | | `image` | string (URL) | Thumbnail on the banner. | | `data` | object | Arbitrary JSON passed to the app. | | `deliverAt` | number, ms since epoch | Send later. Must be a number (an ISO string is ignored and it sends now) and ≥ now − 60 s. | | `replaceKey` | string, max 128 | A newer push with the same key replaces this one on the phone and in the feed. See below. | | `critical` | boolean | Ring through mute where the app's owner allows critical alerts: use the `pushr-alerts` skill. | | `actions` | array, max 4 | Buttons and replies: use the `pushr-actions` skill. | | `ack` | `{ timeoutSec, maxAttempts }` | Re-push until acknowledged: use the `pushr-alerts` skill. | | `liveActivity` | object | Lock Screen / Dynamic Island progress: use the `pushr-live-activities` skill. | Success is `202 { "id": "…", "scheduledFor": null | }`. ## 3. Choosing a priority Pick by what the user needs to do, not by how important the event feels: | Priority | iOS behaviour | Use for | | -------- | ------------- | ------- | | `1`–`3` / `"low"` | Passive: lands quietly in Notification Center, no sound, screen stays off | FYIs, digests, "nightly backup done" | | `4`–`6` / `"normal"` (default) | A normal banner and sound | Most things: build passed, order received | | `7`–`10` / `"high"` | Time-sensitive: breaks through Focus | Needs attention soon: prod down, payment failed | On Android every priority shows as a heads-up notification with the sound the user picked for it; the priority only decides how urgently Google delivers it. Quiet hours and silent priorities use a silent channel. Don't default everything to high: it trains the user to ignore it. During a source app's quiet hours, pushes arrive passively unless they need an ack. ## 4. Pick the client - **Shell, CI, cron:** curl (above) or the `pushrsh` CLI. - **TypeScript / JavaScript (any fetch runtime: Node 18+, Bun, Deno, Workers, edge):** `@pushrsh/sdk`. - **Anything else:** a plain HTTPS POST. Python and Go below. ### TypeScript SDK ```ts // bun add @pushrsh/sdk (or npm i @pushrsh/sdk) import { notify, PushrError } from "@pushrsh/sdk"; // reads PUSHR_URL and PUSHR_TOKEN await notify({ title: "New sale", body: "$42 from Acme", priority: "high", url: "https://dash.example.com/orders/981" }); ``` For explicit config (several tokens, or env names you don't control): ```ts import { Pushr } from "@pushrsh/sdk"; const pushr = new Pushr({ url: process.env.PUSHR_URL!, token: process.env.PUSHR_TOKEN! }); await pushr.notify({ title: "Backup done", body: "18 TB verified", priority: "low" }); ``` `deliverAt` accepts a `Date` in the SDK. Failures throw `PushrError` with `status`, `code` and `data`. The SDK does not send `Idempotency-Key`; when a retry must not double-send, call `fetch` directly (section 6). ### CLI ```bash # brew install cpreston321/tap/pushrsh (reads PUSHR_URL and PUSHR_TOKEN) pushrsh "Deploy finished" "main → production" -p high -u https://example.com/deploys/42 tail -n 20 build.log | pushrsh "Build failed" -p high # stdin becomes the body pushrsh "Standup" "Time to gather" --at +15m # schedule pushrsh ping # check the server ``` Other flags: `-i URL` image, `-d KEY=VALUE` data (repeatable), `--ack 60/5`, `-r KEY` replace key, `--json FILE|-` to send a raw body, `-q` to print only the id. `pushrsh hb NAME --every 1d -- COMMAND` wraps a cron job in a heartbeat: see the `pushr-heartbeats` skill. ### Python ```python import os, requests def notify(title: str, body: str, **fields) -> dict: res = requests.post( f"{os.environ['PUSHR_URL']}/notify", headers={"Authorization": f"Bearer {os.environ['PUSHR_TOKEN']}"}, json={"title": title, "body": body, **fields}, timeout=10, ) res.raise_for_status() return res.json() notify("Training finished", "val_loss 0.231 after 12 epochs", url="https://wandb.ai/run/abc") ``` ### Go ```go body, _ := json.Marshal(map[string]any{"title": "Job done", "body": "3,402 rows imported"}) req, _ := http.NewRequest("POST", os.Getenv("PUSHR_URL")+"/notify", bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer "+os.Getenv("PUSHR_TOKEN")) req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) ``` ### GitHub Actions ```yaml - name: Notify phone if: always() env: PUSHR_URL: ${{ secrets.PUSHR_URL }} PUSHR_TOKEN: ${{ secrets.PUSHR_TOKEN }} run: | curl -fsS -X POST "$PUSHR_URL/notify" \ -H "Authorization: Bearer $PUSHR_TOKEN" -H "Content-Type: application/json" \ -d "$(jq -n --arg s "${{ job.status }}" --arg r "$GITHUB_REPOSITORY" \ '{title: "\($r): \($s)", body: "${{ github.workflow }} on ${{ github.ref_name }}", priority: (if $s == "success" then "normal" else "high" end), url: "${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"}')" ``` Build JSON with `jq` (or your language's encoder), never by string concatenation: titles with quotes or newlines would break the body. ## 5. Writing good notifications - **Title:** the outcome in a few words ("Deploy #482 failed"), not the system name. - **Body:** the one detail that decides what to do next ("tests: 3 failed in auth"). - **`url`:** where the user would go next: the run, the order, the dashboard. - Notify on transitions (failed, recovered, finished), not on every poll. - For a state that keeps changing (disk usage, a queue, a deploy's stage), send every push with the same `replaceKey`, e.g. `"disk-db-1"`. Each one replaces the last, so the Lock Screen shows only the current state and the feed keeps the earlier ones as a timeline. (On Android the feed collapses them the same way; earlier banners stay in the notification shade.) Keys are per source app. For second-by-second progress, use a Live Activity instead. - To know when a cron job or worker *stops* running, don't build it from `/notify`: use a heartbeat (the `pushr-heartbeats` skill). ## 6. Errors and safe retries | Status | Meaning | What to do | | ------ | ------- | ---------- | | `202` | Accepted | Done. | | `200` + `Idempotent-Replay: true` | A retry with a key already used | Done; nothing was sent twice. | | `400` | Bad request (`error` says why) | Fix the payload; don't retry. | | `401` | Missing, invalid or revoked token | Check `PUSHR_TOKEN`; don't retry. | | `403` | App disabled, or `code: "APP_PAUSED"` (cloud: Free plan over its app limit) | Tell the user; don't retry. | | `409` `IDEMPOTENCY_KEY_REUSED` | Same key, different body | A bug in the sender; use a new key per distinct message. | | `429` `RATE_LIMITED` | Over 120 pushes a minute from this source app | Wait the `Retry-After` seconds, then retry. | | `429` `QUOTA_EXCEEDED` | Monthly quota reached (pushr cloud) | Stop and tell the user; don't retry until next month. | | `5xx`, network error | Transient | Retry with backoff, with an `Idempotency-Key`. | To retry without ever sending twice, send the same `Idempotency-Key` header (≤ 255 chars, e.g. a job id) on every attempt. Keys are per source app and remembered for at least 24 hours; replays don't count toward the quota. ```ts async function notifyOnce(key: string, payload: object) { for (let attempt = 1; ; attempt++) { let res: Response | undefined; try { res = await fetch(`${process.env.PUSHR_URL}/notify`, { method: "POST", headers: { Authorization: `Bearer ${process.env.PUSHR_TOKEN}`, "Content-Type": "application/json", "Idempotency-Key": key, }, body: JSON.stringify(payload), }); } catch (err) { if (attempt === 4) throw err; // network error: retried } if (res?.ok) return res.json(); // Rate limited: wait as long as the server says, then try again. const wait = res?.status === 429 ? Number(res.headers.get("Retry-After")) : NaN; if (wait > 0 && attempt < 4) { await new Promise((r) => setTimeout(r, wait * 1000)); continue; } // Any other 4xx won't succeed on a retry. if (res && res.status < 500) throw new Error(`pushr ${res.status}: ${(await res.json()).error}`); if (attempt === 4) throw new Error(`pushr ${res?.status ?? "unreachable"}`); await new Promise((r) => setTimeout(r, 2 ** attempt * 250)); } } ``` A notification must never break the job it reports on: wrap the call so a pushr failure is logged, not thrown, unless the user asked otherwise. ## 7. Limits (pushr cloud) Free: 1,000 pushes a month and 1 source app. Pro: 10,000 a month and unlimited apps. Self-hosted servers have no plans or push quota (just 50 uptime checks per account, 50 heartbeats per app, 90 days of history). Check the server with `GET $PUSHR_URL/healthz` → `{ "ok": true, "version": …, "selfHosted": … }`. --- --- name: pushr-actions description: Add tappable buttons and inline replies to pushr notifications, and implement the HTTPS endpoint that receives the taps. Use when the user asks for "approve/reject from my phone", "a button on the notification", "let me confirm/deny/retry from the push", "reply to the notification", "human-in-the-loop approval", "deploy gate", or needs to build or secure a pushr callback endpoint (Express, Hono, Next.js, FastAPI, Workers…). --- # Notification actions and callbacks Add up to **4** `actions` to a `POST /notify` request (sending basics are in the `pushr-notify` skill). Full reference: https://pushr.sh/llms-full.txt ## The three kinds | `kind` | Required fields | Optional | What happens on tap | | ---------- | --------------- | -------- | ------------------- | | `callback` | `id`, `label`, `callbackUrl` | `destructive`, `authRequired` | pushr POSTs to `callbackUrl` | | `reply` | `id`, `label`, `callbackUrl` | `placeholder` | Inline text field; pushr POSTs the text | | `open_url` | `id`, `label`, `url` | `destructive` | Opens `url` on the phone; nothing is POSTed | Validation (a `400` otherwise): `id`s unique within the notification, at most one `reply`, a known `kind`. Reply text is capped at 2,000 characters. ## Designing the buttons - **A decision (yes/no):** one `callback` per answer, mark the risky one `destructive`. Callbacks on one notification are a single choice: once one goes through, the others are refused ("Already answered") on every device, so your endpoint hears exactly one answer. - **Several independent buttons** (not one answer): send separate notifications. - **Context:** add an `open_url` (logs, diff, order) next to the decision. - `reply` and `open_url` stay usable after the decision. - Lock Screen banners show generic labels ("Action 1", "Reply") because iOS needs categories registered ahead of time (Android shows the same ones); the pushr feed shows your real labels. Keep labels short and put the meaning in the title/body too. ```json { "title": "Staging deploy ready", "body": "a1f93c · 38 checks passed. Promote to production?", "priority": "high", "actions": [ { "kind": "callback", "id": "approve", "label": "Approve", "callbackUrl": "https://ci.example.com/hooks/pushr/deploy/42?key=SECRET" }, { "kind": "callback", "id": "reject", "label": "Reject", "callbackUrl": "https://ci.example.com/hooks/pushr/deploy/42?key=SECRET", "destructive": true }, { "kind": "open_url", "id": "logs", "label": "Logs", "url": "https://ci.example.com/deploy/42" } ] } ``` One `callbackUrl` for every button is fine: the action id arrives in the request, so one handler can branch on it. ## What your endpoint receives ``` POST Content-Type: application/json User-Agent: pushr/1.0 X-Pushr-Source: pushr X-Pushr-Notification: X-Pushr-Action: { "notificationId": "…", "actionId": "approve", "respondedAt": 1712160000000, "reply": "LGTM" } ``` `reply` is present only for `kind: "reply"`. Rules that shape the implementation: - `callbackUrl` must be **public `https://`**: no localhost, private or link-local addresses, no embedded credentials. Redirects aren't followed. For local development, expose the endpoint through a tunnel. - pushr waits **10 seconds**, then counts the tap as failed. Respond fast; queue slow work and return `200` immediately. - Any `2xx` counts as success. A network error or `4xx`/`5xx` leaves the choice open, so the user can tap again. Return non-2xx only when you want them to be able to retry. - pushr stores only your status code, never the response body. - **Requests are unsigned.** Authenticate with a secret in the URL (`?key=…`, compared in constant time) or a path segment you can verify. - Make the handler idempotent: key on `notificationId` + `actionId`. - Members of a shared app can trigger callbacks and replies, unless the owner turned that off for a viewer; links always open. ## Implementations ### Hono (Workers, Bun, Node) ```ts import { Hono } from "hono"; import { timingSafeEqual } from "node:crypto"; const app = new Hono(); app.post("/hooks/pushr/deploy/:id", async (c) => { const key = c.req.query("key") ?? ""; const expected = process.env.PUSHR_CALLBACK_KEY!; if (key.length !== expected.length || !timingSafeEqual(Buffer.from(key), Buffer.from(expected))) { return c.text("forbidden", 403); } const { notificationId, actionId, reply } = await c.req.json<{ notificationId: string; actionId: string; respondedAt: number; reply?: string; }>(); if (await alreadyHandled(notificationId, actionId)) return c.text("ok"); // idempotent await enqueue({ deploy: c.req.param("id"), decision: actionId, note: reply }); // don't block the 10 s window return c.text("ok"); }); ``` ### Express ```ts app.post("/hooks/pushr/deploy/:id", express.json(), async (req, res) => { if (!validKey(req.query.key)) return res.sendStatus(403); const { notificationId, actionId, reply } = req.body; await queue.add("deploy-decision", { id: req.params.id, notificationId, actionId, reply }); res.sendStatus(200); }); ``` ### Next.js route handler ```ts // app/api/pushr/route.ts export async function POST(req: Request) { const url = new URL(req.url); if (!validKey(url.searchParams.get("key"))) return new Response("forbidden", { status: 403 }); const { notificationId, actionId, reply } = await req.json(); await recordDecision(notificationId, actionId, reply); return new Response("ok"); } ``` ### FastAPI ```python @app.post("/hooks/pushr/deploy/{deploy_id}") async def pushr_callback(deploy_id: str, key: str, payload: dict): if not hmac.compare_digest(key, os.environ["PUSHR_CALLBACK_KEY"]): raise HTTPException(403) await queue.put((deploy_id, payload["notificationId"], payload["actionId"], payload.get("reply"))) return {"ok": True} ``` ## Waiting for an answer (approval gates) To block a job until the user decides: send the notification, store `{ notificationId → job }`, and have the callback resolve it. Poll your own store with a timeout and pick a safe default (usually "reject") if no answer arrives. For a decision that must not be missed, combine with `ack` (see `pushr-alerts`) so the push keeps re-alerting until it's opened. ## Other entry points - SDK: `notify({ ..., actions: [...] })`; the `Action` type in `@pushrsh/sdk` matches the table above. - CLI: `pushrsh "PR ready" "+812 / -96" -a "View=https://example.com/pr/318"` adds a single legacy link button (`action: { label, url }`); use `--json` for callbacks or replies. --- --- name: pushr-live-activities description: Show live progress on the user's iPhone Lock Screen and Dynamic Island, or as an ongoing Android notification, with pushr Live Activities (start / update / end). Use when the user asks to "show build/deploy progress on my lock screen", "track this job live", "Dynamic Island progress", "progress bar for my upload/backup/training/order", or wants a long-running script, CI pipeline, worker or delivery tracker to report progress as it runs. --- # Live Activities with pushr A Live Activity is a progress card on the Lock Screen and in the Dynamic Island, driven by `POST /notify` with a `liveActivity` field. On Android the same requests drive an ongoing notification with a progress bar (a Live Update on Android 16), so one integration covers both. Sending basics are in the `pushr-notify` skill. Full reference: https://pushr.sh/llms-full.txt ## Lifecycle Three actions, all keyed by an `activityId` you choose: 1. **`start`**: once, when the job begins. Send `attributes` here (they're fixed for the activity's life). 2. **`update`**: as progress changes. Send only the new `state`. 3. **`end`**: exactly once, on success **and** on failure. Never leave an activity running. ```json { "title": "Deploy #42", "body": "Building", "liveActivity": { "action": "start", "activityId": "deploy-42", "attributes": { "name": "ci.example.com" }, "state": { "title": "Deploy #42", "status": "Building image", "progress": 0.1, "icon": "hammer.fill" } } } ``` | Field | Rules | | ----- | ----- | | `activityId` | Required, non-empty. Stable per job (`deploy-42`, `backup-2026-10-02`), unique across concurrent jobs. Reusing an id restarts that activity. | | `state` | **Required on every action**, including `update` and `end`. `title`, `status`, `progress` (0–1), `icon` (all optional inside). | | `attributes` | `start` only: `name` (shown on the card, and its initial is the fallback icon), optional `logoUrl`. | | `staleDate` | Optional, ms since epoch: when iOS should show the activity as stale. | | `relevanceScore` | Optional, 0–1: ordering when several activities run. | | top-level `title`/`body` | Required as for any push. | `progress` and `relevanceScore` outside 0–1 are a `400`. `update`/`end` for an unknown id still deliver as a normal push. ## Choosing `state.icon` Any SF Symbol name; filled variants read best. Unknown or missing names fall back to the initial of `attributes.name`. | Job | Icons | | --- | --- | | Builds and deploys | `hammer.fill` `gearshape.2.fill` `terminal.fill` `testtube.2` `server.rack` | | Transfers and backups | `arrow.up.circle.fill` `arrow.down.circle.fill` `arrow.triangle.2.circlepath` `externaldrive.fill` | | Orders and deliveries | `shippingbox.fill` `box.truck.fill` `cart.fill` `creditcard.fill` `fork.knife` | | Time and tracking | `timer` `hourglass` `calendar` `flag.checkered` `figure.run` | | Home and devices | `house.fill` `lightbulb.fill` `thermometer.medium` `bolt.fill` `printer.fill` | | Media | `play.fill` `film.fill` `music.note` `camera.fill` | | Status | `checkmark.circle.fill` `xmark.octagon.fill` `exclamationmark.triangle.fill` `sparkles` | On `end`, set `state.outcome` to `"success"` or `"failure"` and switch the icon to `checkmark.circle.fill` or `xmark.octagon.fill`. A failure shows as **Failed** in red and stays on the Lock Screen until it's seen (up to 4 hours); a success shows **Done** and leaves after 15 minutes. `dismissAfter` (seconds, 0–14400) on the `end` overrides how long a success stays; a failure ignores it. ## TypeScript SDK ```ts import { liveActivity } from "@pushrsh/sdk"; // reads PUSHR_URL and PUSHR_TOKEN const la = liveActivity(`deploy-${build.id}`, { name: "ci.example.com" }); await la.start({ title: `Deploy #${build.id}`, status: "Building image", progress: 0, icon: "hammer.fill" }); try { await build.run(async (pct, step) => la.update({ title: `Deploy #${build.id}`, status: step, progress: pct })); await la.end({ title: `Deploy #${build.id}`, status: "Live", progress: 1, icon: "checkmark.circle.fill" }); } catch (err) { await la.end({ title: `Deploy #${build.id}`, status: "Failed", icon: "xmark.octagon.fill" }); throw err; } ``` The handle sends `attributes` with every call and uses `state.title` / `state.status` as the push's title and body. `start` and `update` take an optional `{ staleDate, relevanceScore }`. ## CLI ```bash pushrsh la start deploy-42 --title "Deploy #42" --status Building --progress 0 --icon hammer.fill --name ci.example.com pushrsh la update deploy-42 --status "Tests pass" --progress 0.6 pushrsh la end deploy-42 --status Live pushrsh la test # a demo activity, to check the phone receives them ``` In a shell script, end the activity from a `trap` so a crash still ends it: ```bash ID="backup-$(date +%Y%m%d)" pushrsh la start "$ID" --title "Nightly backup" --status Starting --progress 0 --icon externaldrive.fill trap 'pushrsh la end "$ID" --status Failed' ERR rsync … && pushrsh la update "$ID" --status Verifying --progress 0.8 pushrsh la end "$ID" --status Done ``` ## Good practice - **Update on meaningful change**: a new step, or progress moving a few percent. Not every loop tick; throttle to roughly one update every few seconds. - **Status text is the headline**: "Running tests (212/380)", not "In progress". - **Always end** in `finally`/`trap`, with the real outcome: `outcome: "failure"` on error, so it doesn't read as finished successfully. - Unknown total? Omit `progress` and keep `status` descriptive. - Pair with a normal push for the final result if the user should be alerted (`priority: "high"` on failure). ## When it doesn't show - The user needs iOS 16.2+ with Live Activities allowed for pushr (Settings → pushr → Live Activities). - On Android, pushr's notifications and its "Live updates" channel must be on (Settings → Apps → pushr → Notifications). Android needs no APNs setup. - `start` needs the phone to have registered for push-to-start, which the app does on first launch. - Self-hosted servers need the `APNS_*` variables set (`APNS_AUTH_KEY`, `APNS_KEY_ID`, `APNS_TEAM_ID`, `APNS_BUNDLE_ID`, `APNS_ENVIRONMENT`). Without `APNS_AUTH_KEY` iPhones get a normal push instead; Android phones still show the live update. --- --- name: pushr-alerts description: Set up urgent, on-call style alerting with pushr: priorities that break through Focus, ack-or-escalate pushes that re-alert until acknowledged, on-call rotations that escalate from one teammate to the next, critical alerts that ring through mute, quiet hours, and webhook adapters that turn GitHub, Sentry and Grafana events into pushes without code. Use when the user asks to "page me", "wake me up if prod goes down", "keep alerting until I respond", "on-call alerts", "escalate to my teammate", "ring even on silent", "forward GitHub/Sentry/Grafana to pushr", or "don't bother me at night unless it's critical". --- # Alerts, escalation and webhooks with pushr Sending basics are in the `pushr-notify` skill. Full reference: https://pushr.sh/llms-full.txt ## Match the urgency | Situation | Send | | --------- | ---- | | FYI, can wait for the next time they look | `priority: "low"` | | Should see it, no rush | default (normal) | | Needs attention soon, even in Focus | `priority: "high"` (time-sensitive) | | Must not be missed until someone responds | `priority: "high"` + `ack` | Escalate on state *transitions* (healthy → down), send a matching "recovered" push at normal priority, and don't repeat while the state holds. Give the alert and its recovery the same `replaceKey` (e.g. `"api-prod-health"`): the recovery then replaces the alert on the Lock Screen instead of leaving a stale "down" behind, the feed keeps both as a timeline, and any `ack` loop on the alert stops once it's replaced. To be alerted when a scheduled job *doesn't run*, use a heartbeat instead of sending pushes yourself: see the `pushr-heartbeats` skill. ## Ack-or-escalate ```json { "title": "api-prod is down", "body": "5xx rate 38% across 3 regions", "priority": "high", "url": "https://status.example.com/incidents/91", "ack": { "timeoutSec": 120, "maxAttempts": 5 } } ``` - `timeoutSec` (10–86400): seconds between re-pushes. - `maxAttempts` (integer 1–20): re-pushes **after** the first send. `5` means up to 6 pushes. - Re-pushes are time-sensitive and ignore quiet hours. A **muted** source app stays silent. - Tapping the notification, or opening its `url`, acknowledges it and stops the loop. - Unacknowledged pushes sit at the top of the pushr feed with an "ack needed" badge. - With `deliverAt`, the ack timer starts from the delivery time. CLI: `pushrsh "api-prod is down" "5xx 38%" -p high --ack 120/5`. Pick `timeoutSec` from how long a response may reasonably take (60–300 s for paging), and `maxAttempts` so the total window matches your escalation policy (e.g. 120 s × 5 ≈ 10 minutes). After the last attempt pushr stops; if you need a second person, escalate from your own system. ## On-call escalation (set by the app's owner) If the source app is shared, its owner can set an on-call rotation in the app (source app → **On-call**, Pro on pushr cloud). Then an urgent push (one with `ack`, or priority 7+) reaches the first person on call only, and one more person each unacknowledged round, instead of everyone at once. - Rounds wait `ack.timeoutSec`, or the app's **Escalate after** (1–60 min) when the push has no `ack`; pushr extends the ack loop to reach everyone. - Acknowledging on any phone stops it; weekly rotation moves who's first. - The request doesn't change: send `ack` and `priority: "high"` as usual and let the app's settings decide who gets paged. Don't build your own rotation in the sender. ## Critical alerts (allowed by the app's owner) `"critical": true` asks for an iOS critical alert, which plays its sound even on mute and in Do Not Disturb. It only takes effect where the source app's owner set **Critical alerts** to *Marked critical* (or *All urgent*, which also covers every `ack`/priority 7+ push) and the phone granted permission; otherwise it's an ordinary push. Reserve it for things that justify waking someone through silent: safety, data loss, a production outage. Critical alerts ignore quiet hours; a muted app stays silent. iOS rings through mute only once Apple has approved pushr's entitlement; until then they arrive as time-sensitive. On Android they use pushr's "Critical alerts" channel, which sounds as an alarm and rings through Do Not Disturb once the user lets that channel override it. ```json { "title": "Freezer above -10°C", "body": "Walk-in #2 · 4°C", "priority": "high", "critical": true, "ack": { "timeoutSec": 120, "maxAttempts": 5 } } ``` ## Quiet hours and mutes (set by the user in the app) - **Quiet hours** (per source app, Pro on pushr cloud): pushes arrive passively during the window, except ones with `ack`. - **Mute** (per source app): nothing alerts, ack included; pushes still land in the feed. These are the user's controls; senders don't override them. If the user wants night-time silence except emergencies, tell them to set quiet hours and send emergencies with `ack`. ## Webhook adapters (no code) Point a provider's webhook at pushr. Auth is the source-app token, as a header or in the URL: ``` $PUSHR_URL/hooks/github?token=$PUSHR_TOKEN $PUSHR_URL/hooks/sentry?token=$PUSHR_TOKEN $PUSHR_URL/hooks/grafana?token=$PUSHR_TOKEN ``` Prefer `Authorization: Bearer $PUSHR_TOKEN` where the provider allows custom headers: a token in the query string can end up in the provider's logs. Treat the URL as a secret either way. ### GitHub Repo or org → Settings → Webhooks → payload URL above, content type `application/json`. What gets pushed: | Event | Sent when | Priority | | ----- | --------- | -------- | | `push` | Always | 5 | | `pull_request` | Opened, reopened, ready for review, closed/merged | 6 when opened, else 5 | | `issues` | Opened or reopened | 5 | | `release` | Published | 7 | | `workflow_run`, `check_run` | Failed or timed out (successes are ignored) | 8 | | `deployment_status` | Finished | 8 on failure/error, else 6 | | Any other event | Always | 5 | Subscribe only to the events the user cares about (often just `workflow_run` + `release`). Ignored events get `200 { ignored: true }`. ### Sentry Internal Integration (or legacy webhook plugin) → webhook URL above. Level → priority: `debug` 2, `info` 4, `warning`/`warn` 6, `error` 8, `fatal` 9, anything else 5. ### Grafana Alerting → Contact points → Webhook → URL above. One push per alert batch, titled ` ( firing)`, and ` resolved` at priority 4 when it clears. Severity label → priority: `info` 5, `warning` 6, `high`/`error` 8, `critical`/`emergency` 9, anything else 6. Grafana doesn't sign payloads, so the token is the only authentication. ### Signing secrets GitHub (`X-Hub-Signature-256`, `sha256=`) and Sentry (`Sentry-Hook-Signature`, hex) can sign deliveries. Set the same secret in the provider and in pushr (source app → **API & token** → **Webhook integrations**); unsigned or mismatched deliveries then get `401 { "error": "Invalid signature" }`. Adapters return `202 { id, scheduledFor: null }` when a push is queued and `200 { ignored: true, provider }` when an event is skipped. Errors match `/notify`, except there's no `409`: adapters take no `Idempotency-Key`. ## Need richer alerts than an adapter gives? Send your own `POST /notify` from a small relay (a Worker or function that receives the provider webhook), so you control the title, priority, `url`, `ack` and `actions` (for example an "Acknowledge in PagerDuty" callback; see the `pushr-actions` skill). --- --- name: pushr-heartbeats description: Monitor cron jobs, workers and backups with pushr heartbeats, websites and APIs with pushr uptime checks, and publish them on a public status page, so the user's phone is alerted when a job stops running or a URL stops answering, and again when it recovers. Use when the user asks to "tell me if my cron stops", "alert me if the backup didn't run", "dead man's switch", "monitor this scheduled job", "uptime monitoring", "tell me if my site goes down", "health check my API", "UptimeRobot / healthchecks.io / Cronitor style", "status page", or "make sure this worker is still alive". --- # Heartbeats, uptime checks and status pages with pushr Two monitors, one alert path: - **Heartbeat:** the job pings pushr. Use it for anything that *runs*: cron, backups, queues, scheduled CI. Below first. - **Uptime check:** pushr requests a URL. Use it for anything that *answers*: websites, APIs, health endpoints. See [Uptime checks](#uptime-checks). ## Heartbeats A heartbeat catches the failure a notification can't report: a job that silently stopped. The job pings pushr each time it runs; pushr pushes to the phone when a ping is late or the job reports a failure, and again when it recovers. Sending basics are in the `pushr-notify` skill. Full reference: https://pushr.sh/llms-full.txt Read `PUSHR_URL` and `PUSHR_TOKEN` from the environment or the scheduler's secrets. Never paste the token into a crontab or code. ### The endpoints All take `Authorization: Bearer $PUSHR_TOKEN`. | Request | Meaning | | ------- | ------- | | `GET` or `POST /heartbeat/` | The job ran. Starts a new window. | | `POST /heartbeat//start` | The job started. Optional; the next ping then reports how long it took. | | `POST /heartbeat//fail` | The job failed. Alerts at once; a text body (≤ 500 chars) becomes the alert text. | | `DELETE /heartbeat/` | Stop watching it. | - ``: up to 64 letters, digits, `.`, `-`, `_`, unique per source app. Name it after the job: `nightly-backup`, `invoice-sync`. - `?every=`: how often the job runs, from `1m` to `30d` (`90s`, `15m`, `1h`, `1d`, or plain seconds). **Required on the first ping**, which creates the heartbeat; omit or repeat it afterwards (repeating keeps the config in code, which is better). - `?grace=`: extra time past `every` before alerting, up to `7d`. Default 20% of `every`, between 1 minute and 1 hour. Set it to the job's normal run-time spread: a backup that takes 10–40 minutes wants `grace=1h`. - Response: `200 { ok, name, status: "up"|"down"|"paused", everySec, graceSec, dueAt }`. Errors: `400` bad name/interval or `code: "EVERY_REQUIRED"`, `401` bad token, `403 code: "PRO_REQUIRED"` (pushr cloud Free: 3 heartbeats per account; Pro: 100), `409 code: "HEARTBEAT_LIMIT"` (Pro's 100, or 50 on one app). ### Pick the integration #### Crontab: ping after success ```cron 0 3 * * * /usr/local/bin/backup.sh && curl -fsS -m 10 --retry 3 -H "Authorization: Bearer $PUSHR_TOKEN" "$PUSHR_URL/heartbeat/nightly-backup?every=1d&grace=1h" >/dev/null ``` `&&` means a failed run doesn't ping, so it alerts as *missed* after the grace period. Cron doesn't load shell profiles: put `PUSHR_URL` and `PUSHR_TOKEN` at the top of the crontab or in the script's environment. #### Any command: the CLI wrapper (best default) ```bash pushrsh hb nightly-backup --every 1d --grace 1h -- /usr/local/bin/backup.sh ``` Pings start, then success or fail with the last 500 characters of output, and exits with the command's status. Failures alert immediately instead of waiting for the window to close. #### Shell without the CLI ```bash url="$PUSHR_URL/heartbeat/nightly-backup" auth="Authorization: Bearer $PUSHR_TOKEN" curl -fsS -m 10 -X POST -H "$auth" "$url/start?every=1d" || true if out=$(/usr/local/bin/backup.sh 2>&1); then curl -fsS -m 10 -X POST -H "$auth" "$url" || true else printf '%s' "$out" | tail -c 500 | curl -fsS -m 10 -X POST -H "$auth" --data-binary @- "$url/fail" || true exit 1 fi ``` #### TypeScript ```ts import { heartbeat, withHeartbeat } from '@pushrsh/sdk'; // Wraps the job: start → success, or fail with the error, then rethrows. await withHeartbeat('invoice-sync', { every: '15m' }, syncInvoices); // A long-running worker: check in from its loop. setInterval(() => heartbeat('queue-worker', { every: '5m' }).catch(() => {}), 60_000); ``` #### Python ```python import os, requests def ping(name, suffix="", body=None, every="1d"): try: requests.post( f"{os.environ['PUSHR_URL']}/heartbeat/{name}{suffix}", params={"every": every}, headers={"Authorization": f"Bearer {os.environ['PUSHR_TOKEN']}"}, data=body, timeout=10, ) except requests.RequestException: pass # monitoring must never break the job ping("nightly-backup", "/start") try: run_backup() ping("nightly-backup") except Exception as e: ping("nightly-backup", "/fail", body=repr(e)[:500]) raise ``` #### GitHub Actions (scheduled workflows) ```yaml - name: Check in if: success() run: curl -fsS -H "Authorization: Bearer ${{ secrets.PUSHR_TOKEN }}" "${{ secrets.PUSHR_URL }}/heartbeat/nightly-etl?every=1d&grace=2h" - name: Report failure if: failure() run: curl -fsS -X POST -H "Authorization: Bearer ${{ secrets.PUSHR_TOKEN }}" -d "Run ${{ github.run_id }} failed" "${{ secrets.PUSHR_URL }}/heartbeat/nightly-etl/fail" ``` GitHub can delay scheduled runs by many minutes, so give scheduled workflows a generous `grace`. ### Rules that matter - **Never let monitoring fail the job.** Short timeout, swallow ping errors (`|| true`, `.catch`, `try/except`). - **Ping after the work, not before.** A ping at the start of a job that then crashes reports a healthy run. Use `/start` if you want the start recorded. - **`every` is the schedule, not the run time.** A job every 15 minutes is `every=15m`, however long a run takes; cover run-time spread with `grace`. - **Workers:** ping from the work loop (not a separate timer that keeps pinging while the loop is stuck), at a fraction of `every`. - **Don't also send your own /notify on failure** from the same job: `/fail` already alerts, and recovery replaces it. ### What the user gets | Event | Push | Priority | | ----- | ---- | -------- | | No ping by `dueAt` | "nightly-backup missed its check-in" · Expected every 1d. Last ping 1d 1h ago. | high | | `/fail` | "nightly-backup failed" · the body, or "The job reported a failure." | high | | Next successful ping | "nightly-backup is back up" · Down for 2h 14m. Took 3m 12s. | normal | One alert per outage, and at most 3 down alerts an hour for a flapping job; recovery replaces the alert (replace key `heartbeat:`) and the feed keeps the history. Alerts follow the source app's mutes and quiet hours and don't count toward the monthly quota; pings never count. Lateness is checked every minute. In the app's **Monitors** tab the user can see every heartbeat, and pause one during maintenance; pings are recorded while paused, and only Resume in the app ends the pause. ## Uptime checks ```bash curl -X PUT "$PUSHR_URL/uptime/api" \ -H "Authorization: Bearer $PUSHR_TOKEN" \ -d '{"url":"https://api.example.com/health","every":"1m","keyword":"ok"}' ``` Or `pushrsh uptime api https://api.example.com/health --every 1m --keyword ok`, or `await uptime('api', { url, every: '1m', keyword: 'ok' })` from `@pushrsh/sdk`. `PUT` is idempotent, so put it in deploy scripts or infrastructure code to keep checks next to the services they watch. | Field | Notes | | ----- | ----- | | `url` | `http`/`https` on a public host; private and internal addresses are refused. | | `every` | `1m`–`1h`; on pushr cloud Free, one check and every 5 minutes at most often. | | `method` | `GET` (default) or `HEAD`. | | `keyword` | Body must contain it (≤ 200 chars). Best signal: check for text only a healthy page has, not just a 200. | | `timeout` | 1–30 s, default 10. | | `confirmAfter` | Failures in a row before alerting, 1–5, default 2. Keep 2+ for public sites to ride out blips. | - Passes on status < 400 (redirects aren't followed: point it at the final URL), fails on ≥ 400, missing keyword, error or timeout. - `GET /uptime/` returns the state (`pending`, `up`, `down`, `paused`, last status code and latency); `DELETE` removes it. - Alerts: *api is down* · HTTP 503 · api.example.com/health (high), then *api is back up* · Down for 12m. Responded in 182ms. Same rules as heartbeats: one per outage, replace key `uptime:`, quota-free. - Point it at a cheap health endpoint, not a heavy page; the check runs from pushr's servers (your own Convex deployment, if self-hosted) with user agent `pushr-uptime/1` (allow it through bot protection). ## Status pages The user can publish chosen heartbeats and uptime checks at `status.pushr.sh/` (**Monitors → + → Status page** in the app; Pro on pushr cloud): current status, 90 days of uptime and recent incidents, never URLs or error text. The data is public JSON at `GET $PUSHR_URL/status-page/` (`title`, `overall`, `monitors[]` with `status`, `uptime`, 90 `days` of `downMs`, and `incidents[]`) if they want it on their own site. Outages that overlap across a page's monitors show as one incident, with a timeline of what the checks saw. During an outage the user (or anyone who can edit the app) can post updates for visitors from the dashboard or the app: a title, then **Investigating → Identified → Monitoring → Resolved**, each with a short message. If you're connected over MCP, the `incident_update` tool posts one to a monitor's current or latest incident (`monitor`, `status`, `message`, optional `title`). It's public, so draft it with the user unless they asked you to post. Updates are Pro, with status pages. --- --- name: pushr-types description: Typed integration code for the pushr API: drop-in TypeScript types and a dependency-free fetch client with idempotent retries, Python TypedDicts, and the shape of callback payloads, errors and health checks. Use when the user asks to "add types for pushr", "write a pushr client/wrapper/helper", "integrate pushr without the SDK", "typed notify function", "Zod/validation for pushr payloads", or wants pushr in a codebase where adding @pushrsh/sdk isn't wanted (or in Python). --- # Types and clients for pushr Pick the lightest option that fits the project: 1. **TypeScript, dependency OK:** use `@pushrsh/sdk`. It exports `notify`, `liveActivity`, `ping`, the `Pushr` class, `PushrError` and all request types (`NotifyInput`, `Action`, `AckConfig`, `LiveActivityPayload`, …). See the `pushr-notify` skill. 2. **TypeScript, no dependency, or you need idempotent retries:** copy [`types.ts`](types.ts) and [`client.ts`](client.ts) into the project (for example `src/lib/pushr/`). The client runs on any fetch runtime and retries 5xx/network failures only when you pass an `idempotencyKey`, so a retry can never send twice. 3. **Python:** copy [`types.py`](types.py) and post with `requests`/`httpx` (example in `pushr-notify`). 4. **Other languages:** generate structs from `types.ts`; it's the source of truth for field names, which are camelCase on the wire. ## Using the copied client ```ts import { createPushr, PushrError } from "./lib/pushr/client"; const pushr = createPushr({ url: process.env.PUSHR_URL!, token: process.env.PUSHR_TOKEN! }); await pushr.notify( { title: "Invoice paid", body: "INV-2041 · $1,200", url: "https://dash.example.com/invoices/2041" }, { idempotencyKey: `invoice-paid-2041` } // same key on every retry of this event ); try { await pushr.notify({ title: "Disk 92%", body: "prod-db-1", priority: "high" }); } catch (err) { if (err instanceof PushrError && err.body?.code === "QUOTA_EXCEEDED") { // Don't retry: the monthly quota is used up. Log it and move on. } } ``` ## Rules the types can't express Encode these as runtime validation if the payload comes from user input: - `title` and `body` are required strings (`message` is accepted as an alias for `body` on the wire). - `priority` numbers are 1–10; strings are `low`, `normal`, `default`, `high`. Anything else is a `400`. - `actions`: at most 4, unique `id`s, at most one `reply`; `callbackUrl` must be public `https://`. - `ack.timeoutSec` 10–86400; `ack.maxAttempts` integer 1–20. - `liveActivity.state` is required on every action; `progress` and `relevanceScore` are 0–1. - `deliverAt` must be a number (ms since epoch), not an ISO string, and ≥ now − 60 s. - `Idempotency-Key` header: up to 255 characters. As a Zod schema, for example: ```ts import { z } from "zod"; const Action = z.discriminatedUnion("kind", [ z.object({ kind: z.literal("open_url"), id: z.string(), label: z.string(), url: z.string().url(), destructive: z.boolean().optional() }), z.object({ kind: z.literal("callback"), id: z.string(), label: z.string(), callbackUrl: z.string().url().startsWith("https://"), destructive: z.boolean().optional(), authRequired: z.boolean().optional() }), z.object({ kind: z.literal("reply"), id: z.string(), label: z.string(), callbackUrl: z.string().url().startsWith("https://"), placeholder: z.string().optional() }), ]); export const NotifyInput = z.object({ title: z.string().min(1), body: z.string().min(1), priority: z.union([z.enum(["low", "normal", "default", "high"]), z.number().int().min(1).max(10)]).optional(), url: z.string().url().optional(), image: z.string().url().optional(), data: z.record(z.string(), z.unknown()).optional(), actions: z.array(Action).max(4) .refine((a) => new Set(a.map((x) => x.id)).size === a.length, "action ids must be unique") .refine((a) => a.filter((x) => x.kind === "reply").length <= 1, "at most one reply action") .optional(), ack: z.object({ timeoutSec: z.number().min(10).max(86400), maxAttempts: z.number().int().min(1).max(20) }).optional(), deliverAt: z.number().int().optional(), replaceKey: z.string().trim().min(1).max(128).optional(), critical: z.boolean().optional(), }); ``` ## Shapes on the other side - **Callback endpoint** (your server, receiving taps): `ActionCallbackPayload` in `types.ts`, plus headers `X-Pushr-Notification`, `X-Pushr-Action`, `X-Pushr-Source: pushr`. Implementation patterns are in `pushr-actions`. - **Errors:** `PushrErrorBody` (`error`, optional `code`: `APP_PAUSED`, `IDEMPOTENCY_KEY_REUSED`, `QUOTA_EXCEEDED`, `RATE_LIMITED` with a `Retry-After` header). A bad or revoked token is a plain `401 { error: "Invalid token" }`. - **Health:** `GET /healthz` → `HealthResponse`. - **Heartbeats:** `/heartbeat/` (name: `^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$`) with `HeartbeatQuery` → `HeartbeatResponse`; `client.heartbeat(name, …)` in `client.ts`. Patterns are in `pushr-heartbeats`. - **Uptime checks:** `PUT /uptime/` with `UptimeCheckInput` → `UptimeCheck`; `GET` returns it, `DELETE` removes it. - **Status pages:** `GET /status-page/` (no auth) → `StatusPageView`. ### skills/pushr-types/client.ts ```ts /** * A dependency-free pushr client for any fetch runtime, with idempotent * retries (which @pushrsh/sdk doesn't do). Pairs with ./types.ts. */ import type { HealthResponse, HeartbeatQuery, HeartbeatResponse, NotifyInput, NotifyResponse, PushrErrorBody } from './types'; export class PushrError extends Error { constructor( message: string, readonly status: number, readonly body?: PushrErrorBody ) { super(message); this.name = 'PushrError'; } /** 5xx and network errors are worth retrying; 4xx are not. */ get retryable(): boolean { return this.status === 0 || this.status >= 500; } } export interface PushrClientOptions { url: string; token: string; fetch?: typeof fetch; /** Attempts for retryable failures when an idempotencyKey is given. Default 4. */ maxAttempts?: number; } export function createPushr({ url, token, fetch: f = fetch, maxAttempts = 4 }: PushrClientOptions) { const base = url.replace(/\/+$/, ''); async function once(input: NotifyInput, idempotencyKey?: string): Promise { let res: Response; try { res = await f(`${base}/notify`, { method: 'POST', headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json', ...(idempotencyKey ? { 'Idempotency-Key': idempotencyKey } : {}) }, body: JSON.stringify(input) }); } catch (err) { throw new PushrError(err instanceof Error ? err.message : 'Network error', 0); } if (res.ok) return (await res.json()) as NotifyResponse; const body = (await res.json().catch(() => undefined)) as PushrErrorBody | undefined; throw new PushrError(body?.error ?? `HTTP ${res.status}`, res.status, body); } return { /** * Sends one notification. With an idempotencyKey (≤ 255 chars, e.g. a job id), * retryable failures are retried with backoff and can never send twice. */ async notify(input: NotifyInput, opts: { idempotencyKey?: string } = {}): Promise { const attempts = opts.idempotencyKey ? maxAttempts : 1; for (let i = 1; ; i++) { try { return await once(input, opts.idempotencyKey); } catch (err) { if (!(err instanceof PushrError) || !err.retryable || i >= attempts) throw err; await new Promise((r) => setTimeout(r, 500 * 2 ** (i - 1))); } } }, /** Check in a heartbeat; `kind` "start" or "fail" (with `message`) for those events. */ async heartbeat( name: string, opts: HeartbeatQuery & { kind?: 'start' | 'fail'; message?: string } = {} ): Promise { const query = new URLSearchParams(); if (opts.every !== undefined) query.set('every', String(opts.every)); if (opts.grace !== undefined) query.set('grace', String(opts.grace)); const res = await f( `${base}/heartbeat/${encodeURIComponent(name)}${opts.kind ? `/${opts.kind}` : ''}${query.size ? `?${query}` : ''}`, { method: 'POST', headers: { Authorization: `Bearer ${token}` }, body: opts.message } ); if (res.ok) return (await res.json()) as HeartbeatResponse; const body = (await res.json().catch(() => undefined)) as PushrErrorBody | undefined; throw new PushrError(body?.error ?? `HTTP ${res.status}`, res.status, body); }, async health(): Promise { const res = await f(`${base}/healthz`); if (!res.ok) throw new PushrError(`HTTP ${res.status}`, res.status); return (await res.json()) as HealthResponse; } }; } ``` ### skills/pushr-types/types.py ```python """pushr HTTP API types for Python 3.9+. Reference: https://pushr.sh/llms-full.txt""" from __future__ import annotations from typing import Any, Dict, List, Literal, Optional, TypedDict, Union # 1-3 passive, 4-6 normal (default), 7-10 time-sensitive. Priority = Union[Literal["low", "normal", "default", "high"], int] class OpenUrlAction(TypedDict, total=False): kind: Literal["open_url"] id: str label: str url: str destructive: bool class CallbackAction(TypedDict, total=False): kind: Literal["callback"] id: str label: str callbackUrl: str # public https:// only destructive: bool authRequired: bool class ReplyAction(TypedDict, total=False): kind: Literal["reply"] id: str label: str callbackUrl: str placeholder: str Action = Union[OpenUrlAction, CallbackAction, ReplyAction] class AckConfig(TypedDict): timeoutSec: int # 10-86400 maxAttempts: int # 1-20 re-pushes after the first send class LiveActivityState(TypedDict, total=False): title: str status: str progress: float # 0-1 icon: str # SF Symbol name outcome: Literal["success", "failure"] # on end class LiveActivityPayload(TypedDict, total=False): action: Literal["start", "update", "end"] # required activityId: str # required state: LiveActivityState # required on every action attributes: Dict[str, str] # start only: name, logoUrl staleDate: int # ms since epoch relevanceScore: float # 0-1 dismissAfter: int # on end: seconds a finished activity stays, 0-14400 class NotifyInput(TypedDict, total=False): title: str # required body: str # required priority: Priority url: str image: str data: Dict[str, Any] actions: List[Action] # at most 4 ack: AckConfig liveActivity: LiveActivityPayload deliverAt: int # ms since epoch; must be a number replaceKey: str # <= 128 chars; a newer push with the same key replaces this one critical: bool # rings through mute where the app allows critical alerts class NotifyResponse(TypedDict): id: str scheduledFor: Optional[int] class HeartbeatResponse(TypedDict): ok: bool name: str status: Literal["up", "down", "paused"] everySec: int graceSec: int dueAt: Optional[int] # ms since epoch; None while down or paused class UptimeCheckInput(TypedDict, total=False): url: str # required every: Union[str, int] # required: "1m".."1h" or seconds method: Literal["GET", "HEAD"] keyword: str timeout: int # seconds, 1-30 confirmAfter: int # 1-5 class ActionCallbackPayload(TypedDict, total=False): notificationId: str actionId: str respondedAt: int reply: str # kind="reply" only ``` ### skills/pushr-types/types.ts ```ts /** * pushr HTTP API types, matching @pushrsh/sdk. Copy into a project that * can't take the SDK as a dependency. Reference: https://pushr.sh/llms-full.txt */ /** 1–3 passive, 4–6 normal (default), 7–10 time-sensitive. Strings: low=3, normal/default=5, high=8. */ export type Priority = 'low' | 'normal' | 'default' | 'high' | number; export type Action = | { kind: 'open_url'; id: string; label: string; url: string; destructive?: boolean } | { kind: 'callback'; id: string; label: string; callbackUrl: string; destructive?: boolean; authRequired?: boolean } | { kind: 'reply'; id: string; label: string; callbackUrl: string; placeholder?: string }; export interface AckConfig { /** 10–86400 seconds between re-pushes. */ timeoutSec: number; /** 1–20 re-pushes after the initial send. */ maxAttempts: number; } export interface LiveActivityState { title?: string; status?: string; /** 0–1 */ progress?: number; /** An SF Symbol name, e.g. "hammer.fill". */ icon?: string; /** On end: success shows green; failure shows red and stays until dismissed. */ outcome?: 'success' | 'failure'; } export interface LiveActivityAttributes { name?: string; logoUrl?: string; } export interface LiveActivityPayload { action: 'start' | 'update' | 'end'; /** Stable per job; reused for update and end. */ activityId: string; /** Required on every action. */ state: LiveActivityState; /** Only on start. */ attributes?: LiveActivityAttributes; /** ms since epoch */ staleDate?: number; /** 0–1 */ relevanceScore?: number; /** On end: seconds a finished activity stays, 0–14400. A failure ignores it. */ dismissAfter?: number; } /** Body of POST /notify. */ export interface NotifyInput { title: string; body: string; priority?: Priority; url?: string; image?: string; data?: Record; /** Legacy single button; `actions` wins if both are set. */ action?: { label: string; url: string }; /** At most 4; unique ids; at most one reply. */ actions?: Action[]; ack?: AckConfig; liveActivity?: LiveActivityPayload; /** ms since epoch, ≥ now − 60 s. Must be a number on the wire. */ deliverAt?: number; /** ≤ 128 chars, per source app. A newer push with the same key replaces this one. */ replaceKey?: string; /** Ring through mute, where the source app's owner allows critical alerts. */ critical?: boolean; } /** 202 Accepted, or 200 with `Idempotent-Replay: true` for a replayed Idempotency-Key. */ export interface NotifyResponse { id: string; scheduledFor: number | null; } /** A bad or revoked token is a plain 401 `{ error: "Invalid token" }`, with no code. */ export type PushrErrorCode = | 'APP_PAUSED' | 'IDEMPOTENCY_KEY_REUSED' | 'QUOTA_EXCEEDED' | 'RATE_LIMITED' | 'EVERY_REQUIRED' | 'HEARTBEAT_LIMIT' | 'PRO_REQUIRED' | 'UPTIME_LIMIT'; /** Every error response: 400, 401, 403, 409, 429, 500. */ export interface PushrErrorBody { error: string; code?: PushrErrorCode | string; /** On QUOTA_EXCEEDED. */ tier?: string; count?: number; limit?: number; /** pushr cloud, on QUOTA_EXCEEDED and APP_PAUSED, when configured. */ upgrade?: string; } /** GET /healthz */ export interface HealthResponse { ok: true; version: string; selfHosted: boolean; appleSignIn: boolean; } /** What pushr POSTs to an action's callbackUrl. Headers: X-Pushr-Notification, X-Pushr-Action, X-Pushr-Source: pushr. */ export interface ActionCallbackPayload { notificationId: string; actionId: string; /** ms since epoch */ respondedAt: number; /** kind: "reply" only; up to 2,000 characters. */ reply?: string; } /** * `/heartbeat/[/start|/fail]` query. An interval is seconds, or a number * with s, m, h or d ("15m"). `every` (1m–30d) is required on the first ping. */ export interface HeartbeatQuery { every?: string | number; /** ≤ 7d. Default 20% of every, clamped to 1m–1h. */ grace?: string | number; } /** 200 from GET/POST /heartbeat/, /start and /fail. */ export interface HeartbeatResponse { ok: true; name: string; status: 'up' | 'down' | 'paused'; everySec: number; graceSec: number; /** When pushr alerts if no ping arrives; null while down or paused. */ dueAt: number | null; } /** PUT /uptime/ body. Intervals are seconds or "1m".."1h". */ export interface UptimeCheckInput { url: string; every: string | number; method?: 'GET' | 'HEAD'; /** ≤ 200 chars; not with HEAD. */ keyword?: string; /** Seconds, 1–30. Default 10. */ timeout?: number | string; /** Failures in a row before alerting, 1–5. Default 2. */ confirmAfter?: number; } /** 200 from PUT and GET /uptime/. */ export interface UptimeCheck { ok: true; name: string; url: string; method: 'GET' | 'HEAD'; intervalSec: number; timeoutSec: number; keyword: string | null; confirmAfter: number; status: 'pending' | 'up' | 'down' | 'paused'; lastCheckedAt: number | null; lastStatusCode: number | null; lastLatencyMs: number | null; lastError: string | null; downSince: number | null; } /** GET /status-page/, public. */ export interface StatusPageView { title: string; description: string | null; logoUrl: string | null; logoShape: 'circle' | 'free' | 'square'; /** Hex color, e.g. "#3E7BFA". */ accent: string | null; theme: 'auto' | 'light' | 'dark'; websiteUrl: string | null; announcement: { text: string; tone: 'info' | 'maintenance' | 'warning' } | null; overall: 'operational' | 'degraded' | 'outage'; updatedAt: number; monitors: { label: string; /** The page's section heading for this monitor, if it has one. */ group: string | null; kind: 'heartbeat' | 'uptime'; status: 'pending' | 'up' | 'down' | 'paused'; downSince: number | null; /** 0–1 over the last 90 days, or since the monitor was created. */ uptime: number | null; /** 90 days, oldest first; downMs is -1 before the monitor existed. */ days: { date: string; downMs: number }[]; /** When the monitor was created, ms since epoch. */ since: number; /** Its outages in the window: [start, end], end null while ongoing. */ downtime: [number, number | null][]; }[]; /** Newest first, up to 50 from 90 days; overlapping outages across monitors are one incident. */ incidents: { /** The monitors' names joined ("API and Website"), and the first outage's reason. */ monitor: string; reason: string; startedAt: number; endedAt: number | null; /** Set by the page's owner with an update; null until then. */ title: string | null; /** The latest update's status. */ status: IncidentStatus | null; monitors: { label: string; reason: string; startedAt: number; endedAt: number | null; firstFailedAt: number | null; statusCode: number | null; latencyMs: number | null; recoveredStatusCode: number | null; recoveredLatencyMs: number | null; }[]; /** Oldest first. */ updates: { status: IncidentStatus; body: string; at: number }[]; }[]; } export type IncidentStatus = 'investigating' | 'identified' | 'monitoring' | 'resolved'; /** Webhook adapter (/hooks/github, /hooks/sentry, /hooks/grafana) responses. */ export type AdapterResponse = NotifyResponse | { ignored: true; provider: 'github' | 'sentry' | 'grafana' }; ```