Ataccama ONE Agentic ONE Desktop ONE DQ&C ONE MDM ONE RDM ONE Runtime Server
Downloads

Manage DQ Monitors via API

The REST API is currently in Early Access Preview. The API specification and endpoints might change before being marked as stable.

We recommend testing thoroughly and being prepared to adapt to potential changes in future releases.

This guide shows you how to manage DQ monitors programmatically: create and configure monitors, retrieve their configuration, and publish changes. This enables you to automate DQ setup and promote configurations across environments.

Before using the Data Quality API, configure authentication as described in API Authentication.

When to use this API

Use the DQ monitors API when you need to:

  • Automate DQ setup: Create and configure monitors from scripts or CI/CD pipelines instead of in the web application.

  • Promote configurations across environments: Read monitor configuration from one environment and recreate it in another (for example, dev to prod).

  • Verify configuration before execution: Check which rules are applied, review schedule settings, or confirm profiling options before starting the processing.

  • Audit configurations for compliance: Document which DQ rules and monitors are configured for each dataset for regulatory or internal audits.

  • Build adaptive pipelines: Create automation that adjusts behavior based on monitor settings.

  • Debug evaluation behavior: Understand why DQ evaluation produces certain results by inspecting the full configuration.

Draft and publish lifecycle

DQ monitor changes made through the API follow a draft and publish lifecycle. Each draft has a draftType that indicates what publishing it does:

  • NEW: Creating a monitor produces a draft of a new monitor. Publishing promotes it to the first published version.

  • CHANGE: Updating a published monitor opens a draft on top of the latest published version. Publishing promotes the draft.

  • DELETE: The monitor is marked for deletion. Publishing deletes the monitor.

  • RESURRECT: A deleted monitor is marked for restoration. Publishing restores the monitor.

    DELETE and RESURRECT drafts are created in the web application only; the API never creates them, but you can retrieve them (?version=DRAFT) and publish them like any other draft. To delete a monitor through the API, use the delete operation instead: it deletes the monitor immediately, without a draft (see Delete a monitor).

After a monitor is published, it has no draft: only the published version exists, and responses report draftType: NONE. Publishing again returns the currently published version.

Monitor configuration fields

Create and update requests accept the following fields; retrieve requests return them. None of the fields is required to create a monitor draft; name is required to publish it. A draft without a name appears under its UUID in the web application.

Field Required Description

name

Yes (for publishing)

The name of the DQ monitor.

schedule

No

When the monitor runs: cron expression, time zone, and other scheduling options.

profilingConfiguration

No

Whether profiling is enabled, profiling type (full or sample), and sample limits.

anomalyDetectionConfiguration

No

Whether anomaly detection is enabled.

manualRuleInstances

No

Rule instances applied manually. Each rule instance references the rule it runs (ruleUrn) and contains the following sub-entity collections:

  • mappings: Maps rule input attributes (ruleAttributeUrn) to attributes of the monitor’s own catalog item (catalogItemAttributeUrn).

  • connectedMappings: Maps rule input attributes (ruleAttributeUrn) to attributes of joined catalog items (connectedCatalogItemAttributeUrn). Each connected mapping references the join it goes through (see joinConfigurations).

  • dqThresholds: Thresholds used to trigger alert findings for this rule instance.

  • parameterValues: Values assigned to the rule’s parameters; each entry references the parameter it sets (ruleParameterUrn).

Setting enabled: false on a rule instance pauses its DQ evaluation; the instance and its configuration stay on the monitor. The default is true.

invalidSamplesConfiguration

No

Whether invalid samples are enabled and the sample size limit.

exportDefinitions

No

Configured exports for invalid records.

joinConfigurations

No

Joins to other catalog items, defined by foreign-key attribute pairs and used to evaluate DQ rules across joined data (see Cross-Table Rules).

A join defines only the connection between the catalog items. The rule input attributes are then mapped onto attributes of the joined catalog item by the connected mappings of each rule instance in manualRuleInstances.

overallDqThresholds

No

Monitor-level thresholds used to trigger alert findings during processing.

The following fields are read-only and appear in responses only:

  • urn, catalogItemUrn, and draftType: Assigned automatically. On a published version, draftType is NONE.

  • termRuleInstances: Rule instances applied through glossary terms, as opposed to the manually applied instances in manualRuleInstances. They exist only on the catalog item’s primary DQ monitor.

    Term rule instances cannot be created or modified through this API. To manage them, link rules to terms in the web application. Then assign those terms to attributes, either in the web application or through the Catalog API (POST /catalog/v1/attributes/term-assignments/batch/assign).

How to identify monitor sub-entities

A monitor configuration consists of fields, listed in the preceding table, and sub-entities inside some of them: the rule instances (with their mappings, connected mappings, thresholds, and parameter values), export definitions, join configurations (with their foreign-key pairs), and overall DQ thresholds. In the response example in Retrieve a monitor, manualRuleInstances is a field, and the objects under the {ruleInstanceId} keys are its sub-entities.

Because a monitor can contain any number of sub-entities, each of them is identified by its own ID. This way, requests can address each sub-entity separately and leave the rest of the monitor unchanged.

The ID of a sub-entity is a UUID assigned when the sub-entity is created and has the following properties:

  • In responses, it appears as the key under which the sub-entity is stored, shown as {ruleInstanceId} in the response example in Retrieve a monitor. To find the IDs of existing sub-entities, retrieve the monitor.

  • For sub-entities that have a URN, the ID matches the UUID part of the URN.

New sub-entities have no ID yet, so you need to name each new sub-entity yourself with a temporary key, such as new_email-rule. You can choose any temporary key that follows these rules:

  • It starts with new_. The prefix is what marks the sub-entity as new.

  • It continues with letters, digits, underscores (_), and hyphens (-), up to 36 characters. This part only helps you recognize the sub-entity in the response.

  • It is different for each new sub-entity in the request.

Which identifier you use depends on the request:

  • When creating a monitor, use temporary keys to address sub-entities, since every sub-entity is new (see Create a monitor).

  • When updating a monitor, use IDs to address existing sub-entities and temporary keys for new sub-entities. One request can combine both (see Update a monitor).

In either case, the response returns each new sub-entity under its assigned ID, with your temporary key in the correlationId field:

Response: A new rule instance under its assigned ID (trimmed)
{
  "manualRuleInstances": {
    "3c2b1a90-...": {
      "ruleInstanceName": "Email Format Valid",
      "correlationId": "new_email-rule"
    }
  }
}

The temporary key appears only in this one response. Later retrievals return the sub-entity without correlationId.

List monitors

List the DQ monitors in your environment. The endpoint returns the latest published version of each monitor.

By default, monitors of all catalog items are returned. To list the monitors of a single catalog item, use the catalogItemUrn parameter.

Request: List the DQ monitors of a catalog item
curl -X GET "https://{your-environment}.ataccama.one/api/data-quality/v1/dq-monitors?catalogItemUrn={catalogItemUrn}&size=20" \
  -H "Authorization: Bearer {access_token}"
Query parameters
Parameter Type Required Description

catalogItemUrn

string

No

Restricts the result to DQ monitors of the given catalog item. Omit to list monitors across all catalog items.

size

integer

No

Number of monitors to return per page.

Default: 20.

Max: 100.

sort

string

No

Comma-separated field names for sorting (for example, name,-createdAt). Prefix with a hyphen (-) for descending order.

after

string

No

Cursor for forward pagination. Use the value from meta.next in the previous response.

The response contains a data array with up to size monitors, and a meta object with the pagination information:

  • meta.next: Cursor for retrieving the next batch of monitors; pass it as the after parameter in the next request. Omitted when there are no more monitors to retrieve.

  • meta.total: Total number of monitors, across all pages.

The listing is not isolated from concurrent changes. If monitors are created or deleted between page requests, some monitors might be missing from the results.

Create a monitor

Create a new DQ monitor for a catalog item. The monitor is created as a draft (draftType: NEW); publish it to make it live. See Draft and publish lifecycle.

The request body accepts the fields described in Monitor configuration fields. If you send the read-only fields urn, catalogItemUrn, and draftType, they are ignored:

  • urn and draftType: The URN is assigned automatically and draftType is set to NEW.

  • catalogItemUrn: The catalog item is taken from the request path.

Request: Create a DQ monitor with a schedule, profiling, and anomaly detection
curl -X POST "https://{your-environment}.ataccama.one/api/data-quality/v1/catalog-items/{catalogItemUrn}/dq-monitors" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekly Full Profile",
    "schedule": {
      "cronExpression": "0 0 6 ? * MON",
      "enabled": true,
      "ignoreMisfires": false,
      "timeZone": "Europe/Prague"
    },
    "profilingConfiguration": {
      "enabled": true,
      "type": "FULL"
    },
    "anomalyDetectionConfiguration": {
      "enabled": true
    }
  }'

A successful request returns 201 Created with the created monitor draft.

Retrieve a monitor

Get the full configuration for a specific DQ monitor. By default, the endpoint returns the latest published version. To retrieve the current draft instead, add ?version=DRAFT.

To retrieve the catalog item’s primary monitor without looking up its URN, use primary as the dqMonitorUrn.
Request: Retrieve a DQ monitor
curl -X GET "https://{your-environment}.ataccama.one/api/data-quality/v1/catalog-items/{catalogItemUrn}/dq-monitors/{dqMonitorUrn}" \
  -H "Authorization: Bearer {access_token}"
Query parameters
Parameter Type Required Description

version

string

No

Which version of the DQ monitor to retrieve: PUBLISHED or DRAFT.

If the monitor has no current draft, a DRAFT request returns 404 Not Found.

Default: PUBLISHED.
Response: The published DQ monitor
{
  "urn": "urn:ata:{your-tenant}:data-quality:dq-monitor:123e4567-e89b-12d3-a456-426614174000",
  "name": "Primary Monitor",
  "catalogItemUrn": "urn:ata:{your-tenant}:catalog:catalog-item:456e4567-e89b-12d3-a456-426614174000",
  "draftType": "NONE",
  "schedule": {
    "cronExpression": "0 0 6 * * ?",
    "enabled": true,
    "ignoreMisfires": false,
    "timeZone": "Europe/Prague",
    "startAt": "2026-01-01T00:00:00Z",
    "nextRun": "2026-02-18T06:00:00Z",
    "priority": 5
  },
  "profilingConfiguration": {
    "enabled": true,
    "type": "FULL",
    "sampleLimitCount": 10000
  },
  "anomalyDetectionConfiguration": {
    "enabled": true
  },
  "invalidSamplesConfiguration": {
    "enabled": true,
    "sampleSize": 1000
  },
  "manualRuleInstances": {
    "{ruleInstanceId}": {
      "ruleInstanceUrn": "urn:ata:{your-tenant}:data-quality:rule-instance:{ruleInstanceId}",
      "ruleUrn": "urn:ata:{your-tenant}:data-quality:rule:...",
      "ruleInstanceName": "Email Format Valid",
      "ruleName": "Email Format Validation",
      "enabled": true,
      "dqThresholds": {
        "{dqThresholdId}": {
          "urn": "urn:ata:{your-tenant}:data-quality:dq-threshold:{dqThresholdId}",
          "value": 80,
          "severity": "WARNING"
        }
      },
      "mappings": {
        "{mappingId}": {
          "catalogItemAttributeUrn": "urn:ata:{your-tenant}:catalog:catalog-attribute:...",
          "ruleAttributeUrn": "urn:ata:{your-tenant}:data-quality:rule-attribute:..."
        }
      },
      "connectedMappings": {},
      "parameterValues": {}
    }
  },
  "termRuleInstances": {
    "{ruleInstanceId}": {
      "ruleInstanceUrn": "urn:ata:{your-tenant}:data-quality:rule-instance:{ruleInstanceId}",
      "ruleUrn": "urn:ata:{your-tenant}:data-quality:rule:...",
      "ruleInstanceName": "Phone Number Valid",
      "ruleName": "Phone Validation",
      "enabled": true,
      "dqThresholds": {},
      "mappings": {
        "{mappingId}": {
          "catalogItemAttributeUrn": "urn:ata:{your-tenant}:catalog:catalog-attribute:...",
          "ruleAttributeUrn": "urn:ata:{your-tenant}:data-quality:rule-attribute:..."
        }
      },
      "parameterValues": {},
      "terms": [
        {
          "termUrn": "urn:ata:{your-tenant}:catalog:term:...",
          "termName": "Phone Number"
        }
      ]
    }
  },
  "exportDefinitions": {},
  "joinConfigurations": {},
  "overallDqThresholds": {
    "{dqThresholdId}": {
      "urn": "urn:ata:{your-tenant}:data-quality:dq-threshold:{dqThresholdId}",
      "value": 80,
      "severity": "WARNING"
    }
  }
}

The response contains the complete monitor configuration together with the read-only urn, catalogItemUrn, and draftType. For the meaning of each field, see Monitor configuration fields.

Update a monitor

Update a DQ monitor using JSON Merge Patch. The following rules apply to both the monitor fields and its sub-entities (rule instances, mappings, connected mappings, thresholds, parameter values, export definitions, join configurations, and foreign-key pairs):

  • To change a field or a sub-entity, send only the new values. For a sub-entity, send them under the sub-entity’s ID.

    The ruleUrn of a rule instance is the exception: it cannot be changed. To apply a different rule, delete the rule instance and create a new one.

  • To clear a field or delete a sub-entity, set it to null.

    The name field is the exception: it cannot be null, only replaced with another non-empty value. A join configuration’s foreignKeyPairs cannot be cleared either: a join must always keep at least one pair, and a patch that would leave none is rejected with 400 Bad Request.

  • To add a sub-entity, use a new_<id> key.

    If a request creates a join configuration and a connected mapping that uses it, the connected mapping’s joinConfigurationKey references the join configuration by its new_<id> key.

  • To keep anything unchanged, do not mention it in the request.

A single request can combine all of these anywhere in the monitor, for example, adjust a threshold of one rule instance and remove another rule instance. New sub-entities appear in the response under their new IDs, with your temporary key returned in the correlationId field (see How to identify monitor sub-entities).

The request body accepts the fields described in Monitor configuration fields. If you build the update from a retrieved monitor, you can send the edited body back without removing the read-only fields, such as urn, catalogItemUrn, and draftType. The API checks just the URNs inside sub-entities. Each URN must match the ID under which its sub-entity is stored. A mismatch is rejected with 400 Bad Request.

Updates are applied to the current draft. Patching a published monitor opens a new draft on top of the latest published state; publish the draft to make the change live. See Draft and publish lifecycle.

To update the catalog item’s primary monitor without looking up its URN, use primary as the dqMonitorUrn.
Request: Update the monitor schedule
curl -X PATCH "https://{your-environment}.ataccama.one/api/data-quality/v1/catalog-items/{catalogItemUrn}/dq-monitors/{dqMonitorUrn}" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "schedule": {
      "cronExpression": "0 0 6 * * ?",
      "enabled": true,
      "ignoreMisfires": false,
      "timeZone": "Europe/Prague"
    }
  }'

The response returns the updated monitor draft.

Publish a monitor

Publish the current draft, promoting it to the latest published version. See Draft and publish lifecycle.

To publish the catalog item’s primary monitor without looking up its URN, use primary as the dqMonitorUrn.
Request: Publish the monitor draft
curl -X POST "https://{your-environment}.ataccama.one/api/data-quality/v1/catalog-items/{catalogItemUrn}/dq-monitors/{dqMonitorUrn}/publish" \
  -H "Authorization: Bearer {access_token}"

The response returns the published monitor. If the monitor has no current draft, the request still succeeds and returns the currently published version.

Create monitors in batch

Create up to 100 DQ monitors in a single request. Each item requires catalogItemUrn and name. If an item includes sub-entities, such as rule instances, store each of them under a temporary key that you choose (see How to identify monitor sub-entities).

Unlike Create a monitor, batch-created monitors skip the draft stage and are created directly as published versions.

Each item is processed independently: a failure on one item does not cancel the rest. The response is 207 Multi-Status. It contains a meta summary (total, success, fail) and per-item results. On success, a result carries only the URN of the created monitor. On failure, it carries the error instead.

By default, results are paired with the request items by position: the first result belongs to the first item you sent. You can also add your own id to each item; the response returns it in the matching result.

Request: Create two DQ monitors in one request
curl -X POST "https://{your-environment}.ataccama.one/api/data-quality/v1/dq-monitors/batch/create" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      { "id": "item-1", "catalogItemUrn": "urn:ata:{your-tenant}:catalog:catalog-item:...", "name": "Customers Monitor" },
      { "id": "item-2", "catalogItemUrn": "urn:ata:{your-tenant}:catalog:catalog-item:...", "name": "Orders Monitor" }
    ]
  }'
Response: Per-item result of each created monitor
{
  "meta": { "total": 2, "success": 2, "fail": 0 },
  "results": [
    { "id": "item-1", "status": "OK", "data": { "urn": "urn:ata:{your-tenant}:data-quality:dq-monitor:..." } },
    { "id": "item-2", "status": "OK", "data": { "urn": "urn:ata:{your-tenant}:data-quality:dq-monitor:..." } }
  ]
}

Delete a monitor

Permanently delete a DQ monitor. This is a hard delete: both the draft and published versions are removed, and no draft is created.

The primary DQ monitor cannot be deleted. Such a request returns 409 Conflict.
Request: Delete a DQ monitor
curl -X DELETE "https://{your-environment}.ataccama.one/api/data-quality/v1/catalog-items/{catalogItemUrn}/dq-monitors/{dqMonitorUrn}" \
  -H "Authorization: Bearer {access_token}"

A successful request returns 204 No Content.

Error handling

The API returns standard HTTP status codes and problem details for errors:

Status code Description

200 OK

Request successful.

201 Created

DQ monitor created (as a draft).

204 No Content

DQ monitor deleted.

207 Multi-Status

Batch processed; check each item’s result for its individual outcome.

400 Bad Request

Invalid request parameters or body (for example, a malformed URN). The response body includes a type, title, detail, and optionally an errors array with specific validation failures and JSON Pointer references to the problematic fields.

401 Unauthorized

Invalid or expired access token.

403 Forbidden

Insufficient permissions to access the requested resource.

404 Not Found

Catalog item or DQ monitor does not exist, or you requested version=DRAFT for a monitor that has no current draft.

409 Conflict

The request conflicts with the current state of the monitor (for example, deleting the primary monitor).

API reference

For detailed API reference, including all endpoints, parameters, request and response schemas, and examples, see Data Quality API specification.

Next steps

Was this page useful?