Not Negative Check API

This page documents how to create and manage a Not Negative check via the REST API. The check uses the standard Quality Checks endpoints: set rule to notNegative and list exactly one numeric field under fields. The rule has no rule-specific 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.

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 for the full matrix.

Create

Endpoint: POST /api/quality-checks

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

Create a Not Negative check (every accepted field)

curl -X POST "https://your-instance.qualytics.io/api/quality-checks" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
      "description": "Account balance must not be negative.",
      "rule": "notNegative",
      "fields": ["balance"],
      "container_id": 145,
      "coverage": 1,
      "filter": null,
      "properties": {},
      "tags": ["finance", "range"],
      "additional_metadata": {"jira": "DATA-8301"},
      "anomaly_message_field": null,
      "template_id": null,
      "status": "Active",
      "owner_id": 7,
      "default_anomaly_assignee_id": 12
  }'

Field notes

Field	Required	Notes
`description`	Yes	Free-text description shown in the UI.
`rule`	Yes	Must be `"notNegative"`.
`fields`	Yes	Array with exactly one entry. Must reference a numeric field, or an array of numbers.
`container_id`	Yes	ID of the container (table or file) the check runs against.
`coverage`	No	Fractional value between `0` and `1` that defines the minimum fraction of evaluated rows that must pass. Defaults to `1`, which requires every row to pass.
`filter`	No	SQL `WHERE` expression. Applied before the evaluation, so only filtered rows are evaluated. Send `null` for no filter.
`properties`	No	Not Negative has no rule-specific properties. Send `{}` or omit.
`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).
`anomaly_message_field`	No	Name of a source-record field whose value should be used as the Record Anomaly message instead of the default template-generated one. When the named column is null, missing, or empty for a violating row, the standard Record template is used instead. Shape Anomalies always use the fixed template. Send `null` to use the default Record template.
`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.

Read

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

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

Retrieve a check by ID

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; include the check's current description (or a new one) along with the fields you want to change.

Point the check at another field

curl -X PUT "https://your-instance.qualytics.io/api/quality-checks/101" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Available balance must not be negative.",
    "fields": ["available_balance"]
  }'

A PUT can update most fields on an existing Not Negative check. Three values stay immutable: the rule type, the 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.

Editable vs Immutable on PUT

Editable

description
coverage
filter
tags
additional_metadata
anomaly_message_field
fields (must remain a single numeric field)
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.

Archive a check, keeping its anomalies

curl -X DELETE "https://your-instance.qualytics.io/api/quality-checks/101?archive=true&status=Discarded&delete_anomalies=false" \
  -H "Authorization: Bearer YOUR_TOKEN"

Delete a check permanently

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.
`404 Not Found`	The check ID does not exist, or `fields` references a column that is not on the container.
`422 Unprocessable Entity`	The payload fails schema validation (for example, `description` missing on `PUT`).