Push Notifications API

Send push notifications to your end users’ iOS and Android devices through Apple Push Notification service (APNs) and Firebase Cloud Messaging (FCM). Orbit holds your provider credentials and exposes a single send endpoint that fans out to the right transport. Base path: /api/v1/push Authentication: API key (X-API-Key) or session JWT.

The notification object

Every device token your mobile app registers, every push you send, and the per-device delivery rows they produce all share the same { data, meta } envelope — this page documents that object end to end: register a token, target a send, and read the delivery status back. The notifications[] array a send returns is one entry per device, so one transport failure never masks the others.

Using the SDKs

The push route has no first-class helper yet — each SDK’s generic escape hatch keeps auth, retries, and the response envelope identical to the typed resources while returning a body you type yourself. The samples below run the same call as the curl example, in the fixed language order used across the hand-written pages.

curl -X POST https://api.orbit.devotel.io/api/v1/push/send \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "user_ids": ["usr_abc123"],
    "title": "Your order has shipped",
    "body": "Tracking #1Z999AA10123456784",
    "data": { "order_id": "ord_42" }
  }'

import { Orbit } from "@devotel-orbit/node";

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY! });

interface PushSendResult {
  notifications: {
    id: string;
    deviceTokenId: string;
    transport: "apns" | "fcm" | "webpush" | "hms";
    status: "sent" | "failed" | "skipped";
    error?: string;
  }[];
  total: number;
  sent: number;
  devices_targeted: number;
}

const res = await orbit.request<{ data: PushSendResult }>(
  "POST",
  "/push/send",
  {
    user_ids: ["usr_abc123"],
    title: "Your order has shipped",
    body: "Tracking #1Z999AA10123456784",
    data: { order_id: "ord_42" },
  },
);

for (const device of res.data.notifications) {
  console.log(device.deviceTokenId, device.transport, device.status);
}

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

res = client.request("POST", "/push/send", json_body={
    "user_ids": ["usr_abc123"],
    "title": "Your order has shipped",
    "body": "Tracking #1Z999AA10123456784",
    "data": {"order_id": "ord_42"},
})
for device in res["data"]["notifications"]:
    print(device["deviceTokenId"], device["transport"], device["status"])

package main

import (
    "context"
    "fmt"
    "os"

    "github.com/devotel/orbit-go/orbit"
)

func main() {
    client, err := orbit.NewClient(os.Getenv("ORBIT_API_KEY"))
    if err != nil {
        panic(err)
    }

    body := map[string]any{
        "user_ids": []string{"usr_abc123"},
        "title":    "Your order has shipped",
        "body":     "Tracking #1Z999AA10123456784",
        "data":     map[string]any{"order_id": "ord_42"},
    }
    var res map[string]any
    if err := client.Request(context.Background(), "POST", "/push/send", nil, body, &res, ""); err != nil {
        panic(err)
    }
    fmt.Println(res["data"].(map[string]any)["sent"])
}

require "orbit_sdk"

client = OrbitSdk::Client.from_env  # reads ORBIT_API_KEY

res = client.request("POST", "/push/send", json_body: {
  user_ids: ["usr_abc123"],
  title: "Your order has shipped",
  body: "Tracking #1Z999AA10123456784",
  data: { order_id: "ord_42" },
})
puts "#{res.dig('data', 'sent')}/#{res.dig('data', 'total')} devices sent"

<?php
require __DIR__.'/vendor/autoload.php';

use Devotel\Orbit\OrbitClient;

$client = OrbitClient::fromEnv();  // reads ORBIT_API_KEY

$res = $client->request('POST', '/push/send', null, [
    'user_ids' => ['usr_abc123'],
    'title' => 'Your order has shipped',
    'body' => 'Tracking #1Z999AA10123456784',
    'data' => ['order_id' => 'ord_42'],
]);
echo $res['data']['sent'].'/'.$res['data']['total'].' devices sent'.PHP_EOL;

The Python, Go, Ruby, and PHP SDKs are core-scope — they wrap the 8 core resources (messaging, voice, contacts, campaigns, verify, numbers) and reach everything else through the untyped client.request() / client.Request(...) / $client->request(...) escape hatch shown above: Python SDK, Go SDK, Ruby SDK, PHP SDK. Raw curl and the SDK escape hatches resolve to the same endpoint. Full SDK index at SDK quickstart.

Device tokens

Your mobile app registers each device’s push token after the user grants permission. Re-register on token rotation; APNs and FCM both rotate tokens periodically.

Method	Path	Purpose
`POST`	`/api/v1/push/register`	Register a device token (mobile app SDK)
`POST`	`/api/v1/push/device-tokens`	Register or update a token (server-side)
`GET`	`/api/v1/push/device-tokens`	List tokens for the current tenant
`DELETE`	`/api/v1/push/device-tokens/{id}`	Unregister a token

Register a device token

POST /api/v1/push/register and POST /api/v1/push/device-tokens are the same operation — the first exists for older SDK clients; new integrations should call /device-tokens. Supply the native APNs or FCM token for ios / android / huawei, or a Web Push subscription envelope for platform: web. Registering a token that already exists just refreshes its owner and last-seen time — it does not create a duplicate.

curl -X POST https://api.orbit.devotel.io/api/v1/push/register \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "usr_abc123",
    "platform": "ios",
    "token": "6f3c1a9b…device-push-token"
  }'

import { Orbit } from "@devotel-orbit/node";

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY! });

interface DeviceToken {
  id: string;
  user_id: string;
  platform: "ios" | "android" | "web" | "huawei";
  token: string;
  app_id: string | null;
  app_install_id: string | null;
  device_id: string | null;
  notification_channel: string | null;
}

const token = await orbit.request<{ data: DeviceToken }>(
  "POST",
  "/push/register",
  {
    user_id: "usr_abc123",
    platform: "ios",
    token: process.env.PUSH_DEVICE_TOKEN!,
  },
);

console.log("Registered token id:", token.data.id);

201 Created returns the token’s Orbit id — save it if you want to target specific devices when sending:

{
  "data": {
    "id": "deviceToken_01J9ZABCDEF1",
    "user_id": "usr_abc123",
    "platform": "ios",
    "token": "6f3c1a9b…device-push-token",
    "app_id": null,
    "app_install_id": null,
    "device_id": null,
    "notification_channel": null
  },
  "meta": {
    "request_id": "req_01J9Z8ABCDEF",
    "timestamp": "2026-08-15T12:00:00Z"
  }
}

List device tokens

GET /api/v1/push/device-tokens lists the tenant’s registered tokens, newest first, capped at 200 rows. Pass ?user_id=<id> to scope the list to one user.

curl "https://api.orbit.devotel.io/api/v1/push/device-tokens?user_id=usr_abc123" \
  -H "X-API-Key: dv_live_sk_your_key_here"

import { Orbit } from "@devotel-orbit/node";

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY! });

interface DeviceTokenRow {
  id: string;
  user_id: string;
  platform: string;
  token: string;
  enabled: boolean;
  last_seen_at: string | null;
  created_at: string;
}

const tokens = await orbit.request<{ data: DeviceTokenRow[] }>(
  "GET",
  "/push/device-tokens?user_id=usr_abc123",
);

for (const row of tokens.data) {
  console.log(row.id, row.platform, row.enabled ? "enabled" : "muted");
}

200 OK returns the rows — use the id values to target a send by device_token_ids, and enabled to see whether a token currently receives pushes:

{
  "data": [
    {
      "id": "deviceToken_01J9ZABCDEF1",
      "user_id": "usr_abc123",
      "platform": "ios",
      "token": "6f3c1a9b…device-push-token",
      "app_id": null,
      "app_install_id": null,
      "device_id": null,
      "endpoint": null,
      "notification_channel": "default",
      "created_at": "2026-08-10T09:12:00Z",
      "last_seen_at": "2026-08-15T11:58:00Z",
      "enabled": true
    },
    {
      "id": "deviceToken_01J9ZABCDEF2",
      "user_id": "usr_abc123",
      "platform": "android",
      "token": "fcm:9a7c…registration-token",
      "app_id": "com.example.myapp",
      "app_install_id": null,
      "device_id": null,
      "endpoint": null,
      "notification_channel": null,
      "created_at": "2026-08-09T17:40:00Z",
      "last_seen_at": "2026-08-12T08:21:00Z",
      "enabled": true
    }
  ],
  "meta": {
    "request_id": "req_01J9Z8ABCDEF",
    "timestamp": "2026-08-15T12:00:00Z"
  }
}

Token lifecycle — register / refresh / deregister

A device’s token is a lifecycle, not a one-time write. Register once when the OS first hands the push token over. Refresh by re-registering the same endpoint every time the OS rotates the token — APNs and FCM both rotate periodically, and a rotated token that is not re-registered stops receiving pushes. Deregister with DELETE /api/v1/push/device-tokens/{id} on sign-out so a retired device no longer receives pushes.

curl -X POST https://api.orbit.devotel.io/api/v1/push/device-tokens \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "usr_abc123",
    "platform": "ios",
    "token": "6f3c1a9b…device-push-token",
    "app_install_id": "install_abc123"
  }'

import { Orbit } from "@devotel-orbit/node";

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY! });

interface DeviceToken {
  id: string;
  user_id: string;
  platform: string;
  token: string;
  app_id: string | null;
  app_install_id: string | null;
  device_id: string | null;
  notification_channel: string | null;
}

const refreshed = await orbit.request<{ data: DeviceToken }>(
  "POST",
  "/push/device-tokens",
  {
    user_id: "usr_abc123",
    platform: "ios",
    token: process.env.PUSH_DEVICE_TOKEN!,
    app_install_id: "install_abc123",
  },
);

console.log("Refreshed token id:", refreshed.data.id);

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

token = client.request("POST", "/push/device-tokens", json_body={
    "user_id": "usr_abc123",
    "platform": "ios",
    "token": "6f3c1a9b…device-push-token",
    "app_install_id": "install_abc123",
})
print("Refreshed token id:", token["data"]["id"])

package main

import (
    "context"
    "fmt"
    "os"

    "github.com/devotel/orbit-go/orbit"
)

func main() {
    client, err := orbit.NewClient(os.Getenv("ORBIT_API_KEY"))
    if err != nil {
        panic(err)
    }

    body := map[string]any{
        "user_id":        "usr_abc123",
        "platform":       "ios",
        "token":          "6f3c1a9b…device-push-token",
        "app_install_id": "install_abc123",
    }
    var token map[string]any
    if err := client.Request(context.Background(), "POST", "/push/device-tokens", nil, body, &token, ""); err != nil {
        panic(err)
    }
    fmt.Println("Refreshed token id:", token["data"].(map[string]any)["id"])
}

require "orbit_sdk"

client = OrbitSdk::Client.from_env  # reads ORBIT_API_KEY

token = client.request("POST", "/push/device-tokens", json_body: {
  user_id: "usr_abc123",
  platform: "ios",
  token: "6f3c1a9b…device-push-token",
  app_install_id: "install_abc123",
})
puts "Refreshed token id: #{token.dig('data', 'id')}"

<?php
require __DIR__.'/vendor/autoload.php';

use Devotel\Orbit\OrbitClient;

$client = OrbitClient::fromEnv();  // reads ORBIT_API_KEY

$token = $client->request('POST', '/push/device-tokens', null, [
    'user_id' => 'usr_abc123',
    'platform' => 'ios',
    'token' => '6f3c1a9b…device-push-token',
    'app_install_id' => 'install_abc123',
]);
echo 'Refreshed token id: '.$token['data']['id'].PHP_EOL;

201 Created returns the stored token row. meta.request_id and meta.timestamp appear on every response — success and error alike — so quote them when reconciling a lifecycle event in your own audit trail:

{
  "data": {
    "id": "deviceToken_01J9ZABCDEF1",
    "user_id": "usr_abc123",
    "platform": "ios",
    "token": "6f3c1a9b…device-push-token",
    "app_id": null,
    "app_install_id": "install_abc123",
    "device_id": null,
    "notification_channel": null
  },
  "meta": {
    "request_id": "req_01J9Z8ABCDEF",
    "timestamp": "2026-08-15T12:00:00Z"
  }
}

Refresh follows the same call: re-registering a token that already exists just refreshes its owner and last-seen time — it does not create a duplicate — and sending app_install_id retires the install’s previous token on a reinstall, so the new token is the only live one. Check last_seen_at and the enabled flag in the list response to spot a token the SDK has not refreshed for a long stretch.

Unregister a device token

DELETE /api/v1/push/device-tokens/{id} removes a token so the device no longer receives pushes — for example on sign-out.

curl -X DELETE https://api.orbit.devotel.io/api/v1/push/device-tokens/deviceToken_01J9ZABCDEF1 \
  -H "X-API-Key: dv_live_sk_your_key_here"

import { Orbit } from "@devotel-orbit/node";

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY! });

await orbit.request(undefined, "DELETE", "/push/device-tokens/deviceToken_01J9ZABCDEF1");
// 204 No Content on success; unknown id -> OrbitApiError with status 404.

Success is 204 No Content with an empty body. An unknown id returns 404 Not Found (NOT_FOUND).

Sending

Method	Path	Purpose
`POST`	`/api/v1/push/send`	Send a push notification to specific devices (`device_token_ids`) or users (`user_ids`)
`GET`	`/api/v1/push/notifications`	List sent notifications

Example — send to a user’s devices

Target a send with either user_ids (every registered device for those users) or device_token_ids (specific device tokens). At least one of the two is required.

curl -X POST https://api.orbit.devotel.io/api/v1/push/send \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "user_ids": ["usr_abc123"],
    "title": "Your order has shipped",
    "body": "Tracking #1Z999AA10123456784",
    "data": { "order_id": "ord_42" },
    "deep_link": "myapp://orders/ord_42"
  }'

import { Orbit } from "@devotel-orbit/node";

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY! });

interface PushSendResult {
  notifications: {
    id: string;
    deviceTokenId: string;
    transport: "apns" | "fcm" | "webpush" | "hms";
    status: "sent" | "failed" | "skipped";
    error?: string;
  }[];
  total: number;
  sent: number;
  devices_targeted: number;
}

const result = await orbit.request<{ data: PushSendResult }>(
  "POST",
  "/push/send",
  {
    user_ids: ["usr_abc123"],
    title: "Your order has shipped",
    body: "Tracking #1Z999AA10123456784",
    data: { order_id: "ord_42" },
    deep_link: "myapp://orders/ord_42",
  },
);

for (const device of result.data.notifications) {
  console.log(device.deviceTokenId, device.transport, device.status);
}

To notify specific devices instead, pass device_token_ids with the ids returned from /api/v1/push/device-tokens:

curl -X POST https://api.orbit.devotel.io/api/v1/push/send \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "device_token_ids": ["deviceToken_01J9ZABCDEF1", "deviceToken_01J9ZABCDEF2"],
    "title": "Your order has shipped",
    "body": "Tracking #1Z999AA10123456784"
  }'

import { Orbit } from "@devotel-orbit/node";

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY! });

interface PushSendResult {
  notifications: {
    id: string;
    deviceTokenId: string;
    transport: string;
    status: string;
    error?: string;
  }[];
  total: number;
  sent: number;
  devices_targeted: number;
}

const result = await orbit.request<{ data: PushSendResult }>(
  "POST",
  "/push/send",
  {
    device_token_ids: ["deviceToken_01J9ZABCDEF1", "deviceToken_01J9ZABCDEF2"],
    title: "Your order has shipped",
    body: "Tracking #1Z999AA10123456784",
  },
);

console.log(`${result.data.sent}/${result.data.total} devices reached`);

Either variant returns 201 Created on an immediate send. The response carries one notifications[] entry per targeted device, so an APNs rejection or a frequency-cap skip on one device never masks the others’ delivery:

{
  "data": {
    "notifications": [
      {
        "id": "pushNotification_01J9ZABCDEF9",
        "deviceTokenId": "deviceToken_01J9ZABCDEF1",
        "transport": "apns",
        "status": "sent"
      },
      {
        "id": "pushNotification_01J9ZABCDEF10",
        "deviceTokenId": "deviceToken_01J9ZABCDEF2",
        "transport": "fcm",
        "status": "skipped",
        "error": "Frequency cap exceeded for this recipient — retry after 3600s"
      }
    ],
    "total": 2,
    "sent": 1,
    "devices_targeted": 2
  },
  "meta": {
    "request_id": "req_01J9Z8ABCDEF",
    "timestamp": "2026-08-15T12:00:00Z"
  }
}

Each entry in the response notifications[] array carries a transport field — apns, fcm, webpush, or hms — identifying which transport was used to reach that device, alongside its deviceTokenId and delivery status. A status of sent, failed, or skipped is per-device; when a device could not be reached, its entry carries an error describing why.

List sent notifications

GET /api/v1/push/notifications returns the tenant’s notification log, newest first — the per-device rows recorded by /push/send — with delivery status and the delivered/opened timestamps the SDK ack endpoints set. Page older rows with ?cursor=<created_at of the last row>&limit=50; each page is capped at 200 rows.

curl "https://api.orbit.devotel.io/api/v1/push/notifications?limit=50" \
  -H "X-API-Key: dv_live_sk_your_key_here"

import { Orbit } from "@devotel-orbit/node";

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY! });

interface NotificationRow {
  id: string;
  device_token_id: string;
  title: string;
  body: string;
  data: Record<string, string> | null;
  status: "sent" | "delivered" | "opened" | "failed";
  sent_at: string;
  delivered_at: string | null;
  opened_at: string | null;
  platform: string;
  user_id: string;
  error: string | null;
  created_at: string;
}

const page = await orbit.request<{ data: NotificationRow[] }>(
  "GET",
  "/push/notifications?limit=50",
);

for (const row of page.data) {
  console.log(row.id, row.status, row.delivered_at ?? "no delivery yet");
}

200 OK returns the page:

{
  "data": [
    {
      "id": "pushNotification_01J9ZABCDEF9",
      "device_token_id": "deviceToken_01J9ZABCDEF1",
      "title": "Your order has shipped",
      "body": "Tracking #1Z999AA10123456784",
      "data": { "order_id": "ord_42" },
      "status": "opened",
      "sent_at": "2026-08-15T12:00:01Z",
      "delivered_at": "2026-08-15T12:00:03Z",
      "opened_at": "2026-08-15T12:04:47Z",
      "unread_count": 1,
      "notification_channel": null,
      "error": null,
      "created_at": "2026-08-15T12:00:01Z",
      "platform": "ios",
      "user_id": "usr_abc123"
    }
  ],
  "meta": {
    "request_id": "req_01J9Z8ABCDEF",
    "timestamp": "2026-08-15T12:00:00Z"
  }
}

Scheduled pushes

To send later, add an ISO 8601 send_at to POST /api/v1/push/send. When send_at is in the future the notification is stored instead of dispatched and the request returns 202 Accepted; a background worker replays it through the same fan-out and suppression logic when the time arrives. Omit send_at (or pass a past instant) to send immediately.

curl -X POST https://api.orbit.devotel.io/api/v1/push/send \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "user_ids": ["usr_abc123"],
    "title": "Flash sale starts soon",
    "body": "20% off for the next hour",
    "send_at": "2026-06-20T09:00:00Z"
  }'

import { Orbit } from "@devotel-orbit/node";

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY! });

interface ScheduledPush {
  id: string;
  status: "scheduled" | "sent" | "cancelled" | "failed";
  send_at: string;
}

const queued = await orbit.request<{ data: ScheduledPush }>(
  "POST",
  "/push/send",
  {
    user_ids: ["usr_abc123"],
    title: "Flash sale starts soon",
    body: "20% off for the next hour",
    send_at: "2026-06-20T09:00:00Z",
  },
);

console.log("Scheduled id:", queued.data.id, queued.data.status);

202 Accepted confirms the push was queued, not sent — read it back or cancel it with the scheduled-push id:

{
  "data": {
    "id": "scheduledPush_01J9ZABCDXYZ",
    "status": "scheduled",
    "send_at": "2026-06-20T09:00:00Z"
  },
  "meta": {
    "request_id": "req_01J9Z8ABCDEF",
    "timestamp": "2026-08-15T12:00:00Z"
  }
}

Manage scheduled pushes that have not yet been sent:

Method	Path	Purpose
`GET`	`/api/v1/push/scheduled`	List scheduled pushes (optional `status` filter: `scheduled`, `sent`, `cancelled`, `failed`)
`GET`	`/api/v1/push/scheduled/{id}`	Read a single scheduled push
`DELETE`	`/api/v1/push/scheduled/{id}`	Cancel a scheduled push that has not been sent yet

List the queue with GET /api/v1/push/scheduled — soonest send_at first, capped at 200 rows:

curl "https://api.orbit.devotel.io/api/v1/push/scheduled?status=scheduled" \
  -H "X-API-Key: dv_live_sk_your_key_here"

import { Orbit } from "@devotel-orbit/node";

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY! });

interface ScheduledPushRow {
  id: string;
  payload: {
    user_ids?: string[];
    device_token_ids?: string[];
    title: string;
    body: string;
  };
  payloadJson?: unknown;
  send_at: string;
  status: "scheduled" | "sent" | "cancelled" | "failed";
  attempts: number;
  last_error: string | null;
  sent_at: string | null;
  created_by: string;
  created_at: string;
  updated_at: string;
}

const page = await orbit.request<{ data: ScheduledPushRow[] }>(
  "GET",
  "/push/scheduled?status=scheduled",
);

for (const item of page.data) {
  console.log(item.id, item.send_at, item.status);
}

{
  "data": [
    {
      "id": "scheduledPush_01J9ZABCDXYZ",
      "payload": {
        "user_ids": ["usr_abc123"],
        "title": "Flash sale starts soon",
        "body": "20% off for the next hour"
      },
      "send_at": "2026-06-20T09:00:00Z",
      "status": "scheduled",
      "attempts": 0,
      "last_error": null,
      "sent_at": null,
      "created_by": "usr_admin1",
      "created_at": "2026-08-15T12:00:00Z",
      "updated_at": "2026-08-15T12:00:00Z"
    }
  ],
  "meta": {
    "request_id": "req_01J9Z8ABCDEF",
    "timestamp": "2026-08-15T12:00:00Z"
  }
}

Read one scheduled push by id — including its full payload, attempt count, and any error from a failed dispatch:

curl https://api.orbit.devotel.io/api/v1/push/scheduled/scheduledPush_01J9ZABCDXYZ \
  -H "X-API-Key: dv_live_sk_your_key_here"

import { Orbit } from "@devotel-orbit/node";

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY! });

interface ScheduledPushRow {
  id: string;
  payload: {
    user_ids?: string[];
    device_token_ids?: string[];
    title: string;
    body: string;
  };
  send_at: string;
  status: "scheduled" | "sent" | "cancelled" | "failed";
  attempts: number;
  last_error: string | null;
  sent_at: string | null;
  created_by: string;
  created_at: string;
  updated_at: string;
}

const item = await orbit.request<{ data: ScheduledPushRow }>(
  "GET",
  "/push/scheduled/scheduledPush_01J9ZABCDXYZ",
);

console.log(item.data.id, item.data.status, item.data.send_at);

{
  "data": {
    "id": "scheduledPush_01J9ZABCDXYZ",
    "payload": {
      "user_ids": ["usr_abc123"],
      "title": "Flash sale starts soon",
      "body": "20% off for the next hour"
    },
    "send_at": "2026-06-20T09:00:00Z",
    "status": "scheduled",
    "attempts": 0,
    "last_error": null,
    "sent_at": null,
    "created_by": "usr_admin1",
    "created_at": "2026-08-15T12:00:00Z",
    "updated_at": "2026-08-15T12:00:00Z"
  },
  "meta": {
    "request_id": "req_01J9Z8ABCDEF",
    "timestamp": "2026-08-15T12:00:00Z"
  }
}

An unknown id returns 404 Not Found (NOT_FOUND).

Cancelling a scheduled push

DELETE /api/v1/push/scheduled/{id} cancels a push that is still in the scheduled state. Cancel is a guarded status flip, not a hard delete — the row remains queryable with status: "cancelled".

curl -X DELETE https://api.orbit.devotel.io/api/v1/push/scheduled/scheduledPush_01J9ZABCDXYZ \
  -H "X-API-Key: dv_live_sk_your_key_here"

import { Orbit, OrbitApiError } from "@devotel-orbit/node";

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY! });

interface CancelResult {
  id: string;
  status: "cancelled";
}

try {
  const cancelled = await orbit.request<{ data: CancelResult }>(
    "DELETE",
    "/push/scheduled/scheduledPush_01J9ZABCDXYZ",
  );
  console.log(cancelled.data.id, cancelled.data.status);
} catch (err) {
  if (err instanceof OrbitApiError && err.code === "SCHEDULED_PUSH_NOT_CANCELLABLE") {
    // Already dispatched or cancelled — treat as terminal, not a 5xx retry.
    console.warn("Push is no longer cancellable:", err.message);
  } else {
    throw err;
  }
}

A successful cancel returns 200 OK with the new status:

{
  "data": {
    "id": "scheduledPush_01J9ZABCDXYZ",
    "status": "cancelled"
  },
  "meta": {
    "request_id": "req_01J9Z8ABCDEF",
    "timestamp": "2026-08-15T12:00:00Z"
  }
}

Cancellation only succeeds while the push is still pending. If the worker has already dispatched it (sent / failed) or it was cancelled by an earlier request, the endpoint returns 409 Conflict with error code SCHEDULED_PUSH_NOT_CANCELLABLE — the push has already left and can no longer be recalled. Branch on this code rather than treating the cancel as a silent success. An unknown id returns 404 Not Found (NOT_FOUND).

{
  "error": {
    "code": "SCHEDULED_PUSH_NOT_CANCELLABLE",
    "message": "Scheduled push 'scheduledPush_01J9ZABCDXYZ' is already 'sent' and can no longer be cancelled",
    "status": 409
  }
}

VoIP call devices

A separate registry from the device tokens above, used ONLY to deliver inbound-call pushes that wake a backgrounded or terminated mobile app — Apple PushKit (CallKit) on iOS, a high-priority FCM channel on Android. Registration is handled by the mobile app SDK; the list and revoke endpoints let a backend integration or admin tool audit and manage a user’s registered call devices. Register with the raw PushKit token on iOS, or the call-channel FCM token on Android. Re-registering the same token refreshes it and clears any prior revocation.

curl -X POST https://api.orbit.devotel.io/api/v1/push/voip-devices \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "usr_agent42",
    "platform": "ios",
    "voip_token": "9b04ef…pushkit-token",
    "bundle_id": "com.example.agentapp"
  }'

import { Orbit } from "@devotel-orbit/node";

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY! });

interface VoipDevice {
  id: string;
  user_id: string;
  platform: "ios" | "android";
  voip_token: string;
  bundle_id: string | null;
  revoked_at: string | null;
}

const device = await orbit.request<{ data: VoipDevice }>(
  "POST",
  "/push/voip-devices",
  {
    user_id: "usr_agent42",
    platform: "ios",
    voip_token: process.env.PUSHKIT_TOKEN!,
    bundle_id: "com.example.agentapp",
  },
);

console.log("VoIP device id:", device.data.id);

201 Created returns the registered device:

{
  "data": {
    "id": "voipDevice_01J9ZABCDEF9",
    "user_id": "usr_agent42",
    "platform": "ios",
    "voip_token": "9b04ef…pushkit-token",
    "bundle_id": "com.example.agentapp"
  },
  "meta": {
    "request_id": "req_01J9Z8ABCDEF",
    "timestamp": "2026-08-15T12:00:00Z"
  }
}

The list response includes revoked devices (revoked_at set) alongside active ones, so you can see why a device stopped receiving call pushes — a bad token is marked revoked rather than deleted, and re-registering the same token clears the revocation automatically. Results are capped at 200 rows.

curl -X GET https://api.orbit.devotel.io/api/v1/push/voip-devices \
  -H "X-API-Key: dv_live_sk_your_key_here"

import { Orbit } from "@devotel-orbit/node";

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY! });

interface VoipDeviceRow {
  id: string;
  user_id: string;
  platform: string;
  voip_token: string;
  bundle_id: string | null;
  revoked_at: string | null;
  last_seen_at: string | null;
}

const page = await orbit.request<{ data: VoipDeviceRow[] }>(
  "GET",
  "/push/voip-devices",
);

for (const row of page.data) {
  console.log(
    row.id,
    row.platform,
    row.revoked_at ? `revoked at ${row.revoked_at}` : "active",
  );
}

200 OK returns the devices, newest-seen first:

{
  "data": [
    {
      "id": "voipDevice_01J9ZABCDEF9",
      "user_id": "usr_agent42",
      "platform": "ios",
      "voip_token": "9b04ef…pushkit-token",
      "bundle_id": "com.example.agentapp",
      "revoked_at": null,
      "created_at": "2026-08-14T10:00:00Z",
      "last_seen_at": "2026-08-15T11:59:00Z"
    },
    {
      "id": "voipDevice_01J9ZABCDEF7",
      "user_id": "usr_agent42",
      "platform": "android",
      "voip_token": "fcm:7a1d…call-channel-token",
      "bundle_id": null,
      "revoked_at": "2026-08-13T08:31:00Z",
      "created_at": "2026-08-11T15:20:00Z",
      "last_seen_at": "2026-08-13T08:31:00Z"
    }
  ],
  "meta": {
    "request_id": "req_01J9Z8ABCDEF",
    "timestamp": "2026-08-15T12:00:00Z"
  }
}

Unregister with the device’s Orbit id:

curl -X DELETE https://api.orbit.devotel.io/api/v1/push/voip-devices/voipDevice_01J9ZABCDEF9 \
  -H "X-API-Key: dv_live_sk_your_key_here"

import { Orbit } from "@devotel-orbit/node";

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY! });

await orbit.request(undefined, "DELETE", "/push/voip-devices/voipDevice_01J9ZABCDEF9");
// 204 No Content on success; unknown id -> OrbitApiError with status 404.

Success is 204 No Content with an empty body; an unknown id returns 404 Not Found (NOT_FOUND).

API Reference

All Endpoints

Push Notifications API: register FCM and APNs devices

Push Notifications API

The notification object

Using the SDKs

Device tokens

Register a device token

List device tokens

Token lifecycle — register / refresh / deregister

Unregister a device token

Sending

Example — send to a user’s devices

List sent notifications

Scheduled pushes

Cancelling a scheduled push

VoIP call devices

See also

​Push Notifications API

​The notification object

​Using the SDKs

​Device tokens

​Register a device token

​List device tokens

​Token lifecycle — register / refresh / deregister

​Unregister a device token

​Sending

​Example — send to a user’s devices

​List sent notifications

​Scheduled pushes

​Cancelling a scheduled push

​VoIP call devices

​See also

Push Notifications API

The notification object

Using the SDKs

Device tokens

Register a device token

List device tokens

Token lifecycle — register / refresh / deregister

Unregister a device token

Sending

Example — send to a user’s devices

List sent notifications

Scheduled pushes

Cancelling a scheduled push

VoIP call devices

See also