Data Catalog Links API

You can read, set, and clear catalog links programmatically, search a catalog's assets, and start a scoped synchronization.

Tip

For complete API documentation, including request/response schemas, visit the API docs.

All endpoints use the base URL of your Qualytics deployment (e.g., https://your-instance.qualytics.io/api) and require a Personal API Token. Reading a link requires the Member role and access to the asset's datastore through any team permission (Reporter or above); setting or clearing one requires the Editor team permission on that datastore.

The same three operations exist per level, at /datastores/{id}/catalog-link, /containers/{id}/catalog-link, and /fields/{id}/catalog-link. The examples below use the datastore route; substitute the container or field route to operate on those levels.

Get a Catalog Link

Returns the persisted link between the asset and one data catalog integration.

Endpoint: GET /datastores/{id}/catalog-link?integration_id={integration_id}

Permission: Member or above, with access to the datastore through any team permission (Reporter or above)

Returns HTTP 404 Not Found when the asset has no link in that catalog.

Example request and response

Request:

curl -X GET "https://your-instance.qualytics.io/api/datastores/42/catalog-link?integration_id=7" \
  -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN"

Response (200 OK):

{
  "id": 101,
  "integration_id": 7,
  "datastore_id": 42,
  "catalog_guid": "c2a1...",
  "catalog_name": "finance",
  "catalog_location": "prod-warehouse.finance",
  "catalog_asset_type": "datastore",
  "catalog_source_type": "Schema",
  "link_mode": "manual",
  "last_synced_at": "2026-08-30T14:02:11Z",
  "is_valid": true,
  "catalog_url": "https://catalog.example.com/assets/c2a1..."
}

link_mode tells manual and automatic links apart, is_valid reports whether the link still counts for synchronization, and catalog_url is the address behind the Open in [catalog] button.

Set a Manual Catalog Link

Creates or replaces the asset's manual link in one catalog.

Endpoint: PUT /datastores/{id}/catalog-link?integration_id={integration_id}

Permission: The Editor team permission on the asset's datastore

Field	Required	Description
`catalog_guid`	Yes	The catalog asset's stable identifier.
`catalog_asset_type`	Yes	The Qualytics asset level the catalog asset maps to.
`catalog_source_type`	Yes	The asset's own type name in the catalog.
`catalog_name`	No	The asset's name in the catalog.
`catalog_location`	No	The asset's qualified location in the catalog.

Take these values from a catalog asset search result rather than assembling them by hand.

Example request

curl -X PUT "https://your-instance.qualytics.io/api/datastores/42/catalog-link?integration_id=7" \
  -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "catalog_guid": "c2a1...",
    "catalog_asset_type": "datastore",
    "catalog_source_type": "Schema",
    "catalog_name": "finance",
    "catalog_location": "prod-warehouse.finance"
  }'

Response (200 OK): the saved link, in the same shape as the read endpoint.

Clear a Catalog Link

Removes the asset's link in one catalog. The next synchronization is free to auto-match the asset again.

Endpoint: DELETE /datastores/{id}/catalog-link?integration_id={integration_id}

Permission: The Editor team permission on the asset's datastore

Returns HTTP 204 No Content on success, and HTTP 404 Not Found when the asset has no link in that catalog.

Search Catalog Assets

Searches one integration's catalog for assets to link, by Qualytics asset level and a free-text query over names and identifiers.

Endpoint: GET /integrations/{id}/catalog-assets?asset_type={level}&search={query}&authorize_datastore_id={datastore_id}

Permission: Member or above. Non-admin callers must pass authorize_datastore_id, a datastore they hold the Editor team permission on; it authorizes the search without narrowing the results.

Parameter	Required	Description
`asset_type`	Yes	The Qualytics level to search for. Returns the catalog's schema-level assets for a datastore, tables for a container, and columns for a field.
`search`	No	Free-text query over asset names and identifiers.
`authorize_datastore_id`	For non-admins	A datastore the caller can edit, proving the right to search.
`limit`	No	Maximum results, up to 500 (default 100).

Example request

curl -X GET "https://your-instance.qualytics.io/api/integrations/7/catalog-assets?asset_type=datastore&search=finance&authorize_datastore_id=42" \
  -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN"

Start a Scoped Synchronization

Starts a synchronization of one integration restricted to specific datastores, the same operation the dialog's Sync button runs.

Endpoint: POST /integrations/{id}/sync

Permission: The Editor team permission on every datastore in filter_datastores. Omitting filter_datastores starts a full synchronization, which requires the Manager or Admin role.

Example request

curl -X POST "https://your-instance.qualytics.io/api/integrations/7/sync" \
  -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "pull": true,
    "push": true,
    "filter_datastores": [42]
  }'

Response: HTTP 204 No Content. Progress and results are reported on the integration's entry under Settings > Integrations.