In-App Notifications API

The In-App 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) and a workspace role — Member, Manager, or Admin. Every response is scoped to the token's owner — you cannot retrieve another user's notifications.

Include the token in the Authorization header:

Authorization: Bearer YOUR_QUALYTICS_API_TOKEN

For instructions on generating a token, see Tokens.

---

List Notifications (Paginated)

Returns your notifications sorted by creation date, with the most recent first. Supports filtering by flow trigger type, by tag, and including notifications you've already marked as read.

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?include_acknowledged=false&sort_created=desc" \
  -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN"

Response (200 OK):

{
  "items": [
    {
      "id": 42,
      "created": "2026-05-13T12:00:00Z",
      "acknowledged": false,
      "notification": {
        "id": 100,
        "created": "2026-05-13T12:00:00Z",
        "notification_type": "flow",
        "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
include_acknowledged	boolean	No	Defaults to false. Set to true to include notifications you've already marked as read.
trigger_type	array	No	Filter by flow trigger type. Supported values: Anomaly, PartitionScan, Operation, Manual. Only applies to flow-based notifications.
tag	array	No	Filter by tag name(s).
sort_created	string	No	Sort order by creation date — desc (default) or asc.

---

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?include_acknowledged=false" \
  -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN"

Response (200 OK):

[
  {
    "id": 42,
    "created": "2026-05-13T12:00:00Z",
    "acknowledged": false,
    "notification": {
      "id": 100,
      "created": "2026-05-13T12:00:00Z",
      "notification_type": "flow",
      "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
include_acknowledged	boolean	No	Defaults to false. Set to true to include notifications you've already marked as read.

---

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):

{
  "id": 42,
  "created": "2026-05-13T12:00:00Z",
  "acknowledged": false,
  "notification": {
    "id": 100,
    "created": "2026-05-13T12:00:00Z",
    "notification_type": "flow",
    "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 for the authenticated user.

---

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 — 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 — 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.

---

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.