# REST API

Send notifications and manage users from your backend. All requests go to `https://api.pushgeni.us` and use JSON.

## JavaScript SDK

On Node.js 20+, Bun, Deno, or Cloudflare Workers, `@pushgenius/javascript` wraps every call on this page. It retries network errors, timeouts, and 5xx responses, and gives each send an idempotency key so a retry can never deliver the same notification twice.

```sh
npm install @pushgenius/javascript
```

```js
import { BigBrain } from "@pushgenius/javascript";

const bigBrain = new BigBrain({
  appId: process.env.PUSHGENIUS_APP_ID,
  apiKey: process.env.PUSHGENIUS_API_KEY,
});

await bigBrain.notifications.create({
  headings: { en: "Your order shipped" },
  contents: { en: "Tap to track it." },
  include_aliases: { external_id: ["user-123"] },
});

const user = await bigBrain.users.get("external_id", "user-123");
```

Fields use the same names as the requests below. See the [SDK README](https://github.com/PushGenius/js-sdk#readme) for every method, errors, and options. For Supabase, AWS Lambda, Firebase, and Cloudflare Workers, see the [serverless examples](https://pushgeni.us/docs/serverless.md). The rest of this page shows the HTTP requests the SDK makes, for any other language.

## Authentication

Create a REST API key in the dashboard under Settings and send it in the `Authorization` header:

```
Authorization: Key YOUR_REST_API_KEY
```

Keep this key on your server — never ship it inside your app.

## Send a notification

```http
POST /notifications

{
  "app_id": "YOUR_APP_ID",
  "headings": { "en": "Your report is ready" },
  "contents": { "en": "Tap to see this week's numbers." },
  "included_segments": ["Subscribed Users"]
}
```

### Targeting

Choose exactly one way to pick recipients:

- `included_segments` — segment names, like `["Subscribed Users"]` or one you built in the dashboard.
- `filters` — conditions on tags, country, language, app version, or session activity, evaluated at send time.
- `include_aliases` — your own user IDs, for example `{ "external_id": ["user-123"] }`.
- `include_subscription_ids` — specific device subscriptions.

### Scheduling and timezone delivery

```json
{
  "send_after": "2026-11-27T15:00:00Z",
  "delayed_option": "timezone",
  "delivery_time_of_day": "9:00AM"
}
```

`send_after` holds the message until that time. With `delayed_option: "timezone"`, each device receives it at `delivery_time_of_day` in the user’s own timezone.

### Response

```json
{ "id": "b7e2c1d4-5a0f-4c1e-9d55-0e3a8f1c2b77" }
```

If nobody matches your targeting, the request still succeeds with an empty `id` and an `errors` array explaining why, so you can log it without treating it as a failure.

## Users

```http
POST  /apps/:app_id/users
GET   /apps/:app_id/users/by/:alias_label/:alias_id
PATCH /apps/:app_id/users/by/:alias_label/:alias_id
```

Create users with identity, tags, and subscriptions, then read or update them by any alias — most often `external_id`, the ID you passed to `login` in the SDK. For example, `/apps/:app_id/users/by/external_id/user-123`.

## Devices

```http
POST /players
PUT  /players/:id
GET  /players/:id
```

Register or update a single device directly. Most apps let the SDK handle this for them.

Source: https://pushgeni.us/docs/api