# Data Diff Check API

Source: https://userguide.qualytics.io/data-quality-checks/data-diff/api/

This page documents how to create and manage a Data Diff check via the REST API. The check uses the standard Quality Checks endpoints: set `rule` to `dataDiff`, list the compared fields under `fields`, and configure the reference container and matching behavior under `properties`. All endpoints share the base URL of your deployment (for example, `https://your-instance.qualytics.io/api`) and require a Bearer token.

> **Tip**
>
> For complete API documentation, including request and response schemas, visit the [API docs](https://userguide.qualytics.io/api/docs).

> **Note: Permissions**
>
> All endpoints require the **Member** role plus a team permission on the check's datastore: **Reporter** to read, **Author** to create or update an Active check, archive, or delete, and **Drafter** to create or update a Draft. See [Permissions](https://userguide.qualytics.io/data-quality-checks/data-diff/deep-dive/permissions/) for the full matrix.

## The `properties` object

Data Diff carries the reference target and the matching behavior under `properties`:

| Field | Required | Type | Description |
| --- | --- | --- | --- |
| `ref_datastore_id` | No | `int` | Datastore holding the reference container. Omit or send `null` when it lives in the same datastore as the target. |
| `ref_container_id` | Yes | `int` | The reference container (table, view, or file) compared against the target. |
| `ref_filter` | No | `string` | SQL `WHERE` expression applied to the reference container before the comparison. Accepts Check Variables. |
| `id_field_names` | No | `array` | Field names forming the key that pairs target rows with reference rows. Required to produce `changed` diffs and to enable the Comparison Source Records view. Omit (or send `[]`) to fall back to a set difference that produces only `added` and `removed`. |
| `passthrough_field_names` | No | `array` | Extra field names carried into the comparison output for context. They are displayed but never compared, so they never cause an anomaly. |
| `diff_change_types` | No | `array` | Subset of `["added", "removed", "changed"]` that restricts which statuses produce an anomaly. Defaults to all three. An empty list is rejected; at least one status must be selected. Requires `id_field_names`. See [Restricting Anomalies by Status](https://userguide.qualytics.io/data-quality-checks/data-diff/deep-dive/how-it-works/#restricting-anomalies-by-status). |
| `numeric_comparator` | No | `object` | Tolerance applied when comparing numeric fields. See [Comparators](https://userguide.qualytics.io/data-quality-checks/data-diff/deep-dive/how-it-works/#comparators). |
| `duration_comparator` | No | `object` | Tolerance applied when comparing date and timestamp fields. See [Comparators](https://userguide.qualytics.io/data-quality-checks/data-diff/deep-dive/how-it-works/#comparators). |
| `string_comparator` | No | `object` | Normalization applied when comparing string fields. See [Comparators](https://userguide.qualytics.io/data-quality-checks/data-diff/deep-dive/how-it-works/#comparators). |

## Create

**Endpoint:** `POST /api/quality-checks`

**Permission:** Member role + **Author** team permission on the container's datastore (**Drafter** when `status` is `"Draft"`).

> **Example: Create a Data Diff check (every accepted field)**
>
> ```bash
> curl -X POST "https://your-instance.qualytics.io/api/quality-checks" \
>   -H "Authorization: Bearer YOUR_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "description": "Ensure NATION matches NATION_BACKUP on N_NATIONKEY and N_NATIONNAME",
>     "rule": "dataDiff",
>     "fields": ["N_NATIONKEY", "N_NATIONNAME"],
>     "container_id": 145,
>     "filter": null,
>     "properties": {
>         "ref_datastore_id": 22,
>         "ref_container_id": 803,
>         "id_field_names": ["N_NATIONKEY"],
>         "passthrough_field_names": [],
>         "diff_change_types": ["added", "changed"]
>     },
>     "tags": ["replication"],
>     "additional_metadata": {"jira": "DATA-1234"},
>     "template_id": null,
>     "status": "Active",
>     "owner_id": 7,
>     "default_anomaly_assignee_id": 12
>   }'
> ```
>
> This payload sets `diff_change_types` to `["added", "changed"]` so unmatched reference rows, which arrive as `removed`, are not reported, a typical choice when the reference is a superset of the target (such as a long-lived backup).

### Field notes

| Field | Required | Notes |
| --- | --- | --- |
| `description` | Yes | Free-text description shown in the UI. |
| `rule` | Yes | Must be `"dataDiff"`. |
| `fields` | Yes | Array of field names compared between target and reference. Order does not affect evaluation. Every field must exist on both containers. |
| `container_id` | Yes | ID of the target container (the dataset the check runs on). |
| `filter` | No | SQL `WHERE` expression applied to the **target** container before matching. Send `null` for no filter. Scope the reference side with `properties.ref_filter`. |
| `properties` | Yes | Object holding the reference target and matching behavior. See [above](https://userguide.qualytics.io/data-quality-checks/data-diff/api/#the-properties-object). |
| `tags` | No | List of tag names applied to the check for filtering and organization. |
| `additional_metadata` | No | Free-form key-value pairs (typically links to catalog entries, tickets, governance records). |
| `template_id` | No | ID of a Check Template to associate the check with. `null` if not using a template. |
| `status` | No | `"Active"` (default) or `"Draft"`. Draft checks are not evaluated by Scans. |
| `owner_id` | No | ID of the user who owns the check. Defaults to the user creating the check when omitted. |
| `default_anomaly_assignee_id` | No | ID of the user automatically assigned to anomalies produced by the check. When omitted, anomalies are created unassigned. |

Two payload fields exist for other rule types but do not apply here:

- Omit `coverage` or send `1`. Data Diff reports any difference that a Comparator does not tolerate, so there is no per-row violation rate to set.
- `anomaly_message_field` is ignored. Data Diff emits a Shape Anomaly only, and Shape Anomalies always use the fixed message.

## Read

**Endpoint:** `GET /api/quality-checks/{id}`

**Permission:** Member role + **Reporter** team permission on the check's datastore.

> **Example: Retrieve a check by ID**
>
> ```bash
> curl -X GET "https://your-instance.qualytics.io/api/quality-checks/101" \
>   -H "Authorization: Bearer YOUR_TOKEN"
> ```

## Update

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

**Permission:** Member role + **Author** team permission on the check's datastore (**Drafter** when the check stays Draft).

The `PUT` endpoint requires `description` and `properties`, plus `fields` unless the request also sends `"status": "Draft"` (this also makes the check a Draft; a Draft update that omits `fields` keeps the stored ones). Include the check's current description (or a new one) and its compared fields (or the new list), along with anything else you want to change. Send the whole `properties` object: partial property updates are not merged.

> **Example: Narrow the reported change types**
>
> ```bash
> 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 NATION matches NATION_BACKUP on N_NATIONKEY and N_NATIONNAME",
>     "fields": ["N_NATIONKEY", "N_NATIONNAME"],
>     "properties": {
>         "ref_datastore_id": 22,
>         "ref_container_id": 803,
>         "id_field_names": ["N_NATIONKEY"],
>         "passthrough_field_names": [],
>         "diff_change_types": ["changed"]
>     }
>   }'
> ```

A `PUT` can update most fields on an existing Data Diff check. Three values stay immutable: the rule type, the target container the check is attached to, and the associated Check Template. If any of these needs to change, delete the check and create a new one. The reference container is not immutable: it is part of `properties` and can be repointed.

> **Info: Editable vs Immutable on PUT**
>
> **Editable**
>
> - `description`
> - `fields` (the compared fields)
> - `filter`
> - `properties.ref_datastore_id`
> - `properties.ref_container_id`
> - `properties.ref_filter`
> - `properties.id_field_names`
> - `properties.passthrough_field_names`
> - `properties.diff_change_types`
> - `properties.numeric_comparator`
> - `properties.duration_comparator`
> - `properties.string_comparator`
> - `tags`
> - `additional_metadata`
> - `status`
> - `owner_id`
> - `default_anomaly_assignee_id`
>
> **Immutable**
>
> - `rule`
> - `container_id`
> - `template_id`

## Delete

**Endpoint:** `DELETE /api/quality-checks/{id}`

**Permission:** Member role + **Author** team permission on the check's datastore.

Three query parameters control what happens, mirroring the two-stage flow in the UI:

| Parameter | Default | Description |
| --- | --- | --- |
| `archive` | `true` | When `true`, the check is archived and can be restored later. When `false`, the check is permanently deleted. |
| `status` | `Discarded` | The archive resolution: `Discarded` (no longer relevant) or `Invalid` (wrong and suppressed from future AI generation). Only used when `archive=true`. |
| `delete_anomalies` | `true` | Whether to permanently delete the anomalies the check produced. A permanent delete (`archive=false`) always removes them. |

> **Example: Archive a check, keeping its anomalies**
>
> ```bash
> curl -X DELETE "https://your-instance.qualytics.io/api/quality-checks/101?archive=true&status=Discarded&delete_anomalies=false" \
>   -H "Authorization: Bearer YOUR_TOKEN"
> ```

> **Example: Delete a check permanently**
>
> ```bash
> curl -X DELETE "https://your-instance.qualytics.io/api/quality-checks/101?archive=false" \
>   -H "Authorization: Bearer YOUR_TOKEN"
> ```

## Error responses

| Status | Description |
| --- | --- |
| `400 Bad Request` | A business-logic conflict prevents the operation (for example, changing properties while the check is archived, or switching an archived check between `Discarded` and `Invalid`). |
| `401 Unauthorized` | Missing or invalid API token. |
| `403 Forbidden` | The caller lacks the required team permission on the check's datastore, or on the reference container's datastore. |
| `404 Not Found` | The check ID, the reference datastore, or the reference container does not exist. |
| `422 Unprocessable Entity` | The payload fails schema validation (for example, `description` or `fields` missing on `PUT`, an empty `diff_change_types` list, or a field that does not exist on one of the containers). |

*Last updated: November 10, 2026.*
