Notifications API

The Notifications API backs the dashboard bell: a per-user feed of in-app alerts — delivery failures, billing events, security sign-ins, port-status changes, agent handoffs, SLA breaches, and more. Read the feed with the list endpoints, mark rows read or dismiss them, and subscribe to GET /api/v1/notifications/stream to receive new notifications in real time. Base path: /api/v1/notifications Authentication: session JWT. Notifications are scoped to the signed-in user and their tenant, so these endpoints use your dashboard session rather than a workspace API key. The live stream supports a query-parameter token so browsers can authenticate EventSource connections (see Live stream).

Method	Path	Purpose
`GET`	`/api/v1/notifications/`	List your notifications (cursor-paginated, filterable)
`GET`	`/api/v1/notifications/unread-count`	Unread count for the bell badge
`PUT`	`/api/v1/notifications/{id}/read`	Mark a single notification read
`POST`	`/api/v1/notifications/read-all`	Mark every unread notification read
`DELETE`	`/api/v1/notifications/{id}`	Dismiss (delete) one of your notifications
`POST`	`/api/v1/notifications/sse-token`	Mint a short-lived one-time token for the stream
`GET`	`/api/v1/notifications/stream`	Subscribe to new notifications over SSE

Using the SDKs

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

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

const res = await orbit.notifications.list();

Python (same call via the SDK’s escape hatch):

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

res = client.request("GET", "/notifications")

The Python SDK is core-scope — it wraps the 8 core resources (messaging, voice, contacts, campaigns, verify, numbers) and reaches everything else through the generic client.request() escape hatch above. See the Python SDK. Returns the typed ApiResponse envelope. See the SDK index at SDK quickstart.

The notification object

{
  "id": "notif_0a1b2c3d4e5f60718293a4b5c6d7e8f9",
  "user_id": "user_abc",
  "org_id": "org_xyz",
  "kind": "payment_failed",
  "severity": "error",
  "title": "Payment failed",
  "body": "Your last top-up was declined.",
  "action_url": "/billing",
  "read_at": null,
  "created_at": "2026-06-30T12:00:00.000Z",
  "expires_at": null,
  "source_pillar": "system",
  "category": "billing"
}

severity is one of info, warning, error — it drives the icon colour.
read_at is null until the notification is marked read.
source_pillar and category are coarse facets used by the dashboard filter chips. source_pillar is one of cpaas, ucaas, ccaas, aiaas, cxaas, cspaas, naas, verify, system. category is one of sla_breach, missed_call, campaign_result, agent_state, verification, webhook_failure, billing, security, compliance, system.
Notifications past their expires_at are filtered out of the list automatically.

List notifications — `GET /api/v1/notifications/`

Returns your notifications, newest first, in a cursor-paginated page.

curl "https://api.orbit.devotel.io/api/v1/notifications?limit=20&unread_only=true" \
  -H "Authorization: Bearer <session-jwt>"

Query parameters

Parameter	Type	Default	Notes
`limit`	integer	`20`	Page size, `1`–`100`.
`cursor`	string	—	A notification `id`; the page starts strictly after that row.
`unread_only`	boolean	—	When `true`, returns only unread rows.
`kind`	string	—	Filter by notification kind (e.g. `payment_failed`).
`severity`	string	—	One of `info`, `warning`, `error`.
`source_pillar`	string	—	One of the pillar values above.
`category`	string	—	One of the category values above.

{
  "data": {
    "data": [ /* notification objects */ ],
    "pagination": { "cursor": "notif_…", "has_more": true }
  },
  "meta": { "request_id": "req_…", "timestamp": "2026-06-30T12:00:00.000Z" }
}

To fetch the next page, pass pagination.cursor back as the cursor query parameter. When has_more is false, cursor is null and you have reached the end of the feed.

Unread count — `GET /api/v1/notifications/unread-count`

Returns { "count": <n> } — the number backing the bell badge.

curl "https://api.orbit.devotel.io/api/v1/notifications/unread-count" \
  -H "Authorization: Bearer <session-jwt>"

Mark read — `PUT /api/v1/notifications/{id}/read`

Marks a single notification read and returns the updated row. Returns 404 if the id does not exist or is not yours.

curl -X PUT \
  "https://api.orbit.devotel.io/api/v1/notifications/notif_0a1b…/read" \
  -H "Authorization: Bearer <session-jwt>"

Mark all read — `POST /api/v1/notifications/read-all`

Marks every unread notification read in one call. Returns { "affected": <n> } — the number of rows updated.

curl -X POST \
  "https://api.orbit.devotel.io/api/v1/notifications/read-all" \
  -H "Authorization: Bearer <session-jwt>"

Dismiss — `DELETE /api/v1/notifications/{id}`

Deletes one of your notifications and returns { "deleted": "<id>" }. Returns 404 if the id does not exist or is not user-scoped.

curl -X DELETE \
  "https://api.orbit.devotel.io/api/v1/notifications/notif_0a1b…" \
  -H "Authorization: Bearer <session-jwt>"

Organization-wide notifications are shared across the workspace and cannot be dismissed by an individual user — they clear on their own when they expire. Dismiss applies only to your own user-scoped rows.

Live stream — SSE

GET /api/v1/notifications/stream pushes new notifications to the browser in real time over Server-Sent Events. Browsers cannot set request headers on an EventSource, so the stream accepts the session token as a query parameter. Two authentication paths are supported:

One-time token (preferred). Call POST /api/v1/notifications/sse-token to mint a short-lived token, then open the stream with ?ot=<token>. This keeps your long-lived session JWT out of server access logs and browser history.
Legacy JWT (fallback). Open the stream with ?token=<session-jwt> directly. Use this only when a one-time token is unavailable.

Mint a one-time token — `POST /api/v1/notifications/sse-token`

curl -X POST \
  "https://api.orbit.devotel.io/api/v1/notifications/sse-token" \
  -H "Authorization: Bearer <session-jwt>"

On success returns 201 with the token and its lifetime:

{
  "data": { "ot": "sset_…", "expires_in": 90 },
  "meta": { "request_id": "req_…", "timestamp": "2026-06-30T12:00:00.000Z" }
}

The token is valid for 90 seconds and is meant to be redeemed once, immediately, by opening the stream. Mint a fresh token each time you (re)connect. If the token store is briefly unavailable the endpoint degrades gracefully: it returns 200 with { "ot": null, "fallback": "token" } instead of an error. When you see ot: null, fall back to opening the stream with ?token=<session-jwt>.

Open the stream — `GET /api/v1/notifications/stream`

curl -N \
  "https://api.orbit.devotel.io/api/v1/notifications/stream?ot=sset_your_one_time_token"

The stream opens with a connected event, then emits one event per new notification. The event name reflects the notification type (for example notification.created); the data: line carries the notification JSON.

event: connected
data: {"type":"connected","data":{"userId":"user_abc"}}

event: notification.created
data: {"id":"notif_…","kind":"payment_failed","severity":"error", ...}

A : heartbeat comment is sent every 30 seconds to keep the connection alive. If the stream ends, reconnect — mint a fresh one-time token first if you are using the ?ot= path.

Concurrency cap — 50 streams per tenant. Each tenant may hold at most 50 concurrent SSE connections to this endpoint across the whole platform. Opening another stream over the cap is rejected with 429 and error.code = TOO_MANY_CONNECTIONS. Close streams you no longer need (each open browser tab holds one), and reuse a single connection per tab rather than opening one per component.

The stream is for browser clients: connections must come from a trusted dashboard origin with a browser User-Agent. Non-browser clients are rejected — to consume the same events from a server, use the durable Webhooks push instead.

API Reference

All Endpoints

Notifications API: in-app alerts and SSE stream

Notifications API

Using the SDKs

The notification object

List notifications — `GET /api/v1/notifications/`

Unread count — `GET /api/v1/notifications/unread-count`

Mark read — `PUT /api/v1/notifications/{id}/read`

Mark all read — `POST /api/v1/notifications/read-all`

Dismiss — `DELETE /api/v1/notifications/{id}`

Live stream — SSE

Mint a one-time token — `POST /api/v1/notifications/sse-token`

Open the stream — `GET /api/v1/notifications/stream`

See also

​Notifications API

​Using the SDKs

​The notification object

​List notifications — GET /api/v1/notifications/

​Unread count — GET /api/v1/notifications/unread-count

​Mark read — PUT /api/v1/notifications/{id}/read

​Mark all read — POST /api/v1/notifications/read-all

​Dismiss — DELETE /api/v1/notifications/{id}

​Live stream — SSE

​Mint a one-time token — POST /api/v1/notifications/sse-token

​Open the stream — GET /api/v1/notifications/stream

​See also

Notifications API

Using the SDKs

The notification object

List notifications — `GET /api/v1/notifications/`

Unread count — `GET /api/v1/notifications/unread-count`

Mark read — `PUT /api/v1/notifications/{id}/read`

Mark all read — `POST /api/v1/notifications/read-all`

Dismiss — `DELETE /api/v1/notifications/{id}`

Live stream — SSE

Mint a one-time token — `POST /api/v1/notifications/sse-token`

Open the stream — `GET /api/v1/notifications/stream`

See also