# Field Data Catalog Links API

Source: https://userguide.qualytics.io/fields/data-catalog-links/api/

You can read, set, and clear a field's catalog link programmatically, and search a catalog's columns when picking the counterpart.

> **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 field's datastore through any team permission (**Reporter** or above); setting or clearing one requires the **Editor** team permission on that datastore.

These are the field variants of the same operations available for datastores and containers; the request and response shapes match the [datastore-level API](https://userguide.qualytics.io/source-datastore/data-catalog-links/api/).

## Get the Field's Catalog Link

**Endpoint**: `GET /fields/{id}/catalog-link?integration_id={integration_id}`

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

Returns the persisted link for the field in one data catalog integration, including `link_mode` (manual or automatic), `last_synced_at`, `is_valid`, and the `catalog_url` behind the **Open in [catalog]** button. Returns `HTTP 404 Not Found` when the field has no link in that catalog.

> **Example: Example request**
>
> ```bash
> curl -X GET "https://your-instance.qualytics.io/api/fields/978/catalog-link?integration_id=7" \
>   -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN"
> ```

## Set a Manual Catalog Link

**Endpoint**: `PUT /fields/{id}/catalog-link?integration_id={integration_id}`

**Permission**: The **Editor** team permission on the field's datastore

The body carries the catalog asset's identity: `catalog_guid`, `catalog_asset_type`, and `catalog_source_type` are required; `catalog_name` and `catalog_location` are optional. Take these values from a [catalog asset search](https://userguide.qualytics.io/fields/data-catalog-links/api/#search-the-catalogs-columns) result rather than assembling them by hand.

> **Example: Example request**
>
> ```bash
> curl -X PUT "https://your-instance.qualytics.io/api/fields/978/catalog-link?integration_id=7" \
>   -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "catalog_guid": "f4c9...",
>     "catalog_asset_type": "field",
>     "catalog_source_type": "Column",
>     "catalog_name": "order_total",
>     "catalog_location": "prod-warehouse.finance.orders.order_total"
>   }'
> ```
>
> **Response** (200 OK): the saved link.

## Clear the Field's Catalog Link

**Endpoint**: `DELETE /fields/{id}/catalog-link?integration_id={integration_id}`

**Permission**: The **Editor** team permission on the field's datastore

Returns `HTTP 204 No Content` on success, and `HTTP 404 Not Found` when the field has no link in that catalog. The next synchronization is free to auto-match the field again.

## Search the Catalog's Columns

**Endpoint**: `GET /integrations/{id}/catalog-assets?asset_type=field&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.

With `asset_type=field`, the search returns the catalog's column-level assets matching the free-text query over names and identifiers.

> **Example: Example request**
>
> ```bash
> curl -X GET "https://your-instance.qualytics.io/api/integrations/7/catalog-assets?asset_type=field&search=order_total&authorize_datastore_id=42" \
>   -H "Authorization: Bearer YOUR_QUALYTICS_TOKEN"
> ```

*Last updated: September 7, 2026.*
