API

Notifications and protocols

Your notifications, and an organization's notification protocols.

See Notifications and Caity by phone for how events, channels, quiet hours and protocols work.

Every route below, with its parameters, request and response, errors and samples, is in the API reference.

Route	What it does
`GET /v1/me/notifications/devices`	The app's push registrations on your phones (`deviceId` is the phone's install id; rows of the withdrawn product apps too, until they're removed), with `appId`, `platform`, and the `name`, `model`, `osVersion` and `appVersion` the app sent. No push tokens.
`PUT /v1/me/notifications/devices/:deviceId`	Registers or refreshes a mobile app's Expo push token on this phone (`token`, `platform`, `appId`, optional `name`, `model`, `osVersion`, `appVersion`, and `opensSealed` from an Android build that decrypts end-to-end pushes itself, which then gets them as data-only messages). A mobile app's token ties the registration to its sign-in, so signing the app out removes it, and `appId` must be that app. People only, not assistants. Only the one app (`appId` `home`) registers: a withdrawn product app gets 410.
`DELETE /v1/me/notifications/devices/:deviceId`	Removes an app's push registration on this phone (`appId`, default `caity`: a withdrawn app may remove its own). Signing the app out removes it too. People only, not assistants.
`GET /v1/me/notifications/live-activities`	Your iPhone Live Activity registrations: per phone and app (`home`; `maps` and `vehicles` from the withdrawn apps until they expire), the push-to-start entry (`kind: start`) and each running flight activity (`kind: activity`, with `orgId`, `hex`, `watchId` or `local`), the APNs `environment` and, on the push-to-start entry, the flight activities the app last reported running (`running`). No tokens.
`PUT /v1/me/notifications/live-activities/start/:installId`	Registers the app's push-to-start token on this iPhone (`token` in hex, `appId` `home`: a withdrawn app gets 410, `environment` `production` or `development`, `bundleId`, and `running`: the hexes of the flight activities running in the app, sent again whenever they change), so a flight watch can start a Live Activity at takeoff. From the signed-in iPhone app only; tied to its sign-in.
`DELETE /v1/me/notifications/live-activities/start/:installId`	Removes the app's push-to-start token on this phone (`appId`). Signing the app out removes it too.
`PUT /v1/me/notifications/live-activities/:activityId`	Registers a running flight Live Activity's update token (`token`, `appId`, `environment`, `bundleId`, `installId`, `orgId`, `hex`, and `watchId` or `local: true` for one started with Track live). Needs `maps:read` in the org; from the signed-in iPhone app only.
`DELETE /v1/me/notifications/live-activities/:activityId`	The activity ended or was dismissed on the phone: no more updates (`installId`, `appId`). `stopped=1`: the person stopped a flight's in the app, so no fresh one takes its place, as one swiped away gets.
`GET /v1/me/notifications/settings`	What reaches the person where, event by event, with the app each belongs to (the phone groups them by app: Home → Notifications). The same settings as ID → Notifications. `textsOff`: the event never texts or calls (Maps' events while Admin's "SMS for Maps alerts" is off), so the apps don't offer either.
`PUT /v1/me/notifications/settings/prefs`	Quiet hours, the time zone, important senders and calendar reminders (the events' channels stay as they are); people only, from their own apps. Cleaned as ID cleans them (`cleanPrefs`).
`PUT /v1/me/notifications/settings/events`	Some events' channels (the rest stay as they are); people only, from their own apps.
`GET /v1/me/notifications/web-push`	Web push in your browsers: the key browsers subscribe with (`publicKey`, null where the stage has none) and your subscriptions, one per app per browser (`subId`, `app`, `label`, `createdAt`, `lastUsedAt`). No endpoints or keys.
`POST /v1/me/notifications/web-push`	Turns on web push for one app in this browser (the header's bell): the browser's `endpoint` and `keys` (`p256dh`, `auth`), the web `app`, the browser's id (`browserId`, so a notice shows once per browser) and a `label`. Endpoints must be a browser push service's. A browser signed in as someone else moves to you. Answers the `subId`. People only, not assistants; 503 where the stage has no web push key.
`DELETE /v1/me/notifications/web-push/:subId`	Turns off one of your web push subscriptions (the SHA-256 of its endpoint, base64url). Signing out of the app does it too.
`GET /v1/me/notifications`	Your notifications, newest first (`cursor`, `limit`): title, body, link, read, and whether one waits for an acknowledgement (escalating alerts). `app`: only that mobile app's notices (`home`: every app's). People only.
`POST /v1/me/notifications/read`	Marks notifications read (`noticeIds`, up to 100).
`POST /v1/me/notifications/:noticeId/ack`	Acknowledges a notification: its escalation (later texts or calls) stops. `acked: false` when it already was.
`GET /v1/orgs/:orgId/notify/protocols/templates`	Ready-made notification protocols (production on-call, meeting guard, invitation chaser, VIP mail, service desk SLA, agent jobs).
`GET /v1/orgs/:orgId/notify/protocols`	The organization's notification protocols with their rules and what each is attached to.
`POST /v1/orgs/:orgId/notify/protocols`	Creates a protocol from `{ template }` or `{ name, description?, enabled?, rules }` (rules: events, optional match on event attributes, steps with minutes and channels, roles, overrideQuietHours, beforeEvent). Owners and admins.
`GET /v1/orgs/:orgId/notify/protocols/:protocolId`	One protocol with its attachments.
`PUT /v1/orgs/:orgId/notify/protocols/:protocolId`	Replaces a protocol's name, description, on/off and rules. Owners and admins.
`DELETE /v1/orgs/:orgId/notify/protocols/:protocolId`	Deletes a protocol and its attachments. Owners and admins.
`POST /v1/orgs/:orgId/notify/protocols/:protocolId/attachments`	Attaches the protocol to `{ type, id, label? }`: the whole organization (`org`) or a Serverless App Service, Issues space, calendar, mailbox or agent. Events about it then follow the protocol. Owners and admins.
`DELETE /v1/orgs/:orgId/notify/protocols/:protocolId/attachments/:resourceType/:targetId`	Detaches the protocol from that resource. Owners and admins.