Publish a dashboard notification

Persists a notification and pushes it over the dashboard WebSocket to every connected client the audience covers.

Administrators only. Reading is open to any authenticated user because a caller only ever receives rows their role already entitles them to, but a single publish reaches every dashboard user on the deployment, so it is restricted to the local admin. On a deployment with dashboard auth disabled every request is treated as local admin.

Notifications expire 30 days after creation and are pruned hourly.

POST /api/notifications

Error

A valid request URL is required to generate request examples

201

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "audience": "all",
  "severity": "info",
  "title": "<string>",
  "message": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "expires_at": "2023-11-07T05:31:56Z",
  "role_ids": [
    123
  ],
  "action_label": "<string>",
  "action_path": "<string>"
}

Authorizations

ManagementBearerAuthBasicAuth

Authorization · string · header · required

Management API authentication for /api/* endpoints. Use the Authorization header with Bearer <token>, where <token> is one of:

• a Bifrost management API key,
• a dashboard session token issued by POST /api/session/login,
• base64 of <admin-username>:<admin-password> (legacy equivalent of BasicAuth).

Virtual keys (sk-bf-*) and the x-api-key header are not accepted on management APIs - the sole exception is GET /api/governance/virtual-keys/quota, which is virtual-key-only.

Body

application/json

A notification to publish. IDs and both timestamps are assigned by the server and cannot be supplied.

audience · enum<string> · required

Who the notification reaches. all is every dashboard user; roles limits it to the listed RBAC roles, enforced on both the list endpoint and the WebSocket fan-out.

Available options: all, roles

severity · enum<string> · required

Visual weight the dashboard gives the notification.

Available options: info, success, warning, error

title · string · required

Trimmed before validation.

Required string length: 1 - 160

message · string · required

Trimmed before validation.

Required string length: 1 - 4000

role_ids · integer<int64>[]

Required when audience is roles, and must be empty otherwise. Duplicates are removed and the list is sorted before it is stored.

Required range: x >= 1

action_label · string

Label for the notification's action. Must be supplied together with action_path, or not at all.

action_path · string

Dashboard-internal absolute path the action opens, for example /workspace/providers. Absolute URLs, host-relative // paths, and anything not starting with / are rejected, so a notification cannot be used to send users off-site.

Pattern: ^/(?!/).*

Response

201

application/json

Notification published and broadcast

A persisted dashboard notification.

id · string<uuid> · required

audience · enum<string> · required

Who the notification reaches. all is every dashboard user; roles limits it to the listed RBAC roles, enforced on both the list endpoint and the WebSocket fan-out.

Available options: all, roles

severity · enum<string> · required

Visual weight the dashboard gives the notification.

Available options: info, success, warning, error

title · string · required

message · string · required

created_at · string<date-time> · required

expires_at · string<date-time> · required

Always 30 days after created_at. Expired rows are pruned hourly and are not returned once pruned.

role_ids · integer<int64>[]

action_label · string

action_path · string