Notifications

⚠️ Preview — not yet in the public API

The endpoints on this page are part of the AurionAI helpdesk and are currently accessible only through an authenticated dashboard session. They are not yet exposed through public API keys — a request authenticated with X-API-Key returns 403. Public API-key access is planned. The reference below documents the intended contract.

Notifications

The Notifications API (v2) manages in-app notifications, email delivery preferences, quiet hours, digest settings, and notification delivery history for support agents.

All routes live under /api/v2/notifications and are gated by role (super_admin, tenant_owner, tenant_admin, agent, supervisor, tenant_user, tenant_readonly), with some admin-only routes called out below. There is no notifications:* API-key scope — access is role-based.

List Notifications

Returns the current user's in-app notifications as a top-level JSON array.

curl "https://apps.aurionai.net/api/v2/notifications?unread_only=true&limit=20" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Response:

[
  {
    "id": "notif_abc123",
    "event_type": "ticket_assigned",
    "title": "New ticket assigned to you",
    "body": "Ticket #1042: VPN not connecting",
    "entity_type": "ticket",
    "entity_id": "1042",
    "read": false,
    "read_at": null,
    "created_at": "2026-03-08T10:30:00Z"
  }
]

Query Parameters:

Mark All as Read

curl -X POST "https://apps.aurionai.net/api/v2/notifications/read-all" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Returns 204 No Content on success.

Mark Single Notification as Read

curl -X POST "https://apps.aurionai.net/api/v2/notifications/notif_abc123/read" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Returns 204 No Content on success, or 404 with {"detail": "Notification not found"} if the notification does not exist.

Notification Preferences

Control which events generate notifications and through which channels. Preferences are returned as an array of per-event/channel items scoped by category.

curl "https://apps.aurionai.net/api/v2/notifications/preferences?category=agent" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Query Parameters:

Response:

[
  {
    "event_type": "ticket_assigned",
    "channel": "in_app",
    "enabled": true,
    "category": "agent"
  },
  {
    "event_type": "ticket_assigned",
    "channel": "email",
    "enabled": true,
    "category": "agent"
  }
]

Update preferences by sending an items array. Each item is a {event_type, channel, enabled, category} object. The response reports how many rows were affected.

curl -X PUT "https://apps.aurionai.net/api/v2/notifications/preferences" \
  -H "X-API-Key: itsm_sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {"event_type": "ticket_updated", "channel": "email", "enabled": true, "category": "agent"},
      {"event_type": "csat_received", "channel": "in_app", "enabled": false, "category": "agent"}
    ]
  }'

Response:

{
  "affected": 2
}

Any user may modify their own agent and billing preferences. Modifying requester, cc, or kb_review preferences requires an admin role (super_admin, tenant_owner, or tenant_admin); otherwise the request returns 403 with {"detail": "Only admins can modify requester/CC preferences"}.

Quiet Hours

Suppress non-urgent notifications during off-hours. Quiet hours are stored per user.

curl "https://apps.aurionai.net/api/v2/notifications/quiet-hours" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Response:

{
  "enabled": true,
  "start": "20:00",
  "end": "08:00",
  "timezone": "Europe/Brussels"
}

When quiet hours are not configured, enabled is false and start, end, and timezone are null.

curl -X PUT "https://apps.aurionai.net/api/v2/notifications/quiet-hours" \
  -H "X-API-Key: itsm_sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "timezone": "Europe/Brussels",
    "start": "20:00",
    "end": "08:00"
  }'

When enabled is true, all of start, end, and timezone are required (otherwise 400 with {"detail": "start, end, and timezone are required when enabled"}). start and end must be HH:MM (otherwise 400 with {"detail": "Invalid time format. Use HH:MM"}), and timezone must be a valid IANA zone. Set enabled to false to clear quiet hours. The endpoint returns {"status": "ok"}.

Digest Settings

Batch notifications into a periodic digest instead of delivering each one immediately.

curl "https://apps.aurionai.net/api/v2/notifications/digest-settings" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Response:

{
  "enabled": true,
  "interval_minutes": 60
}

curl -X PUT "https://apps.aurionai.net/api/v2/notifications/digest-settings" \
  -H "X-API-Key: itsm_sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "interval_minutes": 60
  }'

When enabled is true, interval_minutes is required (otherwise 400) and must be one of 15, 30, 60, 120, 240, 480 (otherwise 400). Set enabled to false to disable digest mode. The endpoint returns {"status": "ok"}. Held notifications are flushed by the /notification-digest cronjob at the configured interval.

Delivery Log

View the delivery history for notifications. Admin-only (super_admin, tenant_owner, tenant_admin).

curl "https://apps.aurionai.net/api/v2/notifications/delivery-log?limit=20" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Query Parameters:

Response:

{
  "items": [
    {
      "id": "log_abc123",
      "event_type": "ticket_assigned",
      "recipient_email": "agent@example.com",
      "recipient_user_id": "usr_123",
      "channel": "email",
      "status": "sent",
      "template_locale_used": "en",
      "error_message": null,
      "entity_type": "ticket",
      "entity_id": "1042",
      "retry_count": 0,
      "sent_at": "2026-03-08T10:30:01Z",
      "created_at": "2026-03-08T10:30:00Z"
    }
  ],
  "total": 137,
  "limit": 20,
  "offset": 0
}

Export the Delivery Log as CSV

Pass format=csv to the same GET /delivery-log endpoint to stream the matching rows as text/csv (up to 10,000 rows; the X-Truncated: true header is set if the result was capped). The limit/offset paging params are ignored for the CSV export.

curl "https://apps.aurionai.net/api/v2/notifications/delivery-log?format=csv&date_from=2026-03-01&date_to=2026-03-08" \
  -H "X-API-Key: itsm_sk_live_xxxx" \
  -o delivery-log.csv

Delivery Statistics

Counts of delivery-log entries grouped by status. Admin-only.

curl "https://apps.aurionai.net/api/v2/notifications/delivery-log/stats?date_from=2026-03-01&date_to=2026-03-08" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Query Parameters:

Response:

{
  "sent": 120,
  "failed": 3,
  "pending": 2,
  "skipped": 12
}

Available Event Types

List the notification event registry for the tenant.

curl "https://apps.aurionai.net/api/v2/notifications/events?category=agent" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Query Parameters:

Response:

[
  {
    "id": "evt_abc123",
    "event_key": "ticket_assigned",
    "category": "agent",
    "label_i18n_key": "notifications.events.ticket_assigned",
    "description": "A ticket is assigned to you",
    "default_enabled": true,
    "plan_gate": null,
    "sort_order": 10,
    "is_system": true,
    "is_transactional": false
  }
]

Toggle Event Enabled/Disabled

Enable or disable a notification event type for the tenant. Admin-only. Transactional events cannot be disabled.

curl -X PATCH "https://apps.aurionai.net/api/v2/notifications/events/ticket_assigned" \
  -H "X-API-Key: itsm_sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false
  }'

Response:

{
  "event_key": "ticket_assigned",
  "enabled": false
}

An unknown event_key returns 404 with {"detail": "Event not found"}. Attempting to disable a transactional event returns 422 with {"detail": "Transactional events cannot be disabled"}.

Create Notification

Admin-only (super_admin, tenant_owner, tenant_admin). Enqueues an in-app notification for a specific user.

curl -X POST "https://apps.aurionai.net/api/v2/notifications" \
  -H "X-API-Key: itsm_sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "usr_123",
    "event_type": "ticket_assigned",
    "title": "New ticket assigned to you",
    "body": "Ticket #1042: VPN not connecting",
    "entity_type": "ticket",
    "entity_id": "1042"
  }'

Returns 201 Created with the created NotificationModel. A user_id that does not reference a valid user returns 422.

Notification Webhooks & Templates

Outbound delivery webhooks and email templates are managed by sibling routers:

• Notification webhooks — /api/v2/notification-webhooks (CRUD plus POST /api/v2/notification-webhooks/{id}/test).
• Notification templates — /api/v2/notification-templates.

Both surfaces are dashboard-session (JWT) only, like the rest of this page, and are not reachable with an API key.

Email Unsubscribe (internal)

Each notification email includes a one-click unsubscribe link handled by GET /api/v2/notifications/unsubscribe?token=.... This route is unauthenticated and exists solely for email clients — it is hidden from the OpenAPI schema and is not part of the integration API.

Related Guides

• Teams & Routing — Team notifications and routing
• SLA Management — SLA breach notifications
• CSAT Surveys — CSAT response notifications