Notification APIs
Version: aju17f20mq
Use the reference below for request and response fields and operation-specific requirements.
Overview
Register devices, read inbox messages and manage notification preferences, workflows and dispatch. Provider and channel availability depend on deployment configuration.
Authentication
User-facing calls act for the authenticated beneficiary. A backend sk_… key uses an authorized X-On-Behalf-Of selection with users:impersonate; a client pk_… key accompanies that user’s JWT from the configured issuer. Never expose a secret key in a client. Raw identity headers and recipient IDs are not authentication. See Authentication.
Public management operations under /manage/ belong in trusted backend tooling. The API accepts a verified backend key or configured standalone JWT for tenant-context management; it does not enforce an operation-specific admin role or permission there. Do not treat this acceptance as a secure admin authorization contract. Restrict access at your application boundary. Get/update/delete of the caller’s subscriber profile still require user context.
Tenant context comes from the authenticated request. Client-supplied X-Tenant-Id, X-User-Id or X-Project-Id do not grant authority. The current public integration uses the default project. Do not rely on project headers for separate project, test/live or customer isolation on this API.
Send acknowledgements mean the provider accepted a trigger, not that a recipient received or read it. Preference state, channel registration and topic membership do not by themselves establish consent or sending authority.
Related guide: Notifications
JSON conventions
Requests accept snake_case or camelCase field names; responses use camelCase. Ordinary default-valued scalars and empty repeated fields can be omitted. Explicitly present optional scalars, map values and well-known JSON types follow their own presence rules: an explicit false, 0 or empty value is not universally equivalent to absence. Decode each field according to its schema. 64-bit integers use JSON strings; preserve their precision. Unknown request fields are generally discarded before validation, so a typo can silently change behavior. This is not a guarantee that arbitrary fields or future client contracts are supported. See API conventions.
User: Channel Registration
Register and manage push notification devices and channels. See the Notifications guide.
- Register a push notification device
- Unregister a push notification device
- Get registered notification channels
- Get an inbox session token
User: In-App Inbox
Real-time in-app inbox — session token, feed, mark, and delete. See the Notifications guide.
- Get inbox feed messages
- Get unseen and unread inbox counts
- Mark a single inbox message
- Mark all inbox messages
- Delete an inbox message
- Archive an inbox message
- Unarchive an inbox message
- Archive all inbox messages
- Archive all read inbox messages
- Complete an inbox message action
- Revert an inbox message action
User: Preferences
Get and update per-channel notification preferences. See the Notifications guide.
- Get notification preferences
- Update global notification preferences
- Update per-workflow notification preferences
- Bulk-update per-workflow preferences
Management: Notification Dispatch
Send, broadcast, bulk-send, topic-send, and cancel notifications. See the Notifications guide.
Management: Topics
Pub/sub fan-out — create topics, manage subscribers, send to topic. See the Notifications guide.
- Create a notification topic
- Delete a notification topic
- Add subscribers to a topic
- Remove subscribers from a topic
- List subscribers of a topic
- Check if a user is subscribed to a topic
- Send a notification to all topic subscribers
Management: Digest
Batched digest delivery and cancellation. See the Notifications guide.
Management: Subscribers
Create, read, update, delete, and list notification subscribers. See the Notifications guide.
- Create a notification subscriber
- Get the caller's subscriber profile
- Update subscriber profile data
- Delete the caller's subscriber profile
- List all subscribers
Management: Activity & Status
Query delivery status and notification activity logs. See the Notifications guide.
Management: Providers
Configure and list delivery providers (FCM, SendGrid, etc.). See the Notifications guide.
Management: Workflows
Create, update, get, list, and delete notification workflows. See the Notifications guide.
- Create a notification workflow
- Update an existing notification workflow
- Get a notification workflow
- List notification workflows
- Delete a notification workflow
- Get pending workflow changes
- Promote a single workflow change
- Promote all pending workflow changes
Server 1
Travila API
X-API-Key
Project/service API key. Use pk_… only with a verified end-user JWT; backend sk_… calls that require a user use authorized on-behalf-of context. Management operations can have different requirements; consult the operation and authentication guide.
X-On-Behalf-Of
The end user this call acts for. Required with an sk_… key, because a secret key identifies your tenant and not a user; omitting it returns 401 authenticated user_id is required. The key needs the users:impersonate scope or the call fails with 403 insufficient_scope.
Authorization: Bearer
JWT verified by the configured issuer. User-facing calls require an effective user. Tenant-context management currently accepts verified JWT context without a separate operation/admin-role check. Keep management operations in trusted backend tooling; a valid JWT alone is not an administrator permission.
Authentication credentials
- API Key: apiKeyAuth
- API Key: onBehalfOf
- HTTP: bearerAuth
| Setting | Value |
|---|---|
| Security scheme type | apiKey |
| header parameter name | X-API-Key |
| Setting | Value |
|---|---|
| Security scheme type | apiKey |
| header parameter name | X-On-Behalf-Of |
| Setting | Value |
|---|---|
| Security scheme type | http |
| Scheme | bearer |
Operations
- Register a push notification device —
POST /api/v1/notifications/register-push-device - Unregister a push notification device —
POST /api/v1/notifications/unregister-push-device - Get registered notification channels —
POST /api/v1/notifications/get-registered-channels - Get an inbox session token —
POST /api/v1/notifications/get-inbox-session - Send a notification to a user —
POST /api/v1/notifications/manage/send - Send a notification to multiple users —
POST /api/v1/notifications/manage/send-bulk - Cancel a pending notification —
POST /api/v1/notifications/manage/cancel - Get inbox feed messages —
POST /api/v1/notifications/get-inbox-feed - Get unseen and unread inbox counts —
POST /api/v1/notifications/get-inbox-unseen-count - Mark a single inbox message —
POST /api/v1/notifications/mark-inbox-message - Mark all inbox messages —
POST /api/v1/notifications/mark-all-inbox-messages - Delete an inbox message —
POST /api/v1/notifications/delete-inbox-message - Archive an inbox message —
POST /api/v1/notifications/archive-inbox-message - Unarchive an inbox message —
POST /api/v1/notifications/unarchive-inbox-message - Archive all inbox messages —
POST /api/v1/notifications/archive-all-inbox-messages - Archive all read inbox messages —
POST /api/v1/notifications/archive-all-read-inbox-messages - Complete an inbox message action —
POST /api/v1/notifications/complete-inbox-action - Revert an inbox message action —
POST /api/v1/notifications/revert-inbox-action - Create a notification topic —
POST /api/v1/notifications/manage/create-topic - Delete a notification topic —
POST /api/v1/notifications/manage/delete-topic - Add subscribers to a topic —
POST /api/v1/notifications/manage/add-subscribers-to-topic - Remove subscribers from a topic —
POST /api/v1/notifications/manage/remove-subscribers-from-topic - List subscribers of a topic —
POST /api/v1/notifications/manage/list-topic-subscribers - Check if a user is subscribed to a topic —
POST /api/v1/notifications/manage/check-topic-subscription - Send a notification to all topic subscribers —
POST /api/v1/notifications/manage/send-to-topic - Send a notification with digest aggregation —
POST /api/v1/notifications/manage/send-with-digest - Cancel a pending digest event —
POST /api/v1/notifications/manage/cancel-digest-event - Get notification preferences —
POST /api/v1/notifications/get-preferences - Update global notification preferences —
POST /api/v1/notifications/update-global-preference - Update per-workflow notification preferences —
POST /api/v1/notifications/update-workflow-preference - Bulk-update per-workflow preferences —
POST /api/v1/notifications/bulk-update-preferences - Update subscriber profile data —
POST /api/v1/notifications/manage/update-subscriber-data - Get the caller's subscriber profile —
POST /api/v1/notifications/manage/get-subscriber - Delete the caller's subscriber profile —
POST /api/v1/notifications/manage/delete-subscriber - Create a notification subscriber —
POST /api/v1/notifications/manage/create-subscriber - List all subscribers —
POST /api/v1/notifications/manage/list-subscribers - Get delivery status of a notification —
POST /api/v1/notifications/manage/get-delivery-status - Get notification activity log —
POST /api/v1/notifications/manage/get-notification-activity - Configure a notification provider —
POST /api/v1/notifications/manage/configure-provider - List configured providers —
POST /api/v1/notifications/manage/get-providers - Create a notification workflow —
POST /api/v1/notifications/manage/create-workflow - Update an existing notification workflow —
POST /api/v1/notifications/manage/update-workflow - Get a notification workflow —
POST /api/v1/notifications/manage/get-workflow - List notification workflows —
POST /api/v1/notifications/manage/list-workflows - Delete a notification workflow —
POST /api/v1/notifications/manage/delete-workflow - Get pending workflow changes —
POST /api/v1/notifications/manage/get-pending-changes - Promote a single workflow change —
POST /api/v1/notifications/manage/promote-change - Promote all pending workflow changes —
POST /api/v1/notifications/manage/promote-all-changes
Document ID: DOC-API-notifications-overview. Section identities and revisions.
| Section | Stable reference |
|---|---|
| Overview | DOC-API-notifications-overview#overview |
| Authentication | DOC-API-notifications-overview#authentication |
| JSON conventions | DOC-API-notifications-overview#json-conventions |
| User: Channel Registration | DOC-API-notifications-overview#reference-group-1 |
| User: In-App Inbox | DOC-API-notifications-overview#reference-group-2 |
| User: Preferences | DOC-API-notifications-overview#reference-group-3 |
| Management: Notification Dispatch | DOC-API-notifications-overview#reference-group-4 |
| Management: Topics | DOC-API-notifications-overview#reference-group-5 |
| Management: Digest | DOC-API-notifications-overview#reference-group-6 |
| Management: Subscribers | DOC-API-notifications-overview#reference-group-7 |
| Management: Activity & Status | DOC-API-notifications-overview#reference-group-8 |
| Management: Providers | DOC-API-notifications-overview#reference-group-9 |
| Management: Workflows | DOC-API-notifications-overview#reference-group-10 |
| Server 1 | DOC-API-notifications-overview#reference-server-1 |
| X-API-Key | DOC-API-notifications-overview#authentication-apiKeyAuth |
| X-On-Behalf-Of | DOC-API-notifications-overview#authentication-onBehalfOf |
| Authorization: Bearer | DOC-API-notifications-overview#authentication-bearerAuth |