SEND A PUSH IN
ONE POST.

Parameters

Rate limit: This endpoint is limited to 5 calls per minute per IP address.

Overview

Auto-detects device vs group based on ID format (GRP* = group). Supports webhook icons and threading.

Parameters

Key Points

• Single endpoint: /notify-json/{id}
• Required: Must include Content-Type: application/json header
• Auto-detects device vs group based on ID (GRP* = group)
• Returns "type" field so you know what was processed
• No URL encoding needed for the message text
• Supports webhook icons via iconUrl parameter (case-sensitive): small sender avatar
• Supports hero images via imageUrl parameter (case-sensitive): JPEG/PNG/GIF rendered inline when the notification is expanded, ≤ 10 MB
• iconUrl and imageUrl are independent, use either or both
• Threading: Use groupType to group notifications - same type = same thread, different type = separate threads (case-sensitive)
• Robust icon fallback ensures webhook notifications always display properly

Parameters

Note: Both GET and POST methods are supported with identical parameters.

New: Now supports title, iconUrl, and groupType for enhanced notifications.

Parameters

Note: Both GET and POST methods are supported with identical parameters.

New: Now supports title, iconUrl, and groupType for enhanced notifications.

Overview

A Beacon is reverse monitoring: instead of Notify! telling you when something happens, it tells you when something stops happening. Create a beacon in the app (Devices tab > Beacons), pick how often you expect a ping plus a grace period, and paste its ping URL into the cron job, backup script, or device you want watched. If no ping arrives within the period plus grace, every targeted device gets a Down alert (a push, or the next poll for an older poll-only Mac). When pings resume you get an Up recovery push, and while it stays down you get periodic reminders.

Beacons are created and managed inside the app; only the ping URL below is called from your systems. A beacon can alert a single device or a whole Device Group (Macs running Notify Listener included).

Parameters

Methods: GET, POST, and HEAD all behave identically. The request body and Content-Type are ignored, so it works from anything that can hit a URL. Treat the ping URL as a secret: whoever has it can mark your job "alive".

Overview

A Live Activity is a single Lock Screen Live Activity that updates in place: it appears when a job starts, changes while it runs (progress bar, live countdown, status), and disappears when it ends. One Live Activity instead of a stack of notifications. The device address is an upsert: your first call starts the Live Activity (it appears even when the Notify! app is closed, via push-to-start, as long as the app has been opened once on the device), every later call to the same address updates it, and &end=1 finishes it. One static URL is the whole lifecycle; the returned activityId exists for precision when you run several Live Activities at once.

Countdowns cost one request. Send endsIn (seconds from now, never a timestamp: no time zones, no clock skew) and iOS ticks the countdown locally with no further requests. A progress bar costs one request per change. The in-app Builder (Settings > Notification Builder > Live Activity) composes all of this with a live preview and copyable code.

Parameters (start and update share the same fields)

Updates are partial. Send only what changed: {"progress": 94} is a complete update. An explicit null clears a field ({"endsIn": null} removes the countdown). Content-Type: application/json is required for JSON bodies.

There is no type field: the fields ARE the type, and they compose. progress draws a bar, endsIn a ticking countdown, steps makes the bar segmented, metrics a small dashboard, and a deploy Live Activity can carry steps AND a countdown at once. When several compete for the same spot: steps beat the plain bar, which beats the time bar; the featured value runs countdown, then trailing, then the step fraction, then status. metrics replaces the body TEXT line, which makes body a free fallback: phones on older app builds show the sentence, newer ones show the dashboard, so send both. A button composes with any of it.

Or skip JSON entirely: one static URL is the whole API. The device address is an upsert: the first call with query parameters starts the Live Activity, every later call updates it, and &end=1 finishes it: /live-activity/{deviceId}?token=...&title=Laundry&endsIn=2700&progress=25. Since the device id and token never change, that URL can live in a service's configuration forever. Running several Live Activities at once is explicit: pass &new=1 to start extras and address each by its returned activityId; a device call while several are live returns 409 listing them. Add &format=text to a start for a plain-text response containing only the id.

The layouts, at a glance

Every layout below is the same endpoint and the same Live Activity; only the fields differ, and they combine freely. The JSON under each card is the complete body that produces it.

Show the code

Copy

{
  "title": "Photo Backup",
  "body": "iCloud to Synology",
  "symbol": "photo.on.rectangle.angled",
  "tint": "#0A84FF",
  "progress": 68
}

Show the code

Copy

{
  "title": "EV Charge",
  "body": "to 80 percent",
  "symbol": "bolt.fill",
  "tint": "#30D158",
  "endsIn": 2700
}

Show the code

Copy

{
  "title": "Coffee Roast",
  "body": "development",
  "symbol": "cup.and.saucer.fill",
  "tint": "#FF9F0A",
  "steps": 4,
  "step": 3
}

Show the code

Copy

{
  "title": "Greenhouse",
  "body": "74F and 61% humidity",
  "symbol": "leaf.fill",
  "tint": "#66D4CF",
  "metrics": [
    { "label": "TEMP", "value": "74", "unit": "F", "color": "#FF9F0A" },
    { "label": "HUMIDITY", "value": "61%", "color": "#0A84FF" }
  ]
}

Show the code

Copy

{
  "title": "Pricing Page",
  "body": "3 changes since 9:02",
  "symbol": "doc.text.magnifyingglass",
  "tint": "#BF5AF2",
  "status": "Changed"
}

Show the code

Copy

{
  "title": "3D Print",
  "body": "benchy.gcode",
  "symbol": "printer.fill",
  "tint": "#FF375F",
  "progress": 62,
  "button": {
    "title": "Pause",
    "url": "https://octoprint.example.com/api/pause"
  }
}

Show the code

Copy

{
  "title": "Grafana",
  "body": "3 panels firing",
  "symbol": "gauge.with.needle",
  "tint": "#FF9F0A",
  "button": {
    "title": "Open Dashboard",
    "url": "https://grafana.example.com/d/alerts",
    "open": true
  }
}

The two button flavors are one field. You never ask for the full-width treatment; the app decides. A button sent alongside a bar or a metrics row stays the quiet capsule (shot six), and a button sent with none of them becomes the tile (shot seven). The tap differs too: by default your phone makes the request, so the URL can reach a printer or a server on your own network that no cloud service could, while open: true hands the link to the system to open instead.

Ending a Live Activity DELETE

Always end your Live Activity. Without an explicit end, iOS leaves a finished Live Activity on the Lock Screen for up to four hours, so a script that simply stops calling strands a frozen "91%" in front of the user. This is the most commonly missed step in a Live Activity integration.

Idempotent, and forgiving in the device-ID form. Ending an already-finished Live Activity succeeds and reports how it actually finished, so an end-of-job hook never fails for having already worked. Addressed by device ID, no Live Activity is likewise a success, while several Live Activities return the teaching 409 listing them so you can end one by its activityId. Bad credentials always answer a uniform 403, which never reveals whether the id exists.

The one-URL equivalent: &end=1 on the same path does exactly this, so a service that can only be handed a single static URL still gets a clean finish.

# Either form ends it. The body is the last thing the Live Activity shows.
curl -X DELETE "https://push.getnotifyapp.com/live-activity/LA7Q2ZKM?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" -d '{"progress":100,"status":"done"}'

curl "https://push.getnotifyapp.com/live-activity/ABC12345?token=YOUR_TOKEN&end=1&status=done"

Reading status GET

A bare GET, one carrying no content parameters, reads instead of acting:

# Did it finish, and how?
curl "https://push.getnotifyapp.com/live-activity/LA7Q2ZKM?token=YOUR_TOKEN"

# Lost the id? List what is live on the device and reattach
curl "https://push.getnotifyapp.com/live-activity/ABC12345?token=YOUR_TOKEN"

A GET carrying content parameters ACTS instead of reading, with exactly the semantics of POST: ?title=...&endsIn=2700 starts, ?progress=94 updates, &end=1 ends. That is the house /notify idiom, so anything that can only fetch a URL still drives the whole lifecycle.

Overview

A widget is one named value on the Lock Screen that your scripts keep fresh: a temperature, a queue depth, a stock level. Unlike a Live Activity nothing is ever pushed. The phone polls the device's widget list when iOS refreshes its widgets, roughly every 15 minutes and on the operating system's own schedule, so a widget suits numbers that drift, not alerts. A widget also has no lifecycle: there is nothing to end, and it stays until you delete it. Each device holds up to 10.

The device address is an upsert, like /live-activity. With no widgets a call carrying content CREATES one, with exactly one it UPDATES it in place, and with several it returns 409 listing every widgetId so you can address the one you meant. &new=1 always creates another. The returned widgetId (WG + 6) is the precise handle: calls to /widgets/WG2D9FLD always mean that exact widget.

Parameters (create and update share the same fields)

Updates are partial, and null deletes. Send only what changed: {"value": "93"} is a complete update. An absent field is left alone, and an explicit null removes one ({"detail": null}), with one exception: title is the widget's identity in the phone's picker, so it can be replaced but never cleared (a named 400). updatedAt is stamped by the server on every write; sending it yourself is also a named 400. Content-Type: application/json is required for JSON bodies.

Or skip JSON entirely: every field works in the URL. Unlike a Live Activity there is no array-shaped field to exclude, so one address is the whole API: /widgets/{deviceId}?token=...&title=CPU%20Load&value=92&unit=%25 creates the widget on its first call and keeps updating it forever after. Add &new=1 to create extras, &format=text to a create for a plain-text response containing only the id, and &delete=1 to delete. A non-empty JSON body wins entirely over query parameters, so the two dialects can never half-merge.

The widget, at a glance

Each screenshot is one widget wearing both of its Lock Screen faces, the rectangle and the circle, side by side. The JSON under each card is the exact create body that produced it.

Show the code

Copy

{
  "title": "CPU Load",
  "value": "92",
  "unit": "%",
  "detail": "8 cores, load rising",
  "symbol": "cpu",
  "tint": "#0A84FF",
  "progress": 92
}

Show the code

Copy

{
  "title": "Sales Today",
  "value": "$1,024",
  "detail": "up 12% on yesterday",
  "symbol": "cart.fill",
  "tint": "#30D158"
}

Show the code

Copy

{
  "title": "Greenhouse",
  "value": "74",
  "unit": "F",
  "detail": "vents open",
  "symbol": "leaf.fill",
  "tint": "#66D4CF"
}

After you add the widget (touch and hold the Lock Screen, Customize, pick Notify!), tap the widget while still in customize mode to choose which of your widgets it shows.

Overview

A screen widget is a Home Screen tile (small, medium or large) that persists: where a Live Activity appears when a job starts and leaves when it ends, a screen widget is always there, showing the latest thing your script stored. It carries the whole Live Activity content set: title, body, symbol, tint, a progress bar, segmented steps, a countdown, a metrics grid, a button. The point is the fan-out: one JSON body drives a Live Activity while a job runs and a Home Screen tile forever, so a script posts the same payload to both addresses. Like a Lock Screen widget, nothing is ever pushed. The phone polls the device's list when iOS refreshes its widgets, roughly every 15 minutes and on the operating system's own schedule, so a screen widget suits things worth glancing at, not alerts. It has no lifecycle either: there is nothing to end, and it stays until you delete it. Each device holds up to 10.

The tile arrives with the September 2026 app update. The server accepts, stores and serves screen widgets on its own, so every call on this page works from any script. The Notify! Dashboard widget that renders them ships in the September 2026 update of the Notify! app (6.09.03), where screen widgets are managed under Settings > Home Screen Widgets and the tile is placed through iOS's own Home Screen widget picker. Creating one through the API never puts anything on screen by itself.

The device address is an upsert, like /widgets. With no screen widgets a call carrying content CREATES one, with exactly one it UPDATES it in place, and with several it returns 409 listing every screenWidgetId so you can address the one you meant. &new=1 always creates another. The returned screenWidgetId (SW + 6) is the precise handle: calls to /screenwidgets/SW3K9QZ2 always mean that exact screen widget.

Parameters (create and update share the same fields)

Updates are partial, and null deletes. Send only what changed: {"progress": 94} is a complete update. An absent field is left alone, and an explicit null removes one ({"endsIn": null} drops the countdown), with one exception: title is the screen widget's identity in the phone's picker, so it can be replaced but never cleared. Sending null, an empty string or a whitespace-only string for it on an update answers 400 with the message Field "title" cannot be cleared; a screen widget needs a name. Content-Type: application/json is required for JSON bodies.

Or skip JSON entirely: every field except metrics and button works in the URL. One address is the whole API: /screenwidgets/{deviceId}?token=...&title=Laundry&progress=25&endsIn=2700 creates the screen widget on its first call and keeps updating it forever after. Add &new=1 to create extras, &format=text to a create for a plain-text response containing only the id, and &delete=1 to delete. A non-empty JSON body wins entirely over query parameters, so the two dialects can never half-merge. Only JSON can say null. A GET that carries content parameters acts exactly like a POST; only a bare GET reads.

Live Activity only fields are ignored, not refused. keepFor (how long a finished Live Activity lingers) and end (the flag that finishes one) mean nothing on a surface that never ends, so the server drops them silently instead of answering 400. That is deliberate: the exact body you send to /live-activity, including the end-of-job one, works here unchanged.

What it looks like

The tile ships with the September 2026 update of the Notify! app, and screenshots of it are still to come, so there are none here yet. What can be said today: the content contract is the Live Activity contract verbatim, so every body in the Live Activity gallery above is a valid screen widget body. Three of them, unchanged, as create bodies for a Home Screen tile:

Progress: a bar you drive yourself, from 0 to 100

{
  "title": "Photo Backup",
  "body": "iCloud to Synology",
  "symbol": "photo.on.rectangle.angled",
  "tint": "#0A84FF",
  "progress": 68
}

Countdown: iOS ticks it on the tile, so one request runs the whole 45 minutes

{
  "title": "EV Charge",
  "body": "to 80 percent",
  "symbol": "bolt.fill",
  "tint": "#30D158",
  "endsIn": 2700
}

Metrics: a small dashboard, with body as the fallback line

{
  "title": "Greenhouse",
  "body": "74F and 61% humidity",
  "symbol": "leaf.fill",
  "tint": "#66D4CF",
  "metrics": [
    { "label": "TEMP", "value": "74", "unit": "F", "color": "#FF9F0A" },
    { "label": "HUMIDITY", "value": "61%", "color": "#0A84FF" }
  ]
}

Overview

Deploying Notify! to a fleet? Managed App Configuration auto-joins every managed device into one Device Group, so a single /notify-group webhook pages the whole fleet with zero per-device setup. On launch the app reads two keys from its managed configuration, validates them, and silently joins the group. The group shows an enterprise badge on the device and its Leave button is disabled while managed.

Requirements (read this first)

Most "it does not work" reports are one of these three.

1. The app must be installed as a MANAGED app by your MDM. iOS only delivers managed app configuration to apps the MDM itself installed (App Store / VPP deployment). If the user installed the app manually, or you are testing a TestFlight build, the configuration never reaches the app. There is no error anywhere; it is simply absent.

2. Use your MDM's App Configuration feature, NOT a configuration profile. Installing a .mobileconfig profile (manually or via MDM) does not populate managed app configuration and cannot work. If you used an older Notify! example .mobileconfig file, that approach was wrong and has been retired; use the app-config keys below instead.

3. The key names are case-sensitive: groupID (capital I, capital D) and groupToken. Values must be exact; the app trims stray spaces and newlines but rejects anything else malformed.

Configuration keys