core/docs/ICD/notifications.md

Notifications

Real-time notification infrastructure with WebSocket delivery and optional email transport.

CRUD

GET    /notifications                → paginated list
GET    /notifications/unread-count   → { "count": 5 }
PATCH  /notifications/:id/read       → mark one as read
POST   /notifications/mark-all-read  → mark all as read
DELETE /notifications/:id

Notification object:

{
  "id": "uuid",
  "user_id": "uuid",
  "type": "role.fallback|memory.extracted|system.announcement|...",
  "title": "Role Fallback Triggered",
  "body": "Primary model unavailable, using fallback",
  "metadata": {},
  "read": false,
  "created_at": "..."
}

Preferences

Users control per-type delivery:

GET    /notifications/preferences            → { "preferences": [...] }
PUT    /notifications/preferences/:type      ← { "in_app": true, "email": false }
DELETE /notifications/preferences/:type       → reset to default

Resolution: specific type pref → user wildcard * pref → system default (in_app=true, email=false).

---