Languages: every operation supports cURL, Node.js (TypeScript), Python, Go, Ruby, and PHP. The first 15 operations on this page show all six languages; the remaining 12 show cURL and TypeScript — the two most-used.

Push API

Mobile push notification delivery and device registration Base path: /api/v1/push Endpoint count: 27

title: “Worked push samples” description: “Worked samples for the push integrator’s chain: register a device token, send to explicit device_token_ids with per-device acceptance, read the delivery receipt from the notifications log, and the registration and send errors to handle.”

Worked push samples

The operation list below documents each endpoint with its parameters, but an integrator runs one chain: register a device token → send a push → read the delivery receipt → retire the token. These samples render that chain as ordered calls with the real response envelopes you branch on. The end-to-end guide is Push integration — client SDK setup is out of scope here; this section adds the per-operation worked bodies the operations list below doesn’t carry. Copy a request as written, substitute your own ids, and compare the response envelope. Every sample shows cURL and TypeScript, matching this page’s language note. Errors follow Devotel Orbit’s { error, meta } envelope.

1. Register the device

A device becomes reachable once it registers a token against an Orbit user. Re-registering the same token upserts (idempotent), and passing app_install_id retires the previous token on a reinstall.

cURL

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": "user_8a1f2c",
    "platform": "ios",
    "token": "9f3a1c5d7b2e0486aab2f8c1d3e5b7a9c2d4e6f8a1b3c5d7e9f1b3d5f7a9c1e3f5",
    "app_install_id": "install_abc123"
  }'

TypeScript

const res = await fetch('https://api.orbit.devotel.io/api/v1/push/device-tokens', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    user_id: 'user_8a1f2c',
    platform: 'ios',
    token: '9f3a1c5d…',
    app_install_id: 'install_abc123',
  }),
})
const { data } = await res.json()
// data.id is the Orbit device-token id.

201

{
  "data": {
    "id": "deviceToken_7e2c1b",
    "user_id": "user_8a1f2c",
    "platform": "ios",
    "token": "9f3a1c5d7b2e0486aab2f8c1d3e5b7a9c2d4e6f8a1b3c5d7e9f1b3d5f7a9c1e3f5",
    "app_id": null,
    "app_install_id": "install_abc123",
    "device_id": null,
    "notification_channel": null
  },
  "meta": {
    "request_id": "req_push_reg",
    "timestamp": "2026-08-30T12:00:00.000Z"
  }
}

Save the returned id — the send below targets devices by it. For platform: "web", supply the subscription envelope (PushSubscription.toJSON()) instead of token. Once your first token lands, fire POST /api/v1/push/test-send to validate the provider credential chain against the calling user’s own devices.

2. Send a push

POST /api/v1/push/send takes one of two targeting shapes: device_token_ids (specific devices, as here) or user_ids (everywhere a user registered; ["*"] broadcasts to every opted-in device, capped at 100,000 deliverable tokens). An immediate send returns 201; read notifications[] per device — a top-level success does not mean every device accepted.

cURL

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_7e2c1b", "deviceToken_8b44aa"],
    "title": "Your order is ready",
    "body": "Pickup is available at counter 4.",
    "data": { "order_id": "ord_91z" },
    "deep_link": "myapp://orders/ord_91z"
  }'

TypeScript

const res = await fetch('https://api.orbit.devotel.io/api/v1/push/send', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    device_token_ids: ['deviceToken_7e2c1b', 'deviceToken_8b44aa'],
    title: 'Your order is ready',
    body: 'Pickup is available at counter 4.',
    data: { order_id: 'ord_91z' },
    deep_link: 'myapp://orders/ord_91z',
  }),
})
const { data } = await res.json()
// data.notifications is the per-device acceptance verdict.

201

{
  "data": {
    "notifications": [
      {
        "id": "pushNotif_2",
        "deviceTokenId": "deviceToken_7e2c1b",
        "transport": "apns",
        "status": "sent"
      },
      {
        "id": "pushNotif_3",
        "deviceTokenId": "deviceToken_8b44aa",
        "transport": "fcm",
        "status": "failed",
        "error": "BadDeviceToken"
      }
    ],
    "total": 2,
    "sent": 1,
    "devices_targeted": 2
  },
  "meta": {
    "request_id": "req_push_send",
    "timestamp": "2026-08-30T12:01:00.000Z"
  }
}

Per-device status is sent (provider accepted), failed (provider rejected — read the error string; permanent failures retire the token), or skipped (frequency cap or suppression gated it). Supply a future send_at (ISO-8601) to hold the send for a later instant; a scheduled send answers 202 instead, and GET /api/v1/push/scheduled/{id} reads the queued row back until DELETE cancels it while still scheduled (409 once it has left).

3. Read send status

GET /api/v1/push/notifications is the delivery log: every per-device row carries its status, the delivered_at / opened_at receipts the client SDK acks, and any provider error. Poll it (or listen for the push.delivered / push.opened webhooks) to reconcile the send above to a delivered / failed / skipped breakdown.

cURL

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

TypeScript

const res = await fetch('https://api.orbit.devotel.io/api/v1/push/notifications', {
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
const { data } = await res.json()
// data[] — one row per device-targeted notification, newest first.

200

{
  "data": [
    {
      "id": "pushNotif_2",
      "device_token_id": "deviceToken_7e2c1b",
      "title": "Your order is ready",
      "body": "Pickup is available at counter 4.",
      "status": "delivered",
      "sent_at": "2026-08-30T12:01:00.000Z",
      "delivered_at": "2026-08-30T12:01:02.000Z",
      "opened_at": null,
      "error": null,
      "platform": "ios",
      "user_id": "user_8a1f2c"
    },
    {
      "id": "pushNotif_3",
      "device_token_id": "deviceToken_8b44aa",
      "title": "Your order is ready",
      "body": "Pickup is available at counter 4.",
      "status": "failed",
      "sent_at": "2026-08-30T12:01:00.000Z",
      "delivered_at": null,
      "opened_at": null,
      "error": "BadDeviceToken",
      "platform": "android",
      "user_id": "user_8a1f2c"
    }
  ],
  "meta": {
    "request_id": "req_push_list",
    "timestamp": "2026-08-30T12:03:00.000Z"
  }
}

Page the log with ?cursor=<last-row-created_at>&limit=<page-size> when it grows past one screen. A skipped row never leaves the send-time status — no receipt arrives for a gated device.

4. Errors

Two error classes show up on every integration — read the issues list on 422s and map 404s on ids your tenant has never seen. 422 — malformed registration. A device registers with an unknown platform (must be ios, android, huawei, or web), or with no token / subscription for the platform it claims:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid enum value. Expected 'ios' | 'android' | 'huawei' | 'web', received 'macos'",
    "status": 422,
    "details": {
      "issues": [
        {
          "field": "platform",
          "message": "Invalid enum value. Expected 'ios' | 'android' | 'huawei' | 'web', received 'macos'"
        }
      ]
    }
  },
  "meta": {
    "request_id": "req_push_reg_err",
    "timestamp": "2026-08-30T12:04:00.000Z"
  }
}

The same 422 shape answers a send with neither device_token_ids nor user_ids supplied. A send that resolves to zero deliverable tokens answers NO_DEVICE_TOKENS (422), and user_ids: ["*"] over the recipient cap answers BROADCAST_TOO_LARGE (422). 404 — unknown device id. A token id not known to this tenant — a deleted record, a typo, or another tenant’s id:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Device token 'deviceToken_000000' not found",
    "status": 404
  },
  "meta": {
    "request_id": "req_push_404",
    "timestamp": "2026-08-30T12:05:00.000Z"
  }
}

The identification token an OS hands you on reinstall is new every time — re-register rather than updating a stale id, and DELETE /api/v1/push/device-tokens/{id} on logout retires the current one.

List push notification categories

GET /api/v1/push/categories

List the APNs / FCM categories defined for this tenant, newest first, returning at most 200 entries with their identifiers, sounds and action buttons. Use it to see which interactive categories are configured before naming an identifier on a push send.

string (enum: true|false)

Sandbox opt-in for Clerk-session-authenticated requests. Set to true to route the call through the test-mode pipeline: no real provider delivery, no credits deducted, response meta.test_mode: true. Ignored for live API keys (dv_live_sk_*) — server-to-server clients must use a test-prefixed key (dv_test_sk_*) to exercise sandbox. Test-prefixed keys unconditionally enable sandbox regardless of this header.

cURL

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

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/push/categories', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/push/categories", headers=headers)
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/push/categories", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/push/categories')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']


res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/push/categories');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),

]);

echo curl_exec($ch);

{
  "data": [
    {}
  ],
  "meta": {}
}

Get push notification category by ID

GET /api/v1/push/categories/{id}

Fetch one push notification category by its generated id, including its wire-bound identifier, optional sound and action buttons. Use it to confirm the exact record a category id resolves to before deleting or before wiring it into a push send.

string

required

—

string (enum: true|false)

cURL

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

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/push/categories/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/push/categories/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3", headers=headers)
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/push/categories/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/push/categories/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']


res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/push/categories/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),

]);

echo curl_exec($ch);

{
  "data": [
    {
      "id": "pushNotif_2",
      "device_token_id": "deviceToken_7e2c1b",
      "title": "Your order is ready",
      "body": "Pickup is available at counter 4.",
      "status": "delivered",
      "sent_at": "2026-08-30T12:01:00.000Z",
      "delivered_at": "2026-08-30T12:01:02.000Z",
      "opened_at": null,
      "error": null,
      "platform": "ios",
      "user_id": "user_8a1f2c"
    },
    {
      "id": "pushNotif_3",
      "device_token_id": "deviceToken_8b44aa",
      "title": "Your order is ready",
      "body": "Pickup is available at counter 4.",
      "status": "failed",
      "sent_at": "2026-08-30T12:01:00.000Z",
      "delivered_at": null,
      "opened_at": null,
      "error": "BadDeviceToken",
      "platform": "android",
      "user_id": "user_8a1f2c"
    }
  ],
  "meta": {
    "request_id": "req_push_list",
    "timestamp": "2026-08-30T12:03:00.000Z"
  }
}

Get web push configuration

GET /api/v1/push/config

Return the public Web Push configuration a browser needs to subscribe: the VAPID public key and whether web push is enabled for this deployment. The VAPID private key is never returned. Call it before requesting a browser PushSubscription, or to re-subscribe after a VAPID key rotation.

string (enum: true|false)

cURL

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

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/push/config', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/push/config", headers=headers)
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/push/config", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/push/config')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']


res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/push/config');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),

]);

echo curl_exec($ch);

{
  "data": [
    {
      "id": "pushNotif_2",
      "device_token_id": "deviceToken_7e2c1b",
      "title": "Your order is ready",
      "body": "Pickup is available at counter 4.",
      "status": "delivered",
      "sent_at": "2026-08-30T12:01:00.000Z",
      "delivered_at": "2026-08-30T12:01:02.000Z",
      "opened_at": null,
      "error": null,
      "platform": "ios",
      "user_id": "user_8a1f2c"
    },
    {
      "id": "pushNotif_3",
      "device_token_id": "deviceToken_8b44aa",
      "title": "Your order is ready",
      "body": "Pickup is available at counter 4.",
      "status": "failed",
      "sent_at": "2026-08-30T12:01:00.000Z",
      "delivered_at": null,
      "opened_at": null,
      "error": "BadDeviceToken",
      "platform": "android",
      "user_id": "user_8a1f2c"
    }
  ],
  "meta": {
    "request_id": "req_push_list",
    "timestamp": "2026-08-30T12:03:00.000Z"
  }
}

List registered device tokens

GET /api/v1/push/device-tokens

List the push device tokens registered for this tenant, newest first, optionally filtered to a single user with the user_id query parameter. Each row carries the platform, canonical token, install identifiers and whether delivery is currently enabled. Use it to render a user’s registered devices or to audit which installs will receive a push. Capped at 200 rows.

string (enum: true|false)

cURL

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

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/push/device-tokens', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/push/device-tokens", headers=headers)
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/push/device-tokens", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/push/device-tokens')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']


res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/push/device-tokens');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),

]);

echo curl_exec($ch);

{
  "data": [
    {
      "id": "pushNotif_2",
      "device_token_id": "deviceToken_7e2c1b",
      "title": "Your order is ready",
      "body": "Pickup is available at counter 4.",
      "status": "delivered",
      "sent_at": "2026-08-30T12:01:00.000Z",
      "delivered_at": "2026-08-30T12:01:02.000Z",
      "opened_at": null,
      "error": null,
      "platform": "ios",
      "user_id": "user_8a1f2c"
    },
    {
      "id": "pushNotif_3",
      "device_token_id": "deviceToken_8b44aa",
      "title": "Your order is ready",
      "body": "Pickup is available at counter 4.",
      "status": "failed",
      "sent_at": "2026-08-30T12:01:00.000Z",
      "delivered_at": null,
      "opened_at": null,
      "error": "BadDeviceToken",
      "platform": "android",
      "user_id": "user_8a1f2c"
    }
  ],
  "meta": {
    "request_id": "req_push_list",
    "timestamp": "2026-08-30T12:03:00.000Z"
  }
}

List Live Activities

GET /api/v1/push/live-activities

List the iOS ActivityKit Live Activities tracked for this tenant, newest first. Each row carries the activity token, type, current content state, status and lifecycle timestamps (started, updated, ended). Use it to see which live, lock-screen experiences are active so they can be updated or ended. Capped at 200 rows.

string (enum: true|false)

cURL

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

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/push/live-activities', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/push/live-activities", headers=headers)
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/push/live-activities", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/push/live-activities')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']


res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/push/live-activities');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),

]);

echo curl_exec($ch);

{
  "data": [
    {
      "id": "pushNotif_2",
      "device_token_id": "deviceToken_7e2c1b",
      "title": "Your order is ready",
      "body": "Pickup is available at counter 4.",
      "status": "delivered",
      "sent_at": "2026-08-30T12:01:00.000Z",
      "delivered_at": "2026-08-30T12:01:02.000Z",
      "opened_at": null,
      "error": null,
      "platform": "ios",
      "user_id": "user_8a1f2c"
    },
    {
      "id": "pushNotif_3",
      "device_token_id": "deviceToken_8b44aa",
      "title": "Your order is ready",
      "body": "Pickup is available at counter 4.",
      "status": "failed",
      "sent_at": "2026-08-30T12:01:00.000Z",
      "delivered_at": null,
      "opened_at": null,
      "error": "BadDeviceToken",
      "platform": "android",
      "user_id": "user_8a1f2c"
    }
  ],
  "meta": {
    "request_id": "req_push_list",
    "timestamp": "2026-08-30T12:03:00.000Z"
  }
}

List sent push notifications

GET /api/v1/push/notifications

List push notifications sent for this tenant, newest first, with their delivery status, per-notification transport and the delivered / opened timestamps and any error. Page through the log with the optional cursor (the created_at of the last row you already hold) and limit query parameters. Use it to render the notifications log or to reconcile delivery outcomes.

string (enum: true|false)

cURL

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

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/push/notifications', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/push/notifications", headers=headers)
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/push/notifications", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/push/notifications')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']


res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/push/notifications');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),

]);

echo curl_exec($ch);

{
  "data": [
    {
      "id": "pushNotif_2",
      "device_token_id": "deviceToken_7e2c1b",
      "title": "Your order is ready",
      "body": "Pickup is available at counter 4.",
      "status": "delivered",
      "sent_at": "2026-08-30T12:01:00.000Z",
      "delivered_at": "2026-08-30T12:01:02.000Z",
      "opened_at": null,
      "error": null,
      "platform": "ios",
      "user_id": "user_8a1f2c"
    },
    {
      "id": "pushNotif_3",
      "device_token_id": "deviceToken_8b44aa",
      "title": "Your order is ready",
      "body": "Pickup is available at counter 4.",
      "status": "failed",
      "sent_at": "2026-08-30T12:01:00.000Z",
      "delivered_at": null,
      "opened_at": null,
      "error": "BadDeviceToken",
      "platform": "android",
      "user_id": "user_8a1f2c"
    }
  ],
  "meta": {
    "request_id": "req_push_list",
    "timestamp": "2026-08-30T12:03:00.000Z"
  }
}

List scheduled push notifications

GET /api/v1/push/scheduled

List this tenant’s push notifications queued for a future send, soonest send_at first, optionally filtered by status (scheduled, sent, cancelled, failed). Use it to review or manage pushes waiting for the scheduler to dispatch them. Capped at 200 rows.

string (enum: true|false)

cURL

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

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/push/scheduled', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/push/scheduled", headers=headers)
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/push/scheduled", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/push/scheduled')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']


res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/push/scheduled');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),

]);

echo curl_exec($ch);

{
  "data": [
    {}
  ],
  "meta": {}
}

Get a scheduled push notification

GET /api/v1/push/scheduled/{id}

Retrieve a single scheduled push by id, including its full platform-agnostic payload, target send_at, current status, attempt count and last error. Use it to inspect a queued push before it is dispatched, or to check why a scheduled send failed. Returns 404 when no such scheduled push exists for this tenant.

string

required

Scheduled push id.

string (enum: true|false)

cURL

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

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/push/scheduled/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/push/scheduled/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3", headers=headers)
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/push/scheduled/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/push/scheduled/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']


res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/push/scheduled/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),

]);

echo curl_exec($ch);

{
  "data": [
    {
      "id": "pushNotif_2",
      "device_token_id": "deviceToken_7e2c1b",
      "title": "Your order is ready",
      "body": "Pickup is available at counter 4.",
      "status": "delivered",
      "sent_at": "2026-08-30T12:01:00.000Z",
      "delivered_at": "2026-08-30T12:01:02.000Z",
      "opened_at": null,
      "error": null,
      "platform": "ios",
      "user_id": "user_8a1f2c"
    },
    {
      "id": "pushNotif_3",
      "device_token_id": "deviceToken_8b44aa",
      "title": "Your order is ready",
      "body": "Pickup is available at counter 4.",
      "status": "failed",
      "sent_at": "2026-08-30T12:01:00.000Z",
      "delivered_at": null,
      "opened_at": null,
      "error": "BadDeviceToken",
      "platform": "android",
      "user_id": "user_8a1f2c"
    }
  ],
  "meta": {
    "request_id": "req_push_list",
    "timestamp": "2026-08-30T12:03:00.000Z"
  }
}

Summarize device push telemetry

GET /api/v1/push/telemetry/summary

Return aggregated device push-wake telemetry grouped by user and platform: sample count, median/min/max battery level at last push, average wake count and median delivery latency. Use it to power the dashboard’s battery-impact view and confirm background push delivery is not draining devices. Non-admin callers see only their own telemetry; admins and owners may pass an explicit user_id.

string (enum: true|false)

cURL

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

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/push/telemetry/summary', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/push/telemetry/summary", headers=headers)
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/push/telemetry/summary", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/push/telemetry/summary')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']


res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/push/telemetry/summary');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),

]);

echo curl_exec($ch);

{
  "data": [
    {}
  ],
  "meta": {}
}

List registered VoIP call-push devices

GET /api/v1/push/voip-devices

Lists VoIP/CallKit device tokens registered for this tenant, newest-seen first, optionally filtered to a single user. Includes revoked devices (revoked_at set) so an operator can see why a device stopped ringing. Capped at 200 rows.

string

Filter the list to a single user’s devices.

string (enum: true|false)

cURL

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

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/push/voip-devices', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/push/voip-devices", headers=headers)
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/push/voip-devices", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/push/voip-devices')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']


res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/push/voip-devices');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),

]);

echo curl_exec($ch);

{
  "data": [
    {
      "id": "pushNotif_2",
      "device_token_id": "deviceToken_7e2c1b",
      "title": "Your order is ready",
      "body": "Pickup is available at counter 4.",
      "status": "delivered",
      "sent_at": "2026-08-30T12:01:00.000Z",
      "delivered_at": "2026-08-30T12:01:02.000Z",
      "opened_at": null,
      "error": null,
      "platform": "ios",
      "user_id": "user_8a1f2c"
    },
    {
      "id": "pushNotif_3",
      "device_token_id": "deviceToken_8b44aa",
      "title": "Your order is ready",
      "body": "Pickup is available at counter 4.",
      "status": "failed",
      "sent_at": "2026-08-30T12:01:00.000Z",
      "delivered_at": null,
      "opened_at": null,
      "error": "BadDeviceToken",
      "platform": "android",
      "user_id": "user_8a1f2c"
    }
  ],
  "meta": {
    "request_id": "req_push_list",
    "timestamp": "2026-08-30T12:03:00.000Z"
  }
}

Clear a user’s push badge count

POST /api/v1/push/badge/clear

Reset the unread app-icon badge for one user to zero across their registered iOS devices. By default it also fires a silent background push (badge: 0) so the springboard badge updates without showing an alert; send silent_push: false to only record the reset. Call it after the user has read their notifications — for example when they open the Inbox. When user_id is omitted it clears for the authenticated caller.

string

Stripe-style idempotency token. Pass a stable, client-generated value (1-255 chars) to dedupe retries on transient timeouts. The same key+credential+path replays the original response for 24h on 2xx (5min on 4xx, 30s on 5xx). Returns 409 if a concurrent request with the same key is already in flight; replayed responses include the Idempotency-Replay: true response header.

string (enum: true|false)

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/push/badge/clear" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/push/badge/clear', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/push/badge/clear", headers=headers, json={})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/push/badge/clear", bytes.NewBuffer([]byte(`{}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/push/badge/clear')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/push/badge/clear');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{}
JSON);
echo curl_exec($ch);

{
  "data": [
    {
      "id": "pushNotif_2",
      "device_token_id": "deviceToken_7e2c1b",
      "title": "Your order is ready",
      "body": "Pickup is available at counter 4.",
      "status": "delivered",
      "sent_at": "2026-08-30T12:01:00.000Z",
      "delivered_at": "2026-08-30T12:01:02.000Z",
      "opened_at": null,
      "error": null,
      "platform": "ios",
      "user_id": "user_8a1f2c"
    },
    {
      "id": "pushNotif_3",
      "device_token_id": "deviceToken_8b44aa",
      "title": "Your order is ready",
      "body": "Pickup is available at counter 4.",
      "status": "failed",
      "sent_at": "2026-08-30T12:01:00.000Z",
      "delivered_at": null,
      "opened_at": null,
      "error": "BadDeviceToken",
      "platform": "android",
      "user_id": "user_8a1f2c"
    }
  ],
  "meta": {
    "request_id": "req_push_list",
    "timestamp": "2026-08-30T12:03:00.000Z"
  }
}

Create a push notification category

POST /api/v1/push/categories

Per-tenant APNs / FCM notification category. The identifier is wire-bound — the iOS / Android client matches on it — so it cannot be modified after create.

string

string (enum: true|false)

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/push/categories" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/push/categories', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/push/categories", headers=headers, json={})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/push/categories", bytes.NewBuffer([]byte(`{}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/push/categories')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/push/categories');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{}
JSON);
echo curl_exec($ch);

{
  "data": {
    "id": "deviceToken_7e2c1b",
    "user_id": "user_8a1f2c",
    "platform": "ios",
    "token": "9f3a1c5d7b2e0486aab2f8c1d3e5b7a9c2d4e6f8a1b3c5d7e9f1b3d5f7a9c1e3f5",
    "app_id": null,
    "app_install_id": "install_abc123",
    "device_id": null,
    "notification_channel": null
  },
  "meta": {
    "request_id": "req_push_reg",
    "timestamp": "2026-08-30T12:00:00.000Z"
  }
}

Register a device token

POST /api/v1/push/device-tokens

Register (or refresh) a device so it can receive push notifications. Supply the native APNs / FCM token for ios / android / huawei, or a Web Push subscription envelope for platform: web. Re-registering the same token updates its last-seen time and owner instead of creating a duplicate, and passing an app_install_id retires the install’s previous token on reinstall. Call it once the client obtains a push token from the OS.

string

string (enum: true|false)

cURL

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 '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/push/device-tokens', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/push/device-tokens", headers=headers, json={})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/push/device-tokens", bytes.NewBuffer([]byte(`{}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/push/device-tokens')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/push/device-tokens');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{}
JSON);
echo curl_exec($ch);

{
  "data": {
    "id": "deviceToken_7e2c1b",
    "user_id": "user_8a1f2c",
    "platform": "ios",
    "token": "9f3a1c5d7b2e0486aab2f8c1d3e5b7a9c2d4e6f8a1b3c5d7e9f1b3d5f7a9c1e3f5",
    "app_id": null,
    "app_install_id": "install_abc123",
    "device_id": null,
    "notification_channel": null
  },
  "meta": {
    "request_id": "req_push_reg",
    "timestamp": "2026-08-30T12:00:00.000Z"
  }
}

Start a Live Activity

POST /api/v1/push/live-activities

Start an iOS ActivityKit Live Activity and send its initial push through APNs. Provide the activity_token vended by Activity.pushToken, an activity_type and the initial content_state; Orbit tracks the activity so it can be updated and ended later. Use it to begin a live, lock-screen experience such as order tracking or a live score.

string

string (enum: true|false)

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/push/live-activities" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/push/live-activities', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/push/live-activities", headers=headers, json={})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/push/live-activities", bytes.NewBuffer([]byte(`{}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/push/live-activities')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/push/live-activities');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{}
JSON);
echo curl_exec($ch);

{
  "data": {
    "id": "deviceToken_7e2c1b",
    "user_id": "user_8a1f2c",
    "platform": "ios",
    "token": "9f3a1c5d7b2e0486aab2f8c1d3e5b7a9c2d4e6f8a1b3c5d7e9f1b3d5f7a9c1e3f5",
    "app_id": null,
    "app_install_id": "install_abc123",
    "device_id": null,
    "notification_channel": null
  },
  "meta": {
    "request_id": "req_push_reg",
    "timestamp": "2026-08-30T12:00:00.000Z"
  }
}

Acknowledge a push notification

POST /api/v1/push/notifications/{id}/ack

Record a delivery or open acknowledgement from a client SDK for one push notification, setting its delivered_at or opened_at timestamp. The update is idempotent, so repeated acks are safe and the matching push.delivered / push.opened webhook fires only on the first genuine transition. Send event: delivered when the device receives the push and event: opened when the user taps it; returns 404 when the notification id is unknown.

string

required

—

string

string (enum: true|false)

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/push/notifications/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/ack" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/push/notifications/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/ack', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/push/notifications/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/ack", headers=headers, json={})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/push/notifications/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/ack", bytes.NewBuffer([]byte(`{}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/push/notifications/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/ack')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/push/notifications/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3/ack');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{}
JSON);
echo curl_exec($ch);

{
  "data": [
    {
      "id": "pushNotif_2",
      "device_token_id": "deviceToken_7e2c1b",
      "title": "Your order is ready",
      "body": "Pickup is available at counter 4.",
      "status": "delivered",
      "sent_at": "2026-08-30T12:01:00.000Z",
      "delivered_at": "2026-08-30T12:01:02.000Z",
      "opened_at": null,
      "error": null,
      "platform": "ios",
      "user_id": "user_8a1f2c"
    },
    {
      "id": "pushNotif_3",
      "device_token_id": "deviceToken_8b44aa",
      "title": "Your order is ready",
      "body": "Pickup is available at counter 4.",
      "status": "failed",
      "sent_at": "2026-08-30T12:01:00.000Z",
      "delivered_at": null,
      "opened_at": null,
      "error": "BadDeviceToken",
      "platform": "android",
      "user_id": "user_8a1f2c"
    }
  ],
  "meta": {
    "request_id": "req_push_list",
    "timestamp": "2026-08-30T12:03:00.000Z"
  }
}

Register a device token (alias)

POST /api/v1/push/register

Backwards-compatible alias for POST /api/v1/push/device-tokens that registers or refreshes a device for push delivery with the identical request and response. Prefer POST /push/device-tokens in new integrations; this path exists for older SDK clients that still call /push/register.

string

string (enum: true|false)

cURL

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 '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/push/register', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "id": "deviceToken_7e2c1b",
    "user_id": "user_8a1f2c",
    "platform": "ios",
    "token": "9f3a1c5d7b2e0486aab2f8c1d3e5b7a9c2d4e6f8a1b3c5d7e9f1b3d5f7a9c1e3f5",
    "app_id": null,
    "app_install_id": "install_abc123",
    "device_id": null,
    "notification_channel": null
  },
  "meta": {
    "request_id": "req_push_reg",
    "timestamp": "2026-08-30T12:00:00.000Z"
  }
}

Send a push notification

POST /api/v1/push/send

Send a push notification to one or more targeted devices, fanning out across iOS (APNs), Android (FCM) and Web Push in a single call. Target by explicit user_ids, device tokens or a broadcast, and Orbit applies per-user frequency caps and suppression before delivery. Provide a future send_at to schedule the notification instead of sending immediately — it is persisted and dispatched by the scheduler at that time. Returns 201 with the per-device delivery results for an immediate send, or 202 with the scheduled push id when send_at is in the future.

string

string (enum: true|false)

cURL

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 '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/push/send', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "id": "deviceToken_7e2c1b",
    "user_id": "user_8a1f2c",
    "platform": "ios",
    "token": "9f3a1c5d7b2e0486aab2f8c1d3e5b7a9c2d4e6f8a1b3c5d7e9f1b3d5f7a9c1e3f5",
    "app_id": null,
    "app_install_id": "install_abc123",
    "device_id": null,
    "notification_channel": null
  },
  "meta": {
    "request_id": "req_push_reg",
    "timestamp": "2026-08-30T12:00:00.000Z"
  }
}

Report device-side push wake telemetry

POST /api/v1/push/telemetry

Mobile / web clients call this every ~15min after a push wake to report battery_pct + wake_count + delivery_latency_ms. The dashboard surfaces the aggregate so operators see we don’t drain (UCAAS-GAP-01).

string

string (enum: true|false)

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/push/telemetry" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/push/telemetry', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": {
    "id": "deviceToken_7e2c1b",
    "user_id": "user_8a1f2c",
    "platform": "ios",
    "token": "9f3a1c5d7b2e0486aab2f8c1d3e5b7a9c2d4e6f8a1b3c5d7e9f1b3d5f7a9c1e3f5",
    "app_id": null,
    "app_install_id": "install_abc123",
    "device_id": null,
    "notification_channel": null
  },
  "meta": {
    "request_id": "req_push_reg",
    "timestamp": "2026-08-30T12:00:00.000Z"
  }
}

Send a push configuration test

POST /api/v1/push/test-send

Fire a single fixed-shape test notification to every enabled device token owned by the authenticated operator to validate FCM / APNs / VAPID credentials end-to-end. It never targets a peer and never broadcasts, and it is not recorded as a tracked send so it does not pollute campaign stats. Always returns 200 with a per-token verdict (including the provider that was exercised) so a single failing device does not mask the others.

string

string (enum: true|false)

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/push/test-send" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/push/test-send', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": [
    {
      "id": "pushNotif_2",
      "device_token_id": "deviceToken_7e2c1b",
      "title": "Your order is ready",
      "body": "Pickup is available at counter 4.",
      "status": "delivered",
      "sent_at": "2026-08-30T12:01:00.000Z",
      "delivered_at": "2026-08-30T12:01:02.000Z",
      "opened_at": null,
      "error": null,
      "platform": "ios",
      "user_id": "user_8a1f2c"
    },
    {
      "id": "pushNotif_3",
      "device_token_id": "deviceToken_8b44aa",
      "title": "Your order is ready",
      "body": "Pickup is available at counter 4.",
      "status": "failed",
      "sent_at": "2026-08-30T12:01:00.000Z",
      "delivered_at": null,
      "opened_at": null,
      "error": "BadDeviceToken",
      "platform": "android",
      "user_id": "user_8a1f2c"
    }
  ],
  "meta": {
    "request_id": "req_push_list",
    "timestamp": "2026-08-30T12:03:00.000Z"
  }
}

Register a VoIP (PushKit) / high-priority FCM call token

POST /api/v1/push/voip-devices

Register (or refresh) the device token used ONLY for inbound-call CallKit/ConnectionService pushes — separate from the general marketing/notification device tokens registered at POST /push/device-tokens. Re-registering the same token un-revokes it and updates last-seen. Call it once the client obtains a PushKit VoIP token (iOS) or the call-channel FCM token (Android).

string

string (enum: true|false)

string

Agent/user id this device belongs to; defaults to the authenticated user when omitted.

string (enum: ios|android)

required

—

string

required

iOS: the raw PushKit (PKPushRegistry) token. Android: the FCM registration token used for the high-priority call channel.

string

iOS app bundle id — the APNs apns-topic for a VoIP push is <bundle_id>.voip. Falls back to the server-configured bundle id when omitted.

cURL

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 '{
  "platform": "ios",
  "voip_token": "string"
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/push/voip-devices', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "platform": "ios",
  "voip_token": "string"
}),
})
console.log(await res.json())

{
  "data": {
    "id": "deviceToken_7e2c1b",
    "user_id": "user_8a1f2c",
    "platform": "ios",
    "token": "9f3a1c5d7b2e0486aab2f8c1d3e5b7a9c2d4e6f8a1b3c5d7e9f1b3d5f7a9c1e3f5",
    "app_id": null,
    "app_install_id": "install_abc123",
    "device_id": null,
    "notification_channel": null
  },
  "meta": {
    "request_id": "req_push_reg",
    "timestamp": "2026-08-30T12:00:00.000Z"
  }
}

Update a Live Activity

PUT /api/v1/push/live-activities/{id}

Push a new content_state to a running Live Activity so its lock-screen and Dynamic Island presentation updates in place, identified by the activity’s Orbit id. Use it to advance a tracked activity — for example moving an order from Preparing to Out for delivery. Returns 404 when the activity is unknown or has already ended.

string

required

—

string

string (enum: true|false)

cURL

curl -X PUT "https://api.orbit.devotel.io/api/v1/push/live-activities/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/push/live-activities/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": [
    {
      "id": "pushNotif_2",
      "device_token_id": "deviceToken_7e2c1b",
      "title": "Your order is ready",
      "body": "Pickup is available at counter 4.",
      "status": "delivered",
      "sent_at": "2026-08-30T12:01:00.000Z",
      "delivered_at": "2026-08-30T12:01:02.000Z",
      "opened_at": null,
      "error": null,
      "platform": "ios",
      "user_id": "user_8a1f2c"
    },
    {
      "id": "pushNotif_3",
      "device_token_id": "deviceToken_8b44aa",
      "title": "Your order is ready",
      "body": "Pickup is available at counter 4.",
      "status": "failed",
      "sent_at": "2026-08-30T12:01:00.000Z",
      "delivered_at": null,
      "opened_at": null,
      "error": "BadDeviceToken",
      "platform": "android",
      "user_id": "user_8a1f2c"
    }
  ],
  "meta": {
    "request_id": "req_push_list",
    "timestamp": "2026-08-30T12:03:00.000Z"
  }
}

Enable or disable a device token

PATCH /api/v1/push/device-tokens/{id}

Toggle push delivery for a single device without permanently deleting its token by sending enabled: true or enabled: false. A disabled token is skipped by the send path but kept on file, so you can pause a noisy device and re-enable it later. Returns the updated token row, or 404 when the id is unknown in this tenant.

string

required

—

string (enum: true|false)

cURL

curl -X PATCH "https://api.orbit.devotel.io/api/v1/push/device-tokens/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/push/device-tokens/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3', {
  method: 'PATCH',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": [
    {
      "id": "pushNotif_2",
      "device_token_id": "deviceToken_7e2c1b",
      "title": "Your order is ready",
      "body": "Pickup is available at counter 4.",
      "status": "delivered",
      "sent_at": "2026-08-30T12:01:00.000Z",
      "delivered_at": "2026-08-30T12:01:02.000Z",
      "opened_at": null,
      "error": null,
      "platform": "ios",
      "user_id": "user_8a1f2c"
    },
    {
      "id": "pushNotif_3",
      "device_token_id": "deviceToken_8b44aa",
      "title": "Your order is ready",
      "body": "Pickup is available at counter 4.",
      "status": "failed",
      "sent_at": "2026-08-30T12:01:00.000Z",
      "delivered_at": null,
      "opened_at": null,
      "error": "BadDeviceToken",
      "platform": "android",
      "user_id": "user_8a1f2c"
    }
  ],
  "meta": {
    "request_id": "req_push_list",
    "timestamp": "2026-08-30T12:03:00.000Z"
  }
}

Delete push notification category

DELETE /api/v1/push/categories/{id}

Delete one push notification category by its generated id. Identifier reuse is the supported update pattern — delete, then recreate — because the identifier is wire-bound on the iOS / Android client. Returns an empty 204; an unknown id yields a 404.

string

required

—

string (enum: true|false)

cURL

curl -X DELETE "https://api.orbit.devotel.io/api/v1/push/categories/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/push/categories/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3', {
  method: 'DELETE',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

Response: 204 No Content

Delete a device token

DELETE /api/v1/push/device-tokens/{id}

Unregister a device token so it no longer receives pushes — for example when a user signs out or removes a device. Identified by the token’s Orbit id. Returns 204 No Content on success and 404 when the token does not exist in this tenant.

string

required

—

string (enum: true|false)

cURL

curl -X DELETE "https://api.orbit.devotel.io/api/v1/push/device-tokens/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/push/device-tokens/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3', {
  method: 'DELETE',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

Response: 204 No Content

End a Live Activity

DELETE /api/v1/push/live-activities/{id}

End a running Live Activity and send the final ActivityKit end push, optionally with a closing content_state and a dismissal_date telling iOS when to remove it from the lock screen. Identified by the activity’s Orbit id. Call it when the tracked task completes; returns 404 when the activity is unknown.

string

required

—

string (enum: true|false)

cURL

curl -X DELETE "https://api.orbit.devotel.io/api/v1/push/live-activities/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/push/live-activities/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3', {
  method: 'DELETE',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": [
    {
      "id": "pushNotif_2",
      "device_token_id": "deviceToken_7e2c1b",
      "title": "Your order is ready",
      "body": "Pickup is available at counter 4.",
      "status": "delivered",
      "sent_at": "2026-08-30T12:01:00.000Z",
      "delivered_at": "2026-08-30T12:01:02.000Z",
      "opened_at": null,
      "error": null,
      "platform": "ios",
      "user_id": "user_8a1f2c"
    },
    {
      "id": "pushNotif_3",
      "device_token_id": "deviceToken_8b44aa",
      "title": "Your order is ready",
      "body": "Pickup is available at counter 4.",
      "status": "failed",
      "sent_at": "2026-08-30T12:01:00.000Z",
      "delivered_at": null,
      "opened_at": null,
      "error": "BadDeviceToken",
      "platform": "android",
      "user_id": "user_8a1f2c"
    }
  ],
  "meta": {
    "request_id": "req_push_list",
    "timestamp": "2026-08-30T12:03:00.000Z"
  }
}

Cancel a scheduled push notification

DELETE /api/v1/push/scheduled/{id}

Cancel a push notification still queued for a future send, before the scheduler dispatches it. This is a guarded status change, not a hard delete: only a push still in scheduled status is cancelled. Returns 404 when the id is unknown, and 409 when the push has already been sent or failed and can no longer be cancelled.

string

required

Scheduled push id.

string (enum: true|false)

cURL

curl -X DELETE "https://api.orbit.devotel.io/api/v1/push/scheduled/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/push/scheduled/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3', {
  method: 'DELETE',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

{
  "data": [
    {
      "id": "pushNotif_2",
      "device_token_id": "deviceToken_7e2c1b",
      "title": "Your order is ready",
      "body": "Pickup is available at counter 4.",
      "status": "delivered",
      "sent_at": "2026-08-30T12:01:00.000Z",
      "delivered_at": "2026-08-30T12:01:02.000Z",
      "opened_at": null,
      "error": null,
      "platform": "ios",
      "user_id": "user_8a1f2c"
    },
    {
      "id": "pushNotif_3",
      "device_token_id": "deviceToken_8b44aa",
      "title": "Your order is ready",
      "body": "Pickup is available at counter 4.",
      "status": "failed",
      "sent_at": "2026-08-30T12:01:00.000Z",
      "delivered_at": null,
      "opened_at": null,
      "error": "BadDeviceToken",
      "platform": "android",
      "user_id": "user_8a1f2c"
    }
  ],
  "meta": {
    "request_id": "req_push_list",
    "timestamp": "2026-08-30T12:03:00.000Z"
  }
}

Unregister a VoIP call-push device

DELETE /api/v1/push/voip-devices/{id}

Removes a VoIP/CallKit device token so it no longer receives inbound-call pushes — for example on sign-out. Returns 204 on success, 404 when the id is unknown in this tenant.

string

required

—

string (enum: true|false)

cURL

curl -X DELETE "https://api.orbit.devotel.io/api/v1/push/voip-devices/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel-orbit/node'

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/push/voip-devices/num_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3', {
  method: 'DELETE',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

Response: 204 No Content

API Reference

All Endpoints

Push API

Push API

title: “Worked push samples” description: “Worked samples for the push integrator’s chain: register a device token, send to explicit device_token_ids with per-device acceptance, read the delivery receipt from the notifications log, and the registration and send errors to handle.”

Worked push samples

1. Register the device

2. Send a push

3. Read send status

4. Errors

See also

List push notification categories

Get push notification category by ID

Get web push configuration

List registered device tokens

List Live Activities

List sent push notifications

List scheduled push notifications

Get a scheduled push notification

Summarize device push telemetry

List registered VoIP call-push devices

Clear a user’s push badge count

Create a push notification category

Register a device token

Start a Live Activity

Acknowledge a push notification

Register a device token (alias)

Send a push notification

Report device-side push wake telemetry

Send a push configuration test

Register a VoIP (PushKit) / high-priority FCM call token

Update a Live Activity

Enable or disable a device token

Delete push notification category

Delete a device token

End a Live Activity

Cancel a scheduled push notification

Unregister a VoIP call-push device

​Push API

​title: “Worked push samples” description: “Worked samples for the push integrator’s chain: register a device token, send to explicit device_token_ids with per-device acceptance, read the delivery receipt from the notifications log, and the registration and send errors to handle.”

​Worked push samples

​1. Register the device

​2. Send a push

​3. Read send status

​4. Errors

​See also

​List push notification categories

​Get push notification category by ID

​Get web push configuration

​List registered device tokens

​List Live Activities

​List sent push notifications

​List scheduled push notifications

​Get a scheduled push notification

​Summarize device push telemetry

​List registered VoIP call-push devices

​Clear a user’s push badge count

​Create a push notification category

​Register a device token

​Start a Live Activity

​Acknowledge a push notification

​Register a device token (alias)

​Send a push notification

​Report device-side push wake telemetry

​Send a push configuration test

​Register a VoIP (PushKit) / high-priority FCM call token

​Update a Live Activity

​Enable or disable a device token

​Delete push notification category

​Delete a device token

​End a Live Activity

​Cancel a scheduled push notification

​Unregister a VoIP call-push device

Push API

title: “Worked push samples” description: “Worked samples for the push integrator’s chain: register a device token, send to explicit device_token_ids with per-device acceptance, read the delivery receipt from the notifications log, and the registration and send errors to handle.”

Worked push samples

1. Register the device

2. Send a push

3. Read send status

4. Errors

See also

List push notification categories

Get push notification category by ID

Get web push configuration

List registered device tokens

List Live Activities

List sent push notifications

List scheduled push notifications

Get a scheduled push notification

Summarize device push telemetry

List registered VoIP call-push devices

Clear a user’s push badge count

Create a push notification category

Register a device token

Start a Live Activity

Acknowledge a push notification

Register a device token (alias)

Send a push notification

Report device-side push wake telemetry

Send a push configuration test

Register a VoIP (PushKit) / high-priority FCM call token

Update a Live Activity

Enable or disable a device token

Delete push notification category

Delete a device token

End a Live Activity

Cancel a scheduled push notification

Unregister a VoIP call-push device