Checks API¶

This page documents the endpoints that apply to every check regardless of its rule type: the change log of a check, its definition at a point in time, and the daily assertion history behind its Insights section. Create, read, update, and delete payloads are rule-specific and live on each rule type's API page (see Getting Started with Checks). The optional impact_metrics field of those payloads is described in Impact Metrics in the API.

All endpoints use the base URL of your Qualytics deployment (for example, https://your-instance.qualytics.io/api) and require a Bearer token. Every timestamp is returned in UTC as ISO 8601 with a trailing Z; see Timestamps.

History¶

Returns the paginated change log of a check: one entry per saved version, with the fields that changed, their before and after values, the user who made the change, and when. Use it to reconstruct every state a check has been in.

Endpoint: GET /api/quality-checks/{id}/history

Query parameters:

curl -X GET "https://your-instance.qualytics.io/api/quality-checks/778/history?page=1&size=50" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "items": [
    {
      "changeset": {
        "filter": ["order_date >= '2026-01-01'", "order_date >= '2026-06-01'"],
        "description": ["Orders must reference a customer", "Orders must reference an active customer"]
      },
      "transaction": {
        "id": 9876,
        "issued_at": "2026-06-02T13:40:11Z",
        "user": { "id": 42, "name": "Alice Lee" }
      },
      "operation": "update"
    },
    {
      "changeset": {
        "fields": [null, ["customer_id"]],
        "status": [null, "Active"]
      },
      "transaction": {
        "id": 8120,
        "issued_at": "2026-01-15T09:02:47Z",
        "user": { "id": 42, "name": "Alice Lee" }
      },
      "operation": "insert"
    }
  ],
  "total": 2,
  "page": 1,
  "size": 50,
  "pages": 1
}

Each field inside items[].changeset is a [before, after] pair. The transaction object carries the change id, the issued_at timestamp, and the user who saved it. The operation field reports whether the entry is an insert, update, or delete. To load successive windows, increment page until it reaches pages.

Version at a Point in Time¶

Returns the full check definition as it stood at a given instant. Pass the start_time of a scan (from GET /api/operations/{id} or GET /api/container-scans/{id}) to retrieve the exact definition that scan evaluated, even if the check has been edited since.

Endpoint: GET /api/quality-checks/{id}/version?version_at={UTC timestamp}

Query parameters:

curl -X GET "https://your-instance.qualytics.io/api/quality-checks/778/version?version_at=2026-05-15T02:00:00Z" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "id": 778,
  "rule_type": "notNull",
  "description": "Orders must reference a customer",
  "filter": "order_date >= '2026-01-01'",
  "coverage": 1.0,
  "status": "Active",
  "fields": [{ "id": 3101, "name": "customer_id" }],
  "container": { "id": 235, "name": "orders" },
  "datastore": { "id": 101, "name": "Sales" },
  "created": "2026-01-15T09:02:47Z",
  "last_asserted": "2026-06-02T02:00:04Z"
}

The response has the same shape as GET /api/quality-checks/{id}, so any client that already reads a check can read a historical version. Deleted checks can be resolved as well.

The returned importance_level is the importance the check had at version_at, so a version requested before an importance change shows the earlier level.

Insights¶

Returns the daily assertion history behind the Insights section of a check: for each day in the window, the result of the latest evaluation, the scan that produced it, and the asserted and anomalous record counts. This is the API equivalent of the pass/fail timeline in the UI and distinguishes checks that could not be evaluated from checks that passed.

Endpoint: GET /api/quality-checks/{id}/insights

Query parameters:

curl -X GET "https://your-instance.qualytics.io/api/quality-checks/778/insights?report_date=2026-06-07&timeframe=week" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "generated_at": "2026-06-07T18:21:03Z",
  "start_date": "2026-06-01",
  "end_date": "2026-06-07",
  "timeframe": "week",
  "daily_assertion_measured": [
    {
      "date": "2026-06-01",
      "latest_scan_id": 12345,
      "latest_container_scan_id": 456,
      "latest_container_scan_start_time": "2026-06-01T02:00:00Z",
      "latest_partition_scan_id": 9001,
      "latest_assertion_result": "passed",
      "latest_asserted_records": 120000,
      "latest_anomalous_records": 0,
      "total_scans": 1,
      "total_asserted_records": 120000,
      "total_anomalous_records": 0
    },
    {
      "date": "2026-06-02",
      "latest_scan_id": 12360,
      "latest_container_scan_id": 471,
      "latest_container_scan_start_time": "2026-06-02T02:00:00Z",
      "latest_partition_scan_id": 9017,
      "latest_assertion_result": "failed",
      "latest_asserted_records": 121500,
      "latest_anomalous_records": 37,
      "total_scans": 2,
      "total_asserted_records": 243000,
      "total_anomalous_records": 37
    }
  ]
}

Daily metric fields:

Timestamp fields¶

Ownership¶

Ownership is exposed on the standard quality check endpoints, with no dedicated route, through an owner_id field on create and update and an owner object on reads. For how ownership behaves, see Check Ownership.

The owner_id field¶

Every quality check carries a single owner. The API exposes it as owner_id on writes and as a nested owner object on reads.

{
  "id": 101,
  "rule_type": "unique",
  "inferred": false,
  "owner": {
    "id": 42,
    "name": "Alice Lee",
    "email": "alice@example.com"
  }
}

Create¶

Create a check with an explicit owner¶

Endpoint: POST /api/quality-checks

Permission: Member role + Author team permission on the container's datastore, or Drafter to create the check as a Draft. The target owner_id must have Drafter on the same datastore.

Include owner_id in the create payload to set an explicit owner. Omit the field to let the platform default to the caller.

curl -X POST "https://your-instance.qualytics.io/api/quality-checks" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Ensure C_NAME is unique in the CUSTOMER table",
    "rule": "unique",
    "fields": ["C_NAME"],
    "container_id": 145,
    "owner_id": 42
  }'

Update¶

Transfer ownership on a single check¶

Endpoint: PUT /api/quality-checks/{id}

Permission: Member role + Author team permission on the check's datastore, or Drafter when the check is a Draft and the request does not change its status. The target owner_id must have Drafter on the same datastore.

Send owner_id set to the new owner's user ID. The previous owner is recorded in the check's history.

A PUT replaces the check's assertion, so send the current description and properties from GET /api/quality-checks/{id}, an array of each returned field's name as fields, and the new owner_id. For an owner-only change, the bulk update is simpler because it needs only id and owner_id.

curl -X PUT "https://your-instance.qualytics.io/api/quality-checks/101" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Ensure C_NAME is unique in the CUSTOMER table",
    "fields": ["C_NAME"],
    "properties": null,
    "owner_id": 42
  }'

Transfer ownership across many checks¶

Endpoint: PATCH /api/quality-checks

Permission: Member role + Author team permission on the datastore of every check in the request (Drafter is enough for checks that are Drafts and stay Drafts). The target owner_id must have Drafter on each of those datastores.

Send a list of { id, owner_id } entries; the same owner_id can be reused across entries to apply one owner to many checks. The same endpoint also takes the other bulk fields, such as tags and additional_metadata, with tags_mode and additional_metadata_mode set to replace (the default) or add; owner_id always replaces the current owner.

curl -X PATCH "https://your-instance.qualytics.io/api/quality-checks" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    { "id": 101, "owner_id": 42 },
    { "id": 102, "owner_id": 42 },
    { "id": 103, "owner_id": 42 }
  ]'

Filter¶

Filter checks by a specific owner¶

Endpoint: GET /api/quality-checks

Permission: Member role. Results are scoped to datastores the caller can see.

Use the owner_id query parameter to narrow the list to checks owned by a specific user. Combine with the other list filters (status, tags, rule type, and so on) to scope further.

curl -X GET "https://your-instance.qualytics.io/api/quality-checks?owner_id=42" \
  -H "Authorization: Bearer YOUR_TOKEN"

List checks owned by the current user¶

Endpoint: GET /api/quality-checks

Permission: Member role.

Pass owner_id with a user's ID to list the checks that user owns. The Owned subtab sends your own user ID, which GET /api/users/me returns as id, together with the datastore and the status of the tab you are on.

curl -X GET "https://your-instance.qualytics.io/api/quality-checks?owner_id=42&datastore=7&status=Active" \
  -H "Authorization: Bearer YOUR_TOKEN"

Error responses¶

AI Managed¶

AI Managed checks use the same endpoints as every other check. For how they behave, see AI Managed Checks.

Telling AI Managed and Authored Checks Apart¶

Every check returned by the API includes an inferred boolean. When true, Qualytics AI manages the check; when false, the check is Authored and Profile runs leave it alone.

curl -X GET "https://your-instance.qualytics.io/api/quality-checks?inferred=true" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
  "items": [
    {
      "id": 101,
      "rule_type": "between",
      "inferred": true,
      "coverage": 1.0,
      "filter": null,
      "fields": [{ "id": 5001, "name": "price" }],
      "properties": { "min": 0, "inclusive_min": true, "max": 10000, "inclusive_max": true }
    }
  ]
}

Editing an AI Managed Check¶

To edit an AI Managed check, send a PUT /api/quality-checks/{id} request with the check's whole definition. description is always required. fields is required unless the request keeps the check in Draft, and properties is required for rule types that have required properties (such as Between or Expected Values), sent in full because it replaces the stored one. Resend their current values along with the change. Whether the check stays AI Managed depends on which values the request changes, not on which fields it includes.

Permission: Drafter or above while the check stays in Draft. Author or above on an Active check, or for any status change other than restoring an archived check to Draft.

Edits that convert the check to Authored¶

Changing the value of any of the following fields flips inferred from true to false on save. Resending a field with its current value does not convert the check.

curl -X PUT "https://your-instance.qualytics.io/api/quality-checks/101" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "price stays between 0 and 10000",
    "fields": ["price"],
    "properties": { "min": 0, "inclusive_min": true, "max": 10000, "inclusive_max": true },
    "coverage": 0.995
  }'

Edits that keep the check AI Managed¶

Changing only the following fields saves the change without converting the check, as long as the other values are resent unchanged:

curl -X PUT "https://your-instance.qualytics.io/api/quality-checks/101" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "price stays between 0 and 10000",
    "fields": ["price"],
    "properties": { "min": 0, "inclusive_min": true, "max": 10000, "inclusive_max": true },
    "tags": ["critical", "ops-reviewed"]
  }'

Deleting an AI Managed Check¶

Send DELETE /api/quality-checks/{id} to remove the check. Deleting an AI Managed check does not stop Qualytics from re-creating an equivalent check during the next Profile run if the data still suggests the rule.

Permission: Author or above.

Error Responses¶