Notifications

Configure where alerts are delivered and manage browser push subscriptions. All endpoints are authenticated with a Bearer JWT (see Authentication).

Endpoints

Method	Path	Description
GET	/api/v1/notification-channels	List notification channels
POST	/api/v1/notification-channels	Create a channel
PUT	/api/v1/notification-channels/{channel_id}	Update a channel
DELETE	/api/v1/notification-channels/{channel_id}	Delete a channel
POST	/api/v1/notification-channels/{channel_id}/test	Send a test notification
GET	/api/v1/push/vapid-public-key	Get the public key for web-push
POST	/api/v1/push/subscribe	Register a web-push subscription
DELETE	/api/v1/push/subscribe	Remove a web-push subscription
GET	/api/v1/notifications/marks	What you have read, dismissed and acknowledged in the bell
PATCH	/api/v1/notifications/marks	Add or remove marks of one kind

Notification channels

A channel describes one delivery destination. Channel-specific settings go in the config object; secret values are masked in responses. Webhook and chat destinations must use HTTPS and a public host.

Supported channel_type values: email, slack, webhook, sms, msteams, telegram, pagerduty, opsgenie, servicenow, jira.

Create a channel

POST /api/v1/notification-channels

Email:

{
  "name": "Maintenance Team Email",
  "channel_type": "email",
  "config": { "to_email": "maintenance@example.com" },
  "is_active": true,
  "notify_on_alert": true
}

Slack:

{
  "name": "Alerts Slack",
  "channel_type": "slack",
  "config": { "webhook_url": "https://hooks.slack.com/services/T00/B00/XXXX" },
  "is_active": true,
  "notify_on_alert": true
}

Generic webhook:

{
  "name": "Custom Integration",
  "channel_type": "webhook",
  "config": {
    "url": "https://example.com/webhook",
    "headers": { "X-Custom-Header": "value" }
  },
  "is_active": true,
  "notify_on_alert": true
}

Response:

{
  "id": "...",
  "tenant_id": "...",
  "channel_type": "slack",
  "name": "Alerts Slack",
  "config": { "webhook_url": "***" },
  "is_active": true,
  "notify_on_alert": true,
  "created_by": "USER_UUID",
  "created_at": "2026-08-05T10:00:00Z"
}

Test a channel

POST /api/v1/notification-channels/{channel_id}/test

Sends a test message to the channel and reports whether it succeeded.

{ "success": true }

Web push

Deliver alerts as browser push notifications. See the Webhook & delivery setup guide for end-to-end wiring.

Get the public key

GET /api/v1/push/vapid-public-key

{ "public_key": "BMod…", "enabled": true }

When enabled is false, web push is not available and subscribe calls return 503.

Subscribe

POST /api/v1/push/subscribe

Register the browser PushSubscription for the current user's device.

{
  "endpoint": "https://push.example.com/subscription/abc123",
  "keys": { "p256dh": "BEl…", "auth": "k9X…" },
  "user_agent": "Mozilla/5.0 …"
}

{ "subscribed": true }

Unsubscribe

DELETE /api/v1/push/subscribe

Send the same endpoint to remove the subscription. Returns 404 if no matching subscription exists.

Notification marks

What a person has done with the notifications in the portal's bell, kept per user on the server so it follows them between devices: the alerts they have read, the announcements they have read or dismissed, and the standing notifications (low stock, maintenance due, and so on) they have acknowledged. Each person reads and changes only their own; service accounts are refused with 403.

Read your marks

GET /api/v1/notifications/marks

{
  "alert_read": ["7c9e6679-7425-40de-944b-e07fc1f90ae7"],
  "announcement_read": [],
  "announcement_dismissed": ["2f1b3c4d-..."],
  "condition_acknowledged": ["low_stock:1b4e28ba-2fa1-11d2-883f-0016d3cca427"]
}

Change your marks

PATCH /api/v1/notifications/marks

{ "kind": "condition_acknowledged", "add": ["low_stock:p2"], "remove": ["low_stock:p1"] }

Field	Type	Description
kind	string	One of alert_read, announcement_read, announcement_dismissed, condition_acknowledged
add	string[]	Keys to mark; adding one twice keeps one. Up to 500 per request, each 1–255 characters
remove	string[]	Keys to unmark. Up to 500 per request

Returns 204 No Content. Read-alert marks are kept for 7 days, then dropped: the bell only lists a day of alerts.