# Data Catalog Links API

Source: https://userguide.qualytics.io/source-datastore/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](https://userguide.qualytics.io/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: Example request and response**
>
> **Request**:
>
> ```bash
> 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):
>
> ```json
> {
>   "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](https://userguide.qualytics.io/source-datastore/data-catalog-links/api/#search-catalog-assets) result rather than assembling them by hand.

> **Example: Example request**
>
> ```bash
> 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: Example request**
>
> ```bash
> 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. For a Manager it covers only the datastores where they have **Editor**. An Admin bypasses team permissions, so it covers every datastore of the integration.

> **Example: Example request**
>
> ```bash
> 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**.

*Last updated: October 6, 2026.*
