Max Length Check API

This page documents how to create and manage a Max Length check via the REST API. The check uses the standard Quality Checks endpoints: set rule to maxLength, list exactly one text field under fields, and provide the length 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.

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.

The `properties` object

Max Length carries its rule-specific configuration under properties:

Field	Required	Type	Description
`value`	Yes	`number`	The length the value is compared against, as a character count. The comparison is `<=`.
`is_element_context`	No	`boolean`	Set to `true` to measure each element of an array field instead of the array as a whole.

Create

Endpoint: POST /api/quality-checks

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

Create a Max Length 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": "Country code must be at most 2 characters.",
      "rule": "maxLength",
      "fields": ["country_code"],
      "container_id": 145,
      "coverage": 1,
      "filter": null,
      "properties": {"value": 2},
      "tags": ["reference", "format"],
      "additional_metadata": {"jira": "DATA-8601"},
      "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 `"maxLength"`.
`fields`	Yes	Array with exactly one entry. Must reference a text field, or an array of text values.
`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`	Yes	Object holding the length. See above.
`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 both description and the complete properties object on every request, even when you are only changing metadata such as tags or ownership. Max Length declares value as a required property, and the update path validates required properties before storing, so omitting properties is rejected with 422. Partial property updates are not merged either: send the whole object.

Change the length on an existing check

curl -X PUT "https://your-instance.qualytics.io/api/quality-checks/101" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Country code must be at most 3 characters.",
    "properties": {"value": 3}
  }'

A PUT can update most fields on an existing Max Length 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
properties.value (the length)
properties.is_element_context
tags
additional_metadata
anomaly_message_field
fields (must remain a single text 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.
`422 Unprocessable Entity`	The payload fails schema validation (for example, `description` missing on `PUT`, or `properties.value` is missing or is not a number).