Import API

The Import API allows you to programmatically import entities into the platform, bulk-delete them, and import or delete column level lineage from raw SQL queries.

Two payload formats are supported:

JSON via /api/v1/import - recommended for configuration entities such as test cases, test suites, connections, dynamic rules, variables, webhooks, parameters and business rules.
CSV via /api/v1/import/csv - used for catalog entities such as objects, columns, terms and their relations, as well as CSV exports of business rules.

Each JSON request is an array of wrapper objects in the form:

[
  {
    "entityType": "<TYPE>",
    "entity": { /* entity payload */ }
  }
]

All entities in a single JSON request must share the same entityType. IDs (id, connectionRef, testsuiteRef, dynamicRuleRef, webhookRefs, testCaseRef) are UUIDs - if the entity already exists with the given ID it is updated, otherwise it is created.

Supported entityType values:

Entity type	JSON	CSV
`TEST_CASE`	X	X
`TEST_SUITE`	X
`CONNECTION`	X
`DYNAMIC_RULE`	X
`VARIABLE`	X
`WEBHOOK`	X
`PARAMETER`	X
`BUSINESS_RULE`	X	X
`OBJECT`		X
`COLUMN`		X
`COLUMN_RELATION`		X
`COLUMN_TERM_RELATION`		X
`TERM`		X
`TERM_RELATION`		X

Import JSON entity

/api/v1/import

Import endpoint for any JSON objects that are previously exported from the application

Request parameters

Responses

Import one or more entities of the same type as a JSON array. Each element must specify entityType and an entity payload. See the per-type sections below for the expected payload structure.

Response example:

{
  "type": "TEST_CASE",
  "created": 2,
  "updated": 0,
  "failed": 0,
  "total": 2
}

Import CSV entity

/api/v1/import/csv

Import endpoint for any CSV objects that are previously exported from the application

Request parameters

Responses

{
  "type": "TEST_CASE",
  "created": 96,
  "updated": 96,
  "failed": 96,
  "total": 96
}

Used for catalog entity types (OBJECT, COLUMN, COLUMN_RELATION, COLUMN_TERM_RELATION, TERM, TERM_RELATION) as well as CSV exports of TEST_CASE and BUSINESS_RULE. The expected CSV headers match those produced by the matching export template - you can download the template for a given entity type from the catalog import UI.

Term references

Several CSV columns reference business glossary terms by name. Because a term name is only unique within its glossary, these references embed the glossary path in the value:

Term name - a term at the glossary root
My glossary|Term name - a term inside a glossary, with a pipe (|) separating path and name
Parent glossary/Sub glossary|Term name - nested glossary levels are joined with /

This is exactly what exports produce, so exported files re-import without editing. On import a bare term name matches root terms only - a term that lives inside a glossary must be referenced with its full glossary path, even if the name is unique across glossaries. A reference that cannot be resolved marks that row as failed.

The format is used wherever a CSV value points at a term:

TERM_RELATION - the sourceName and targetName columns
COLUMN_TERM_RELATION - the term column
term-type custom field values (cf_ columns) on any entity that supports them

Term mentions in descriptions

Description texts can embed glossary term mentions. Exports serialize each mention as a portable token in the form @[Label](key:|Glossary path|Term name|) (the glossary segment is empty for root terms). On import each token is matched against the glossary: a resolved mention becomes a live term link again, and an unresolved one keeps its label and re-links automatically once a matching term exists (for example later in the same import batch). Plain-text descriptions written by hand import as-is - the tokens only matter when round-tripping exported data.

Entity types

Each section below describes one entityType and which import endpoint accepts it.

JSON only (/api/v1/import): TEST_SUITE, CONNECTION, DYNAMIC_RULE, VARIABLE, WEBHOOK, PARAMETER.
CSV only (/api/v1/import/csv): OBJECT, COLUMN, COLUMN_RELATION, COLUMN_TERM_RELATION, TERM, TERM_RELATION.
Both formats: TEST_CASE, BUSINESS_RULE. Note that CSV business rule import does not link test cases - use JSON if you need testCaseRefs.

CSV imports expect headers that match the corresponding export template - download it from the catalog import UI before filling it in.

TEST_CASE

Import test cases. connectionRef and testsuiteRef must reference existing entities (or be included earlier in the same deployment flow). relations.schema and relations.object bind the test case to a catalog object so lineage and alerting work correctly.

Request example:

[
  {
    "entityType": "TEST_CASE",
    "entity": {
      "id": "fd523557-118e-4356-81e9-432ed462d50c",
      "connectionRef": "11d6f2ee-424b-4e64-abcb-f95902496b4a",
      "testsuiteRef": "d2f2d729-721c-4e6e-b5ab-4dad679cb561",
      "description": "public.addresses - Count of rows",
      "sql": "SELECT COUNT(*) FROM public.addresses",
      "expectedResult": ">0",
      "type": "Query",
      "owner": "David",
      "dynamicRuleRef": "eaf2f027-88fe-4258-9804-b50645ff5eb7",
      "autoUpdate": false,
      "disabled": true,
      "severity": "CRITICAL",
      "autoRelation": true,
      "relations": {
        "columns": [],
        "schema": "public",
        "object": "addresses"
      },
      "labels": [
        "LIVE"
      ],
      "scheduleType": "NOT_SCHEDULED"
    }
  },
  {
    "entityType": "TEST_CASE",
    "entity": {
      "id": "1e5d783a-dd41-4712-b083-0d5e9a3dc9d8",
      "connectionRef": "11d6f2ee-424b-4e64-abcb-f95902496b4a",
      "testsuiteRef": "d2f2d729-721c-4e6e-b5ab-4dad679cb561",
      "description": "public.addresses - Duplicates",
      "sql": "SELECT COUNT(*) FROM (SELECT \"language\",\"suite\" FROM public.addresses GROUP BY \"language\",\"suite\" HAVING COUNT(*)>1) a",
      "expectedResult": "=0",
      "type": "Query",
      "owner": "David",
      "autoUpdate": false,
      "disabled": false,
      "severity": "WARNING",
      "relations": {
        "columns": [
          "language",
          "suite"
        ],
        "schema": "public",
        "object": "addresses"
      },
      "labels": []
    }
  }
]

Key fields:

type - Query, Compare, QueryTotal. Compare additionally requires compareConnectionRef and compareSql.
dynamicRuleRef - optional UUID of the parent dynamic rule when this case was generated from one.
severity - CRITICAL, WARNING, INFO.
scheduleType - see Scheduling. Omit or use NOT_SCHEDULED to inherit the test suite schedule.

TEST_SUITE

Import test suites. Referenced test cases are linked through testsuiteRef in the test case payload - a test suite import does not embed its test cases.

Request example:

[
  {
    "entityType": "TEST_SUITE",
    "entity": {
      "id": "d2f2d729-721c-4e6e-b5ab-4dad679cb561",
      "name": "Addresses - core checks",
      "owner": "David",
      "directory": "Customer data/Addresses",
      "emails": [
        "data-quality@example.com"
      ],
      "emailThreshold": 0.1,
      "resultsInReportRows": 100,
      "severity": "CRITICAL",
      "alertMode": "ON_FAILURE",
      "visibility": "PUBLIC",
      "allowedRoles": "data-quality,analysts",
      "webhookRefs": [
        "5e4b3f02-9b21-4f0a-9bd7-1c52b5d0e0a0"
      ],
      "tags": [
        { "name": "LIVE", "color": "green" },
        { "name": "core", "color": "blue" }
      ],
      "scheduleType": "SELECTED_DAYS",
      "scheduleDay": "MON,TUE,WED,THU,FRI",
      "scheduleTime": "06:00"
    }
  }
]

Key fields:

directory - forward-slash separated folder path. Missing folders are created on import.
emailThreshold - fraction of failing tests (0.0–1.0) that triggers an email notification.
alertMode - ALWAYS or ON_FAILURE.
visibility - PUBLIC, PRIVATE or READ_ONLY. PUBLIC is viewable and editable by everyone, PRIVATE is viewable and editable only by the owner and users matching allowedRoles, READ_ONLY is viewable by everyone but only editable by the owner and users matching allowedRoles.
allowedRoles - comma-separated role names. Used when visibility is PRIVATE (controls view and edit) or READ_ONLY (controls edit only). Ignored when visibility is PUBLIC.
scheduleType - NOT_SCHEDULED, SELECTED_DAYS, MONTHLY, CUSTOM, CRON. Additional fields scheduleDay, scheduleTime, scheduleDate, scheduleCustom are used depending on the chosen type - see Scheduling.

CONNECTION

Import database connections. Credentials are not included in the payload and must be set through the Connections UI or the secrets backend after import.

Request example:

[
  {
    "entityType": "CONNECTION",
    "entity": {
      "id": "11d6f2ee-424b-4e64-abcb-f95902496b4a",
      "type": "postgresql",
      "name": "warehouse-prod",
      "databaseUrl": "warehouse.internal",
      "databaseName": "analytics",
      "databaseUser": "dqm_reader",
      "databasePort": 5432,
      "maxThreads": 4,
      "timeout": 60,
      "properties": "sslmode=require",
      "jdbcUrlOverride": null
    }
  }
]

Key fields:

type - connector identifier as shown in the Connections UI (e.g. postgresql, mssql, snowflake, bigquery). See Connections.
jdbcUrlOverride - use this to supply a full JDBC URL instead of the discrete databaseUrl/databasePort/databaseName triple.

DYNAMIC_RULE

Import dynamic rules - SQL templates that generate test cases based on metadata.

Request example:

[
  {
    "entityType": "DYNAMIC_RULE",
    "entity": {
      "id": "eaf2f027-88fe-4258-9804-b50645ff5eb7",
      "shortDescription": "Row count > 0",
      "longDescription": "Asserts that the target object has at least one row.",
      "sql": "SELECT COUNT(*) FROM {schema}.{object}",
      "expectedResult": ">0",
      "drivers": [
        "postgresql",
        "mssql"
      ]
    }
  }
]

Key fields:

sql - may use the {schema}, {object} and {column} placeholders that are substituted per generated test case.
drivers - list of connector types this dynamic rule applies to. Leave empty for all.

VARIABLE

Import global variables usable in SQL via ${variableName} syntax.

Request example:

[
  {
    "entityType": "VARIABLE",
    "entity": {
      "id": "8b3d1e42-9ac0-4a7d-8a71-5c2f8d1aa001",
      "name": "environment",
      "value": "PRODUCTION"
    }
  },
  {
    "entityType": "VARIABLE",
    "entity": {
      "id": "8b3d1e42-9ac0-4a7d-8a71-5c2f8d1aa002",
      "name": "maxDaysStale",
      "value": "7"
    }
  }
]

WEBHOOK

Import webhook definitions used for alerting.

Request example:

[
  {
    "entityType": "WEBHOOK",
    "entity": {
      "id": "5e4b3f02-9b21-4f0a-9bd7-1c52b5d0e0a0",
      "name": "slack-data-quality",
      "url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXX",
      "json": {
        "text": "DQM alert: {{testSuiteName}} - {{failedCount}} failing tests"
      }
    }
  }
]

Key fields:

json - request body template. Placeholders such as {{testSuiteName}}, {{failedCount}} are substituted by the alerting engine when the webhook fires.

PARAMETER

Import per-test-case parameter overrides. values[].testCaseRef must match an existing test case UUID.

Request example:

[
  {
    "entityType": "PARAMETER",
    "entity": {
      "id": "6a1f9b3b-0d77-4f35-9fa4-c7b82b3c1234",
      "name": "expectedRowCount",
      "values": [
        {
          "testCaseRef": "fd523557-118e-4356-81e9-432ed462d50c",
          "value": "10000"
        },
        {
          "testCaseRef": "1e5d783a-dd41-4712-b083-0d5e9a3dc9d8",
          "value": "0"
        }
      ]
    }
  }
]

Parameter values are fully replaced on import: any existing values for the parameter that are not listed in the values array are removed.

BUSINESS_RULE

Import business rules. The testCaseRefs field links the rule to test cases by UUID - those test cases must already exist or be imported in the same deployment.

Request example:

[
  {
    "entityType": "BUSINESS_RULE",
    "entity": {
      "id": "3244945c-c777-4fc8-9b63-cf1501011bf3",
      "name": "Every order must have an address",
      "description": "Orders with no linked address cannot be fulfilled.",
      "owners": [
        "david@example.com",
        "anna@example.com"
      ],
      "allowedRoles": [
        "data-stewards"
      ],
      "testCaseRefs": [
        "fd523557-118e-4356-81e9-432ed462d50c",
        "1e5d783a-dd41-4712-b083-0d5e9a3dc9d8"
      ]
    }
  }
]

Business rules are also importable from CSV via /api/v1/import/csv?type=BUSINESS_RULE, however CSV import does not link test cases - use the JSON endpoint if you need to set testCaseRefs.

OBJECT

CSV import only via /api/v1/import/csv?type=OBJECT. Imports catalog objects (tables and views) into the catalog. Expected CSV headers match the OBJECT export template downloadable from the catalog import UI.

COLUMN

CSV import only via /api/v1/import/csv?type=COLUMN. Imports column descriptions and metadata attached to existing catalog objects. Expected CSV headers match the COLUMN export template.

COLUMN_RELATION

CSV import only via /api/v1/import/csv?type=COLUMN_RELATION. Imports column-level lineage relations between catalog columns. For SQL-driven lineage that the platform should parse for you instead, use the Import lineage endpoint.

COLUMN_TERM_RELATION

CSV import only via /api/v1/import/csv?type=COLUMN_TERM_RELATION. Imports the mapping between catalog columns and business glossary terms. The term column uses the term reference format, so glossary-scoped terms are written as My glossary|Term name.

TERM

CSV import only via /api/v1/import/csv?type=TERM. Imports business glossary terms.

Columns: name (required), color, description, type, glossary, plus one cf_ column per custom field defined for terms (multiple values within one cell are separated by ;). glossary is the full path of an existing glossary with nested levels joined by / (e.g. Finance/Accounting); when it is empty or does not match an existing glossary, the term is placed at the glossary root. An unknown type value creates that term type. Descriptions may carry term mention tokens; values of term-type custom fields use the term reference format.

TERM_RELATION

CSV import only via /api/v1/import/csv?type=TERM_RELATION. Imports relations between business glossary terms.

Columns: sourceName, relation, targetName. Both term columns use the term reference format - there is no separate glossary column, the glossary path is part of the term reference (My glossary|Term name).

The relation value is matched case-insensitively against the built-in relations (Synonym, Related to, Contains) and the custom relation types defined under Settings. A directed custom relation is accepted by either of its side names - importing the inverse side swaps source and target, so the stored relation always uses the type's original direction. An unknown relation value creates a new custom relation type with that name. Rows that duplicate an existing relation are reported as failed, and Contains relations are validated against containment cycles.

Import lineage

/api/v1/import/lineage

Import column level lineage from SQL queries

Request parameters

Responses

Parses the supplied SQL queries against the named connection's metadata and creates column level lineage relations where source and destination columns can be resolved. Queries that reference objects unknown to the platform are skipped unless smart relations are enabled in lineage settings.

Request example:

{
  "connectionName": "connection_name",
  "aggregateRelations": false,
  "batchId": "overnight-data-loading-2026-04-28",
  "queries": [
    "SELECT COUNT(*) FROM sports.participants_events JOIN sports.latest_revisions ON id = event_id WHERE rank > 1"
  ]
}

Response example:

{
  "type": "QUERY",
  "created": 1,
  "updated": 0,
  "deleted": 0,
  "failed": 0,
  "total": 1,
  "errors": [],
  "warnings": [],
  "batchId": "overnight-data-loading-2026-04-28"
}

When you omit batchId, a UUID is generated, persisted as the batch handle, and returned in the response. Pass that same id to a later call to replace the batch, or to the delete endpoint below to remove it. Re-importing under an existing batchId replaces the batch: relations that reappear in the payload are reported as updated, and relations no longer present are removed and counted in deleted.

Delete lineage batch

/api/v1/import/lineage

Delete all lineage relations imported under a batchId

Request parameters

Responses

Removes every lineage relation imported under the given batchId, passed as a query parameter. Relations the batch created that retain no other references are deleted; relations that other batches still reference keep the relation row but lose the references this batch contributed. The call is idempotent - an unknown batchId returns deleted: 0.

Request example:

DELETE /api/v1/import/lineage?batchId=overnight-data-loading-2026-04-28

Response example:

{
  "type": "QUERY",
  "created": 0,
  "updated": 0,
  "deleted": 3,
  "failed": 0,
  "total": 0,
  "errors": [],
  "warnings": [],
  "batchId": "overnight-data-loading-2026-04-28"
}

Delete entities

/api/v1/delete

Delete any imported entity by the reference id(s)

Request parameters

Responses

Bulk-deletes entities by UUID. The endpoint resolves the entity type from the UUID automatically, so IDs from different types can be mixed in a single request.

Request example:

{
  "ids": [
    "3244945c-c777-4fc8-9b63-cf1501011bf3"
  ]
}

Response example:

{
  "deleted": 1,
  "failed": 0,
  "total": 1,
  "errors": []
}

27 August 2026