Notifications

Overview

The Notifications API surfaces items that require human attention — pending action approvals and case reviews. Each notification carries a notification_key used to track read/unread state per user. All endpoints require authentication.

Get Pending Notifications

GET /api/v1/notifications/pending
Authorization: Bearer aira_live_xxxxx

Returns all pending notifications for the caller's organization, with read/unread state resolved per user (when authenticated via JWT).

Example Response

{
  "items": [
    {
      "id": "a1b2c3d4-...",
      "type": "action_approval",
      "notification_key": "action:a1b2c3d4-...",
      "title": "Action requires approval",
      "description": "transfer by agent-billing-bot",
      "href": "/dashboard/actions/a1b2c3d4-...",
      "created_at": "2026-06-04T14:22:00Z",
      "read": false
    },
    {
      "id": "e5f6g7h8-...",
      "type": "case_review",
      "notification_key": "case:e5f6g7h8-...",
      "title": "Case requires review",
      "description": "Consensus: reject \u2014 disagreement 0.45",
      "href": "/dashboard/cases/e5f6g7h8-...",
      "created_at": "2026-06-04T12:10:00Z",
      "read": true
    }
  ],
  "total": 2,
  "unread_count": 1,
  "request_id": "req_01J8X..."
}

Notification Item Fields

Field	Type	Description
`id`	string	UUID of the underlying resource (action or case)
`type`	string	Notification type: `action_approval` or `case_review`
`notification_key`	string	Unique key for read-state tracking (e.g. `action:{id}` or `case:{id}`)
`title`	string	Short human-readable title
`description`	string	Context about the notification
`href`	string	Dashboard path to the relevant resource
`created_at`	string\|null	When the underlying resource was created (ISO 8601 UTC)
`read`	boolean	Whether the current user has marked this notification as read

Response Fields

Field	Type	Description
`items`	array	List of notification items, sorted by `created_at` descending
`total`	integer	Total number of pending notifications
`unread_count`	integer	Number of unread notifications for the current user
`request_id`	string	Request tracking ID

Results are capped at 50 items per notification type (50 pending actions + 50 pending cases). Read state is only resolved when the request is authenticated via JWT (dashboard users). API-key-only requests see all items as read: false.

Mark Notifications as Read

POST /api/v1/notifications/mark-read
Authorization: Bearer aira_live_xxxxx
Content-Type: application/json

Mark specific notifications as read for the current user.

Request Body

{
  "notification_keys": [
    "action:a1b2c3d4-...",
    "case:e5f6g7h8-..."
  ]
}

Request Fields

Field	Type	Required	Description
`notification_keys`	array	Yes	List of notification keys to mark as read (1-100 items)

Example Response

{
  "marked": 2,
  "request_id": "req_01J8X..."
}

Response Fields

Field	Type	Description
`marked`	integer	Number of notifications newly marked as read (excludes already-read items)
`request_id`	string	Request tracking ID

This endpoint requires JWT authentication (dashboard user). If the request uses only an API key, marked returns 0.

Mark All Notifications as Read

POST /api/v1/notifications/mark-all-read
Authorization: Bearer aira_live_xxxxx

Mark all currently pending notifications as read for the current user. No request body is required.

Example Response

{
  "marked": 5,
  "request_id": "req_01J8X..."
}

Response Fields

Field	Type	Description
`marked`	integer	Number of notifications newly marked as read
`request_id`	string	Request tracking ID

Like mark-read, this endpoint requires JWT authentication. It gathers all current pending action approvals and case reviews for the organization and marks them read in one call.

Notifications

On this page