Freshness Check API¶

This page documents how to create and manage a Freshness check via the REST API. The check uses the standard Quality Checks endpoints: set rule to freshness and set the Maximum Age under properties. The rule reads the container itself, so fields is not used. All endpoints share the base URL of your deployment (for example, https://your-instance.qualytics.io/api) and require a Bearer token.

The properties object¶

Freshness carries its rule-specific configuration under properties:

Create¶

Endpoint: POST /api/quality-checks

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

curl -X POST "https://your-instance.qualytics.io/api/quality-checks" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
      "description": "customers_snapshot is refreshed at least every 6 hours.",
      "rule": "freshness",
      "fields": [],
      "container_id": 311,
      "filter": null,
      "properties": {"value": 21600000},
      "tags": ["crm", "sla"],
      "additional_metadata": {"runbook": "https://wiki.example.com/crm-extract"},
      "template_id": null,
      "status": "Active",
      "owner_id": 7,
      "default_anomaly_assignee_id": 18
  }'

Field notes¶

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

• coverage is not supported. The rule reads the container's last modification time, not its rows, so there is no per-row violation rate. Any value other than 1 is rejected with 422.
• anomaly_message_field is ignored. Freshness 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.

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

The response's inferred field is true for an AI Managed check. Its last_asserted field is empty until a Scan has asserted the check.

Update¶

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

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

Every PUT requires description and the full properties object with its value. Repeat the check's current properties even when changing only its description, tags, or other metadata: a request without them returns 422.

curl -X PUT "https://your-instance.qualytics.io/api/quality-checks/101" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "customers_snapshot is refreshed at least every 8 hours.",
    "properties": {"value": 28800000}
  }'

A PUT can update most fields on an existing Freshness check. Three values stay immutable: the rule type, the container the check is attached to, and template_id. Updating properties.value on an AI Managed check sets inferred to false, which stops automatic updates.

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:

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

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

Error responses¶