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.

npm install @pushgenius/javascript

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 for every method, errors, and options. For Supabase, AWS Lambda, Firebase, and Cloudflare Workers, see the serverless examples. 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

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

{
  "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

{ "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

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

POST /players
PUT  /players/:id
GET  /players/:id