Notifications API

The Notifications API provides programmatic access to the same notifications that appear in the bell panel. Use these endpoints to integrate alerts into your own tooling, build custom dashboards, or automate marking notifications as read from scripts.

Complete API Reference

For the full interactive API documentation with all request/response schemas, visit the API docs.

All endpoints use the base URL of your Qualytics deployment (e.g., https://your-instance.qualytics.io/api).

Authentication

All endpoints require a Qualytics Personal API Token (PAT); any role (Member, Manager, or Admin) can call them. List, acknowledge, and unacknowledge requests are scoped to the token's owner, so they only ever touch your own notifications.

Include the token in the Authorization header:

Authorization: Bearer YOUR_QUALYTICS_API_TOKEN

For instructions on generating a token, see Tokens.

category and notification_type

Two fields describe what a notification is about. category is the notification's type as shown in the panel's colored label: mention, ownership, anomaly, assignment, operation, flow, or system, derived from what the notification refers to. notification_type records how the notification was produced, so the two can differ: in the examples below, a flow's in-app notification action (notification_type: "flow") reported a finished operation, which the panel presents under the Operation type (category: "operation").

List Notifications (Paginated)

Returns your notifications sorted by creation date, with the most recent first. Supports filtering by read status, by flow trigger type, and by tag.

Endpoint: GET /api/user-notifications

Permission: Member or above

Example request and response

Request:

curl -X GET "https://your-instance.qualytics.io/api/user-notifications?status=unread&sort_created=desc&size=12" \
  -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN"

Response (200 OK, abbreviated; nested objects carry more fields than shown):

{
  "items": [
    {
      "id": 42,
      "created": "2026-05-13T12:00:00Z",
      "acknowledged": false,
      "notification": {
        "id": 100,
        "created": "2026-05-13T12:00:00Z",
        "notification_type": "flow",
        "category": "operation",
        "title": "Scan completed • Healthcare Analytics",
        "message": "A Scan operation on Healthcare Analytics has completed.",
        "target_uri": "/datastores/101/activity?operation_id=50001",
        "target_url": "https://your-instance.qualytics.io/datastores/101/activity?operation_id=50001",
        "action_execution": {
          "id": 200,
          "flow_execution": {
            "id": 300,
            "flow": { "id": 7, "name": "Healthcare Nightly Quality Gate" }
          }
        }
      }
    }
  ],
  "total": 1,
  "page": 1,
  "size": 12,
  "pages": 1
}

Query parameters:

Parameter	Type	Required	Description
`status`	string	No	Filter by read status. One of `unread` (default), `read`, or `all`.
`trigger_type`	array	No	Filter by flow trigger type. Supported values: `Anomaly`, `AnomalyStatusChange`, `PartitionScan`, `Operation`, `Schedule`, `Manual`. Only applies to flow-based notifications; mention notifications are always included in filtered results.
`tag`	array	No	Filter by tag name(s). Mention notifications are always included in filtered results.
`sort_created`	string	No	Sort order by creation date: `desc` (default) or `asc`.
`page`	integer	No	Page number, starting at `1`.
`size`	integer	No	Number of notifications per page.

List Notifications (Non-Paginated)

Returns the same data as the paginated endpoint but as a flat array, useful for small result sets where pagination is unnecessary.

Endpoint: GET /api/user-notifications/listing

Permission: Member or above

Example request and response

Request:

curl -X GET "https://your-instance.qualytics.io/api/user-notifications/listing?status=unread" \
  -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN"

Response (200 OK, abbreviated; nested objects carry more fields than shown):

[
  {
    "id": 42,
    "created": "2026-05-13T12:00:00Z",
    "acknowledged": false,
    "notification": {
      "id": 100,
      "created": "2026-05-13T12:00:00Z",
      "notification_type": "flow",
      "category": "operation",
      "title": "Scan completed • Healthcare Analytics",
      "message": "A Scan operation on Healthcare Analytics has completed.",
      "target_uri": "/datastores/101/activity?operation_id=50001",
      "target_url": "https://your-instance.qualytics.io/datastores/101/activity?operation_id=50001",
      "action_execution": {
        "id": 200,
        "flow_execution": {
          "id": 300,
          "flow": { "id": 7, "name": "Healthcare Nightly Quality Gate" }
        }
      }
    }
  }
]

Query parameters:

Parameter	Type	Required	Description
`status`	string	No	Filter by read status. One of `unread` (default), `read`, or `all`.

Get Single Notification

Retrieve the details of one notification by its ID.

Endpoint: GET /api/user-notifications/{id}

Permission: Member or above

Example request and response

Request:

curl -X GET "https://your-instance.qualytics.io/api/user-notifications/42" \
  -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN"

Response (200 OK, abbreviated; nested objects carry more fields than shown):

{
  "id": 42,
  "created": "2026-05-13T12:00:00Z",
  "acknowledged": false,
  "notification": {
    "id": 100,
    "created": "2026-05-13T12:00:00Z",
    "notification_type": "flow",
    "category": "operation",
    "title": "Scan completed • Healthcare Analytics",
    "message": "A Scan operation on Healthcare Analytics has completed.",
    "target_uri": "/datastores/101/activity?operation_id=50001",
    "target_url": "https://your-instance.qualytics.io/datastores/101/activity?operation_id=50001",
    "action_execution": {
      "id": 200,
      "flow_execution": {
        "id": 300,
        "flow": { "id": 7, "name": "Healthcare Nightly Quality Gate" }
      }
    }
  }
}

Path parameters:

Parameter	Type	Required	Description
`id`	integer	Yes	The unique ID of the notification.

Responses:

200 OK: Notification returned.
404 Not Found: No notification with that ID exists.

Bulk Mark as Read

Mark multiple notifications as read in a single request. Supply specific IDs to mark a subset as read, or pass an empty array [] to mark every unread notification as read.

Endpoint: PATCH /api/user-notifications/acknowledge

Permission: Member or above

Example request and response

Request to mark specific notifications as read:

curl -X PATCH "https://your-instance.qualytics.io/api/user-notifications/acknowledge" \
  -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[{"id": 42}, {"id": 43}]'

Request to mark all unread notifications as read:

curl -X PATCH "https://your-instance.qualytics.io/api/user-notifications/acknowledge" \
  -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[]'

Response (200 OK):

{
  "acknowledged_count": 2,
  "requested_count": 2
}

Request body: A JSON array of objects with the id field, or an empty array to mark all as read.

Field	Type	Required	Description
`id`	integer	Yes (per object)	The ID of a notification to mark as read.

Bulk Mark as Unread

Return multiple notifications to the unread list in a single request. Supply specific IDs to mark a subset as unread, or pass an empty array [] to mark every read notification as unread. In the panel, the same bulk action appears when you select notifications on the Read tab.

Endpoint: PATCH /api/user-notifications/unacknowledge

Permission: Member or above

Example request and response

Request to mark specific notifications as unread:

curl -X PATCH "https://your-instance.qualytics.io/api/user-notifications/unacknowledge" \
  -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[{"id": 42}, {"id": 43}]'

Response (200 OK):

{
  "unacknowledged_count": 2,
  "requested_count": 2
}

Request body: A JSON array of objects with the id field, or an empty array to mark all read notifications as unread.

Field	Type	Required	Description
`id`	integer	Yes (per object)	The ID of a notification to mark as unread.

Mark Single Notification as Read

Mark exactly one notification as read.

Endpoint: PUT /api/user-notifications/acknowledge/{id}

Permission: Member or above

Example request and response

Request:

curl -X PUT "https://your-instance.qualytics.io/api/user-notifications/acknowledge/42" \
  -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN"

Response (200 OK):

{
  "id": 42,
  "created": "2026-05-13T12:00:00Z",
  "acknowledged": true
}

Path parameters:

Parameter	Type	Required	Description
`id`	integer	Yes	The unique ID of the notification to mark as read.

Responses:

200 OK: Notification marked as read.
404 Not Found: No notification with that ID exists for the authenticated user.

Mark Single Notification as Unread

Return one notification to the unread list, reversing a previous mark as read.

Endpoint: PUT /api/user-notifications/unacknowledge/{id}

Permission: Member or above

Example request and response

Request:

curl -X PUT "https://your-instance.qualytics.io/api/user-notifications/unacknowledge/42" \
  -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN"

Response (200 OK):

{
  "id": 42,
  "created": "2026-05-13T12:00:00Z",
  "acknowledged": false
}

Path parameters:

Parameter	Type	Required	Description
`id`	integer	Yes	The unique ID of the notification to mark as unread.

Responses:

200 OK: Notification marked as unread.
404 Not Found: No notification with that ID exists for the authenticated user.