Administrative Notifications

Filters, shared read state, creation and the reliability boundary of live events.

Where notifications appear

Administrators use /admin/notifications. These are Core-managed records, not email or user chat. Notifications, business analytics and system health are separate sources; one notification does not prove a metric or incident recovered.

GET /api/v1/admin/notifications supports page, pageSize, service, severity, q, unreadOnly, from and to. It defaults to 20 records, with a maximum of 200. severity is critical, warning, info or success. For no results, clear filters and verify the time range first.

Mark records read

POST /api/v1/admin/notifications/mark-read accepts an ids array containing record UUIDs returned by the list. Reread the list to verify the change.

Read state belongs to the shared administrative notification record, not a separate inbox for each administrator. Others may see your change. Read does not mean resolved and does not undo an event or delete logs.

Create a notification

POST /api/v1/admin/notifications requires administrator authentication and title, description, severity and service, with optional meta. Titles allow 200 characters, descriptions 2000, and service names 100. severity must be a supported enum value.

State only known facts. Never include access tokens, database connection strings, codes or raw user records in description or meta. Other administrators may search or receive the content live. Success returns 201; invalid input returns 400.

SSE is not a durable queue

GET /api/v1/admin/notifications/stream uses SSE and Bearer access-token authentication, with a heartbeat roughly every 25 seconds. It assists live display, but does not promise reliable historical replay through Last-Event-ID.

This source version keeps connections within one Core process. Disconnection, restart or routing to another instance can leave gaps. Query the list again after reconnecting and merge records without duplicating them. The list is the basis for recovering current records. Do not put a token in a query parameter just to use EventSource.

Troubleshoot

If both list and stream fail, check identity and administrative permission. If only the stream disconnects, check proxy streaming support and timeouts. Heartbeats without events do not establish that no notifications exist. Read state, filters and pagination also affect counts.

See Local development for service checks and Deployment for protecting logs.