# Push notifications

Register a device's APNs, FCM or browser push token, then send a push with one HTTPS request.

All endpoints live on `https://app.nativenotify.com` and take your **app id** and **app token** — in the body for POSTs, in the URL for GETs. A dashboard session or an [MCP token](/docs/mcp-server) can stand in for the app token on POSTs, for apps that account can access.

## Kinds of push

| Kind                | Audience                                      | Use for                                              |
| ------------------- | --------------------------------------------- | ---------------------------------------------------- |
| **Mass push**       | `{ "type": "all" }` — every registered device | Announcements to everyone.                           |
| **Individual push** | One `deviceId` or one `subscriberId`          | Account alerts, like "your order shipped".           |
| **Group push**      | `{ "type": "group", "key": "…" }`             | Everyone subscribed to a [group](/docs/push/groups). |

All three share one response shape, one inbox entry per targeted device and the same analytics.

## Endpoints

| Endpoint                                                   | Auth | Does                                                                  |
| ---------------------------------------------------------- | ---- | --------------------------------------------------------------------- |
| `POST /api/universal/device/register`                      | body | Register a device and its APNs, FCM or `webPush` token. Idempotent.   |
| `POST /api/universal/device/deregister`                    | body | Remove a device. Idempotent.                                          |
| `POST /api/universal/notifications/send`                   | body | Send to everyone, a device list, a subscriber list or a group.        |
| `POST /api/universal/test-send`                            | body | Send to one device or token and return the result.                    |
| `GET /api/universal/health/:appId/:appToken`               | URL  | Device and token counts.                                              |
| `POST /api/universal/credentials/validate`                 | body | Check the stored FCM and APNs credentials.                            |
| `GET /api/universal/web-push/keys/:appId/:appToken`        | URL  | The app's VAPID public key.                                           |
| `POST /api/universal/groups/subscribe` and `/unsubscribe`  | body | Add or remove subscribers or devices in a [group](/docs/push/groups). |
| `GET`, `POST /api/universal/environments/:appId/:appToken` | URL  | List or switch [environments](/docs/push/environments).               |
| `GET /api/universal/inbox/:appId/:appToken?deviceId=`      | URL  | One device's inbox, with unread, read, read-all and delete actions.   |

Scheduling, AI copy and owner-side reads are account routes under `/api/apps/:appId/…`. They take a dashboard session or an [MCP token](/docs/mcp-server), never the app token.

## Concepts

- **`deviceId`** is a stable key you choose per install. Registering it again updates the device. A token that arrives with a different `deviceId` moves to that device.
- **`subscriberId`** ties devices to one of your users. Optional; one subscriber can have many devices.
- **Environments:** a device is `production` unless registered as `staging` or `development`, and a send reaches only its own environment. See [Environments](/docs/push/environments).
- **Tokens:** APNs for iOS, FCM for Android, `webPush` for browsers. A mismatched pair is `400 token_platform_mismatch`.
- **Errors** use `{ "error": { "code", "message", "field"? } }` with stable codes like `no_tokens_provided`.
- **Delivery:** APNs and FCM acknowledge a send immediately, and that is the strongest signal a native token gives. Responses say `delivered: null` instead of guessing. See [Verify delivery](/docs/push/verification).

> **Credentials required:**
>
> Sends use **your** FCM v1 service-account JSON (Android) and APNs `.p8` key (iOS). Google shut down the legacy FCM server key, so it isn't accepted. See [Push credentials](/docs/push/credentials).

## Next steps

- [Quickstart](/docs/push/quickstart) — register a device and send a push.
- [Device registration](/docs/push/registration) — every field and error code.
- [Send notifications](/docs/push/sending) — audiences, options and the send response.