Set up DQ Rules and 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 set up DQ rules and monitoring programmatically, without manual work in the web application. It covers two common scenarios: onboarding a newly connected data source, and importing rule definitions from an external source such as Microsoft Excel or Collibra.

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

Onboard a new data source

When a new data source is connected and its catalog items are available, set up data quality end to end: create the DQ rules, create and configure a DQ monitor, run the first evaluation, and review the results.

To create rules one at a time, as drafts you review and then publish, follow Step 1: Create DQ rules and Step 2: Publish the rules.

To create multiple rules at once, use the batch endpoint instead. Batch-created rules must be complete (that is, they must already meet the publish requirements), and they are published directly. Then continue with Step 3: Create a DQ monitor.

Step 1: Create DQ rules

Create the DQ rules you want to apply to the data. Rules are created as drafts and must be published before they can be used in a monitor.

Request: Create a DQ rule

curl -X POST "https://{your-environment}.ataccama.one/api/data-quality/v1/rules" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Email Format Validation",
    "inputGroups": {
      "new_input-group": {
        "name": "Input",
        "inputs": {
          "new_email": { "name": "email", "dataType": "STRING" }
        }
      }
    },
    "implementation": { ... }
  }'

The response returns the created rule draft, including its URN. Save the rule URN for the assignment step. For the rule structure and details, see Create a rule.

Step 2: Publish the rules

Publish each rule so it can be used in monitors.

Request: Publish a DQ rule

curl -X POST "https://{your-environment}.ataccama.one/api/data-quality/v1/rules/{ruleUrn}/publish" \
  -H "Authorization: Bearer {access_token}"

Publishing requires the rule to be complete (including a name, an implementation with conditions, and at least one input group with joined: false). An incomplete rule fails with a 400 error listing what is missing. For details, see Publish a rule.

Step 3: Create a DQ monitor

Create a DQ monitor for the catalog item. The monitor is created as a draft.

Request: Create a DQ monitor

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": "Customer Data Monitor"}'

The response returns the created monitor, including its URN. Save it for the following steps.

For the full request body options and details, see Create a monitor.

Step 4: Assign rules and set thresholds

Assign the published rules to the DQ monitor and configure DQ thresholds by updating the monitor draft.

Rules are assigned as rule instances in manualRuleInstances. Reference the rule by its ruleUrn and map the rule’s input attributes to the catalog item’s attributes.

Rule instances, mappings, and thresholds are stored under their own IDs. For new sub-entities, you choose a temporary key that starts with new_ (see How to identify monitor sub-entities).

Request: Assign a rule and set thresholds

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 '{
    "manualRuleInstances": {
      "new_email-rule": {
        "ruleUrn": "urn:ata:{your-tenant}:data-quality:rule:...",
        "ruleInstanceName": "Email Format Valid",
        "enabled": true,
        "mappings": {
          "new_email-mapping": {
            "catalogItemAttributeUrn": "urn:ata:{your-tenant}:catalog:catalog-attribute:...",
            "ruleAttributeUrn": "urn:ata:{your-tenant}:data-quality:rule-attribute:..."
          }
        },
        "dqThresholds": {
          "new_email-threshold": { "value": 80 }
        }
      }
    },
    "overallDqThresholds": {
      "new_overall-threshold": { "value": 80 }
    }
  }'

The request properties:

ruleUrn: URN of the published rule to apply. Required when you create a rule instance; on an existing rule instance, the rule cannot be changed.
ruleInstanceName: Display name of this rule instance on the monitor.
enabled: Whether the rule instance is evaluated; false pauses the DQ evaluation of the rule instance.
mappings: Maps each rule input attribute (ruleAttributeUrn) to a catalog item attribute (catalogItemAttributeUrn).

The ruleAttributeUrn values come from the rule itself: retrieve the rule and read the urn of each input in inputs. See Retrieve a rule.
dqThresholds: Thresholds for this rule instance. The value is the percentage of valid records (from 0 to 100): when the evaluation results in fewer valid records, an alert finding is triggered.
parameterValues: For parameterized rules only, the value of each rule parameter. Reference the parameter by its ruleParameterUrn (the urn of the parameter in the rule’s parameters) and provide the value.
overallDqThresholds: Thresholds for the monitor as a whole, with the same value semantics.

The update changes only the rule instances you send. Everything else stays unchanged. For the full update semantics, see Update a monitor.

Step 5: Publish the monitor

Publish the monitor draft to make the configuration live.

Request: Publish the DQ monitor

curl -X POST "https://{your-environment}.ataccama.one/api/data-quality/v1/catalog-items/{catalogItemUrn}/dq-monitors/{dqMonitorUrn}/publish" \
  -H "Authorization: Bearer {access_token}"

For details, see Publish a monitor.

Step 6: Run the first evaluation

Start the DQ monitor processing to run the first evaluation and verify the setup works end to end.

Request: Start the DQ monitor processing

curl -X POST "https://{your-environment}.ataccama.one/api/data-quality/v1/catalog-items/{catalogItemUrn}/dq-monitors/{dqMonitorUrn}/processings" \
  -H "Authorization: Bearer {access_token}"

The processing runs asynchronously. For polling and completion handling, see Run DQ Evaluation from Pipelines.

Step 7: Review the results

After the processing completes, retrieve the results and check that the rules were applied as expected: each assigned rule appears in ruleInstanceResults, and threshold breaches (if any) appear as findings.

Request: Retrieve the latest DQ results

curl -X GET "https://{your-environment}.ataccama.one/api/data-quality/v1/catalog-items/{catalogItemUrn}/dq-monitors/{dqMonitorUrn}/processings/latest/dq-results" \
  -H "Authorization: Bearer {access_token}"

For the full response structure, see Retrieve DQ Results for External Systems.

Import rules from an external source

To migrate rule definitions maintained outside Ataccama ONE (for example, in Excel or Collibra), import them one at a time with a script that iterates through the source list and calls the rule creation API for each definition.

Imported rules are created as drafts. This gives your team a review checkpoint: complete and validate each rule, then publish it either in the web application or through the API publish endpoint.

If the source definitions are already complete and validated and no review step is needed, use the batch endpoint instead. The batch endpoint imports up to 100 rules per request directly as published versions, skipping the draft review this workflow relies on.

Script example: Import rules from an external source as drafts

import requests

rules = load_rules_from_source()  # e.g., parse an Excel export or a Collibra API response

for rule in rules:
    response = requests.post(
        f"{BASE_URL}/data-quality/v1/rules",
        headers={"Authorization": f"Bearer {token}"},
        json={
            "name": rule["name"],
            "description": rule.get("description"),
            "inputGroups": rule["input_groups"],
            "implementation": rule.get("implementation"),  # may be omitted; drafts can be incomplete
        },
    )
    response.raise_for_status()
    print(f"Imported as draft: {rule['name']} -> {response.json()['urn']}")

Drafts can be created incomplete, so each rule imports successfully even when its logic cannot be fully converted from the source definition. A rule only needs to be complete when you publish it. 400 validation errors in the loop therefore indicate malformed requests (for example, an invalid data type) rather than incomplete logic.

After the import:

Review the draft rules in the web application and complete any missing information that could not be imported from the source system. For details on completing the rule definition, see Create DQ Rule in the Rule Library.
Publish each rule, either in the web application or via the API publish endpoint (see Step 2: Publish the rules).

Rule and monitor lifecycle

Both rules and monitors follow the same draft and publish lifecycle:

Creation always produces a draft. A draft is a working version: it can be reviewed and updated without affecting live DQ rules and monitors. Rule drafts can be incomplete until you publish them.
Publishing is a separate step that promotes the draft to the published version.
The batch create endpoints are the exception: they create rules and monitors directly as published versions, skipping the draft stage.

A rule that has only a draft version can be assigned to a monitor draft. However, the monitor cannot be published until every assigned rule has a published version, and evaluations can be started only for published monitors, not for monitor drafts.

Troubleshooting

400 Bad Request when creating or updating

The request body is invalid (VALIDATION_ERROR). The response’s errors array lists each failure with a JSON Pointer to the problematic field.

400 Bad Request when publishing a rule

The rule is incomplete: it does not yet meet the publish requirements. The 400 response lists what is missing.

To check a current draft of the rule, retrieve it with ?version=DRAFT.

404 Not Found when creating a monitor

The catalog item does not exist or the URN is malformed (RESOURCE_NOT_FOUND). Check the URN format (urn:ata:{tenant}:catalog:catalog-item:{uuid}) and that the tenant segment matches your environment.

Assigned rule has no effect in the evaluation results

Check that:

The rule is published.
The rule instance is enabled (enabled: true).
The attribute mappings reference existing catalog item attributes.

API reference

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

Next steps

Manage DQ Monitors via API: Manage DQ monitor configuration in detail.
Run DQ Evaluation from Pipelines: Run DQ evaluation from your pipelines.
Retrieve DQ Results for External Systems: Retrieve and interpret DQ results.

Was this page useful?