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

Manage DQ Dashboards 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 dashboards programmatically: create a dashboard that aggregates the results of selected DQ monitors, publish it, and retrieve its configuration. 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.

API base URL

All Data Quality API endpoints are accessed through the following base URL:

https://{your-environment}.ataccama.one/api/data-quality/v1

Replace {your-environment} with your environment identifier from the Ataccama Cloud Portal.

When to use this API

Use the DQ dashboards API when you need to:

  • Automate DQ setup: Create dashboards from scripts or CI/CD pipelines instead of in the web application, for example, as the last step after setting up the monitors through the API.

  • Promote configurations across environments: Read the dashboard configuration from one environment and recreate it in another (for example, dev to prod). The same approach recreates the dashboards from a previous Ataccama ONE deployment.

Limitations of the DQ dashboards API

The API cannot update or delete a dashboard. It creates, publishes, retrieves, and lists dashboards only. Through the API, the monitor list is set once, when you create the dashboard.

To add monitors to an existing dashboard, add them in the web application. To delete a dashboard, use the web application.

The API does not return the aggregated quality of a dashboard. A dashboard has no results of its own. Its aggregated quality is calculated from the DQ evaluation results of its monitors. To view the aggregated quality, trends over time, and the breakdown by monitor and rule, open the dashboard in the web application. To get DQ evaluation results through the API, request them for each monitor separately.

You cannot share a dashboard with other users through the API. Share the dashboard in the web application instead.

Draft and publish lifecycle

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

  • NEW: Creating a dashboard produces a draft of a new dashboard. Publishing promotes it to the first published version. Until then, the dashboard is not listed, and retrieving it returns 404 Not Found unless you request the draft with ?version=DRAFT.

  • CHANGE: Changing a published dashboard opens a draft on top of the latest published version. Publishing promotes the draft to the new published version.

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

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

    CHANGE, 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.

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

The draftType field refers to the version you retrieved. When you retrieve the published version, draftType is always NONE, even if the dashboard has an unpublished change waiting in a draft.

Dashboard configuration fields

Create requests accept the following fields. Retrieve and list requests return them.

Unlike a rule or monitor draft, a dashboard draft cannot be incomplete. The required fields must be present when you create it.

Field Required Description

name

Yes

The name of the dashboard, 1 to 255 characters.

description

No

Free-text description of the dashboard.

dqMonitorUrns

Yes

The URNs of the DQ monitors whose results the dashboard aggregates, 1 to 100 monitors. The monitors can belong to different catalog items, since a dashboard is not tied to any catalog item.

Each monitor must exist and be published, and your API client must have access to it. If a monitor URN appears more than once, the monitor is added once.

To find the URNs of the monitors, list them.

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

  • urn and draftType: Assigned automatically. The urn identifies the dashboard. On a published version, draftType is NONE.

List dashboards

List the DQ dashboards in your environment. The endpoint returns published dashboards only (see Draft and publish lifecycle).

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

size

integer

No

Number of dashboards to return per page.

Default: 20.

Min: 1.

Max: 100.

sort

string

No

Field to sort by. Only name is supported. Prefix with a hyphen (-) for descending order.

after

string

No

Cursor for forward pagination. Copy the value from meta.next in the previous response as is. Do not build or decode cursors yourself.
Response: Page of DQ dashboards
{
  "meta": {
    "next": "MjA=",
    "total": 42
  },
  "data": [
    {
      "urn": "urn:ata:{your-tenant}:data-quality:dq-dashboard:123e4567-e89b-12d3-a456-426614174000",
      "name": "Sales DQ Dashboard",
      "description": "Aggregated quality of all sales-domain monitors",
      "draftType": "NONE",
      "dqMonitorUrns": [
        "urn:ata:{your-tenant}:data-quality:dq-monitor:...",
        "urn:ata:{your-tenant}:data-quality:dq-monitor:..."
      ]
    }
  ]
}

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

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

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

Paging is forward-only.

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

Create a dashboard

Create a DQ dashboard that aggregates the results of the DQ monitors you specify. The dashboard is created as a draft (draftType: NEW). Publish it to make it live (see Publish a dashboard).

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

Request: Create a DQ dashboard aggregating two monitors
curl -X POST "https://{your-environment}.ataccama.one/api/data-quality/v1/dq-dashboards" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales DQ Dashboard",
    "description": "Aggregated quality of all sales-domain monitors",
    "dqMonitorUrns": [
      "urn:ata:{your-tenant}:data-quality:dq-monitor:...",
      "urn:ata:{your-tenant}:data-quality:dq-monitor:..."
    ]
  }'
Response: Created dashboard draft
{
  "urn": "urn:ata:{your-tenant}:data-quality:dq-dashboard:123e4567-e89b-12d3-a456-426614174000",
  "name": "Sales DQ Dashboard",
  "description": "Aggregated quality of all sales-domain monitors",
  "draftType": "NEW",
  "dqMonitorUrns": [
    "urn:ata:{your-tenant}:data-quality:dq-monitor:...",
    "urn:ata:{your-tenant}:data-quality:dq-monitor:..."
  ]
}

A successful request returns 201 Created with the created dashboard draft. The Location header carries the URL of the created dashboard. The URL might be relative. If it is, resolve it against the URL of your request. Save the urn for publishing and retrieving the dashboard.

Retrieve a dashboard

Retrieve the configuration of a DQ dashboard by URN. By default, the endpoint returns the latest published version. To retrieve the current draft instead, add ?version=DRAFT.

Request: Retrieve a DQ dashboard
curl -X GET "https://{your-environment}.ataccama.one/api/data-quality/v1/dq-dashboards/{dqDashboardUrn}" \
  -H "Authorization: Bearer {access_token}"
Query parameters
Parameter Type Required Description

version

string

No

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

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

Default: PUBLISHED.
Response: Retrieved dashboard
{
  "urn": "urn:ata:{your-tenant}:data-quality:dq-dashboard:123e4567-e89b-12d3-a456-426614174000",
  "name": "Sales DQ Dashboard",
  "description": "Aggregated quality of all sales-domain monitors",
  "draftType": "NONE",
  "dqMonitorUrns": [
    "urn:ata:{your-tenant}:data-quality:dq-monitor:...",
    "urn:ata:{your-tenant}:data-quality:dq-monitor:..."
  ]
}

For the meaning of each field, see Dashboard configuration fields.

Publish a dashboard

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

Request: Publish the dashboard draft
curl -X POST "https://{your-environment}.ataccama.one/api/data-quality/v1/dq-dashboards/{dqDashboardUrn}/publish" \
  -H "Authorization: Bearer {access_token}"

The response returns the published dashboard, with draftType: NONE, in the same form as in Retrieve a dashboard. If the dashboard has no current draft, the request still succeeds and returns the currently published version.

Error handling

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

Status code Description

200 OK

Request successful.

201 Created

DQ dashboard created (as a draft).

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

One of the following:

  • The DQ dashboard does not exist.

  • The dashboard exists only as a draft and you retrieved it without version=DRAFT.

  • You requested version=DRAFT for a dashboard that has no current draft.

  • When creating a dashboard, a referenced DQ monitor does not exist or is not published, or your API client has no access to it. No dashboard is created.

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?