Notifications
API: notifications and email templates
Source: notification_handler.go, email_template_handler.go, systemdomain.Notification. Admin: AdminAuth() + RoleAuth("admin").
Unblock portal HTTP is Enterprise-only. Setup is provided separately to Enterprise customers.
GET /api/v1/notifications
Purpose. List notifications.
Authentication. Admin.
Parameters (query):
Scroll sideways to see the full table. Use the arrow keys when focused.
| Param | Default |
|---|---|
type | |
status | |
severity | |
severity_threshold | |
agent_id | |
limit | 50 if omitted |
offset | 0 |
Request. Empty.
Example request.
curl -sS 'https://manager.example.com:8443/api/v1/notifications?limit=50' \
-H "Authorization: Bearer TOKEN"Response (200).
{
"success": true,
"data": {
"notifications": [],
"unread_count": 0,
"total": 0
}
}Notification object: id, type, title, message, severity, status, agent_id, rule_id, log_id, metadata, count, created_at, read_at. notifications is never JSON null (empty array).
Errors. 500 Failed to retrieve notifications.
Edition. SHARED.
GET /api/v1/notifications/:id
Purpose. One notification.
Authentication. Admin.
Parameters. :id integer.
Response (200). {"success":true,"data":{"notification":{...}}}. 400 Invalid notification ID; 404 Notification not found; 500.
Edition. SHARED.
POST /api/v1/notifications
Purpose. Create a notification (also used internally). Enterprise write gate FeatureNotifications.
Authentication. Admin.
Request (NotificationRequest):
Scroll sideways to see the full table. Use the arrow keys when focused.
| Field | Required |
|---|---|
type | yes; must pass IsValidNotificationType |
title | yes |
message | yes |
severity | default medium if empty |
agent_id / rule_id / log_id | optional |
metadata | JSON object or omitted |
Example request.
{
"type": "security",
"title": "Example",
"message": "Example notification",
"severity": "medium"
}Response (201/200). success + notification. 400 Invalid request format / Invalid notification type / Invalid metadata. Metadata must be a JSON object.
Edition. SHARED.
PUT /api/v1/notifications/:id/read
Purpose. Mark one read.
Authentication. Admin.
Response. success gin.H. 400/404/500.
Edition. SHARED.
PUT /api/v1/notifications/read-all
Purpose. Mark all read.
Authentication. Admin.
Response. success gin.H. 500 on failure.
Edition. SHARED.
DELETE /api/v1/notifications/:id
Purpose. Delete one notification.
Authentication. Admin.
Response (200). {"success":true,"message":"Notification deleted successfully","deleted":true,"already_clear":false}.
Edition. SHARED.
GET /api/v1/notifications/unread-count
Purpose. Unread counter.
Authentication. Admin.
Response (200). {"success":true,"data":{"unread_count":0}}. 500 Failed to get unread count.
Edition. SHARED.
GET /api/v1/notifications/:id/deliveries
Purpose. Delivery attempts for one notification.
Authentication. Admin.
Response (200). {"success":true,"data":{"deliveries":[]}} (never null). 400/500.
Channels in domain: email, webhook, slack, websocket.
Edition. SHARED.
GET /api/v1/notifications/health
Purpose. Notification subsystem health.
Authentication. Admin.
Response (200). {"success":true,"data": <health>}. API_SCHEMA_DOCUMENTATION_BLOCKED for nested health fields (GetNotificationHealth service object).
Edition. SHARED.
GET /api/v1/notifications/preferences/me
PUT /api/v1/notifications/preferences/me
Purpose. Current admin notification preferences.
Authentication. Admin (user_id from context).
PUT body:
Scroll sideways to see the full table. Use the arrow keys when focused.
| Field |
|---|
email_enabled |
slack_enabled |
webhook_enabled |
severity_threshold (low | medium | high | critical; default medium) |
quiet_hours_enabled |
quiet_hours_start / quiet_hours_end (0–23) |
timezone |
subscribed_types |
Response. {"success":true,"data":{"preference":{...}}}. 401 Unauthorized; 400 invalid threshold/hours; 500.
Edition. SHARED.
Email templates
Prefix /api/v1/email-templates. Writes gated on Enterprise FeatureNotifications.
GET /api/v1/email-templates
GET /api/v1/email-templates/variables
POST /api/v1/email-templates/preview
GET /api/v1/email-templates/event/:event_type
GET /api/v1/email-templates/:id
POST /api/v1/email-templates
PUT /api/v1/email-templates/:id
DELETE /api/v1/email-templates/:id
POST /api/v1/email-templates/:id/test
Purpose. Template CRUD/preview/test.
Authentication. Admin.
Request/response. API_SCHEMA_DOCUMENTATION_BLOCKED — EmailTemplateHandler uses gin.H around template records. Variables endpoint returns a named list for preview substitution. Test/preview must not log recipient secrets.
Edition. SHARED.
Security. POST .../test sends mail. Prefer a lab notification object if it would fire real SMTP. Documented for operators who already configured notifications.email.
Related
- Notifications integration
- Unblock portal (Enterprise-only; customer setup is not a public page)