Administrative Notifications

Query, filter, and mark notifications read—plus live SSE streaming and its reliability boundary.

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 doesn't 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. If you're seeing 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 doesn't mean resolved and doesn't 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 helps with live display but doesn't 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. Don't 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 don't establish that no notifications exist. Read state, filters, and pagination also affect counts.

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