---
updatedAt: 2026-04-13T13:25:41.000Z
agentTools:
  projectIndex: https://developer.intellistack.com/llms.txt
---

# Data Catalog

Browse entities, inspect fields, and manage data classes in your organization's data catalog. The catalog is the schema layer that powers datasets and workflow steps.

## Quick Navigation

* [What is the Data Catalog?](https://developer.intellistack.com/docs/data-catalog#what-is-the-data-catalog)
* [Core Concepts](https://developer.intellistack.com/docs/data-catalog#core-concepts)
  * [Entities](https://developer.intellistack.com/docs/data-catalog#entities)
  * [Data fields](https://developer.intellistack.com/docs/data-catalog#data-fields)
  * [Data classes](https://developer.intellistack.com/docs/data-catalog#data-classes)
* [How-To Guides](https://developer.intellistack.com/docs/data-catalog#how-to-guides)
  * [List entities](https://developer.intellistack.com/docs/data-catalog#list-entities)
  * [Get an entity by ID](https://developer.intellistack.com/docs/data-catalog#get-an-entity-by-id)
  * [Batch lookup entities](https://developer.intellistack.com/docs/data-catalog#batch-lookup-entities)
  * [Get adjacent entities](https://developer.intellistack.com/docs/data-catalog#get-adjacent-entities)
  * [List data fields](https://developer.intellistack.com/docs/data-catalog#list-data-fields)
  * [Get fields for an entity](https://developer.intellistack.com/docs/data-catalog#get-fields-for-an-entity)
  * [Get a single field](https://developer.intellistack.com/docs/data-catalog#get-a-single-field)
  * [Create a field on an entity](https://developer.intellistack.com/docs/data-catalog#create-a-field-on-an-entity)
  * [Update a field](https://developer.intellistack.com/docs/data-catalog#update-a-field)
  * [Batch lookup fields by entity](https://developer.intellistack.com/docs/data-catalog#batch-lookup-fields-by-entity)
  * [Update a field's data class](https://developer.intellistack.com/docs/data-catalog#update-a-fields-data-class)
  * [Update field metadata](https://developer.intellistack.com/docs/data-catalog#update-field-metadata)
  * [Get field settings](https://developer.intellistack.com/docs/data-catalog#get-field-settings)
  * [Update field settings](https://developer.intellistack.com/docs/data-catalog#update-field-settings)
  * [List data classes](https://developer.intellistack.com/docs/data-catalog#list-data-classes)
  * [Get a data class by ID](https://developer.intellistack.com/docs/data-catalog#get-a-data-class-by-id)
* [Error responses](https://developer.intellistack.com/docs/data-catalog#error-responses)

## What is the Data Catalog?

The **Data Catalog** is the schema layer that describes the structure of your connected data sources. When you connect an integration (for example Salesforce or a database), Streamline discovers the tables, objects, or collections from that source and stores them as **entities**. Each entity contains **data fields** — the individual columns or properties — and every field can be tagged with a **data class** that describes the kind of data it holds (for example "Email Address" or "Phone Number").

You do not create catalog entries by hand. Catalog entities and fields are populated automatically when an integration syncs. Use the catalog APIs to *browse* what was discovered, *inspect* field details, and *classify* fields with data classes.

The catalog feeds into the rest of Streamline: [datasets](https://developer.intellistack.com/docs/dataset-management) reference catalog entities and fields, and workflow steps such as [Data Search](https://developer.intellistack.com/docs/data-search-step) and [Deliver Data](https://developer.intellistack.com/docs/deliver-data-step) rely on the catalog to know which fields are available, searchable, and writable.

## Core Concepts

### Entities

An **entity** represents a single table, object, or collection discovered from a connected data source. Each entity has a display `label`, an optional `descriptor`, and a `nativeIdentifier` that matches the name at the source (for example a Salesforce object API name or a database table name). Entities belong to an integration and carry `dataTags` derived from their fields.

| name               | type               | description                                                               |
| ------------------ | ------------------ | ------------------------------------------------------------------------- |
| `id`               | string (UUID)      | Stable identifier for the entity.                                         |
| `label`            | string             | Display label (for example "Contacts").                                   |
| `descriptor`       | string             | Longer description of the entity.                                         |
| `nativeIdentifier` | string             | Original name at the source (for example `Contact` or `accounts`).        |
| `organizationId`   | string (UUID)      | Owning organization.                                                      |
| `integrationId`    | string (UUID)      | Integration that discovered this entity.                                  |
| `dataTags`         | array of string    | Tags associated with this entity.                                         |
| `createable`       | boolean            | Whether new records can be added to this entity.                          |
| `hidden`           | boolean            | When `true`, the entity is hidden from default listings. Default `false`. |
| `isFileEntity`     | boolean            | When `true`, the entity represents a file-based source. Default `false`.  |
| `createdAt`        | string (date-time) | When the entity was first cataloged.                                      |

The JSON below shows a typical entity response.

```json Entity overview
{
  "id": "e1b2c3d4-e5f6-7890-1234-567890abcdef",
  "label": "Contacts",
  "descriptor": "People associated with accounts",
  "nativeIdentifier": "Contact",
  "organizationId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "integrationId": "i1b2c3d4-e5f6-7890-1234-567890abcdef",
  "dataTags": ["pii", "crm"],
  "createable": true,
  "hidden": false,
  "isFileEntity": false,
  "createdAt": "2025-01-10T08:00:00Z"
}
```

### Data fields

A **data field** is a single column or property on an entity. Fields describe the data type (`scalarType`), whether the field can be searched, created, or updated at the source, and which data class (if any) has been assigned. Fields also carry an optional `defaultValue` and `fieldMetadata` for richer configuration such as picklist labels and values.

| name                        | type               | description                                                                           |
| --------------------------- | ------------------ | ------------------------------------------------------------------------------------- |
| `id`                        | string (UUID)      | Stable identifier for the field.                                                      |
| `entityId`                  | string (UUID)      | Entity this field belongs to.                                                         |
| `label`                     | string             | Display label (for example "Email Address").                                          |
| `descriptor`                | string             | Longer description of the field.                                                      |
| `nativeIdentifier`          | string             | Original name at the source (for example `email_address`).                            |
| `locator`                   | string             | Expression used to locate this field in the source data.                              |
| `scalarType`                | string             | Data type (for example `STRING`, `INTEGER`, `BOOLEAN`, `DATE`).                       |
| `collectionType`            | string (enum)      | `ORDERED_LIST`, `UNORDERED_LIST`, or `null` for scalar fields.                        |
| `searchable`                | boolean            | Whether this field can be used in search filters.                                     |
| `sortable`                  | boolean            | Whether this field can be used for sorting.                                           |
| `createable`                | boolean            | Whether a value can be provided when creating a record.                               |
| `updateable`                | boolean            | Whether an existing value can be updated.                                             |
| `nullable`                  | boolean            | Whether the field can be null.                                                        |
| `required`                  | boolean            | Whether the field must be provided in an insertion request.                           |
| `isPrimaryKey`              | boolean            | Whether the field is part of the entity's primary key.                                |
| `hidden`                    | boolean            | Whether the field is hidden from default listings.                                    |
| `isManaged`                 | boolean            | `true` when the field was added through the API rather than discovered at the source. |
| `dataClassId`               | string             | ID of the assigned data class, if any.                                                |
| `dataClassName`             | string             | Name of the assigned data class.                                                      |
| `isDataClassOverridden`     | boolean            | `true` when the data class was manually overridden from the auto-classified value.    |
| `originalDataClassId`       | string             | Original data class ID before an override.                                            |
| `defaultValue`              | object             | Default value configuration (see below).                                              |
| `fieldMetadata`             | object             | Extended metadata such as picklist labels and values.                                 |
| `caseSensitivityCapability` | string (enum)      | How the source handles case sensitivity for searches on this field.                   |
| `organizationId`            | string (UUID)      | Owning organization.                                                                  |
| `createdAt`                 | string (date-time) | When the field was first cataloged.                                                   |

#### Default values

The `defaultValue` object describes how a field is populated when no explicit value is given.

| name                | type   | description                                                                         |
| ------------------- | ------ | ----------------------------------------------------------------------------------- |
| `type`              | string | One of `UNKNOWN`, `LITERAL`, `CURRENT_DATE`, `CURRENT_TIMESTAMP`, or `RANDOM_UUID`. |
| `value`             | any    | Evaluated value when static evaluation is possible.                                 |
| `defaultExpression` | string | Original expression that evaluates to the default value.                            |

#### Case sensitivity

The `caseSensitivityCapability` enum indicates how the source handles case when searching this field.

* **`CASE_INSENSITIVE`** — searches ignore case with no performance penalty.
* **`CASE_INSENSITIVE_SLOW`** — case-insensitive searches are supported but may be slower.
* **`CASE_SENSITIVE_ONLY`** — searches are always case-sensitive.
* **`UNKNOWN`** — case behavior is not known.

#### Collection type

The `collectionType` enum indicates whether the field holds a single value or a collection.

* **`ORDERED_LIST`** — the field contains an ordered list of values.
* **`UNORDERED_LIST`** — the field contains an unordered set of values.
* **`null`** — the field is a standard scalar (non-collection) field.

### Data classes

A **data class** is a label that describes the *kind* of data a field holds — for example "Email Address," "Phone Number," or "Currency." When an integration syncs, Streamline auto-classifies fields using a machine-learning model. You can override the assigned class on any field if the automatic classification is not correct.

Data classes help with governance and presentation: workflow steps and the product UI use data classes to format values, apply validation, and flag sensitive data.

| name             | type               | description                                      |
| ---------------- | ------------------ | ------------------------------------------------ |
| `id`             | string             | Stable identifier for the data class.            |
| `name`           | string             | Display name (for example "Email Address").      |
| `description`    | string             | Longer explanation of what the class represents. |
| `category`       | string             | Grouping category (for example "Contact Info").  |
| `version`        | string             | Version of the data class definition.            |
| `organizationId` | string (UUID)      | Owning organization.                             |
| `createdAt`      | string (date-time) | When the data class was created.                 |
| `updatedAt`      | string (date-time) | When the data class was last updated.            |

## How-To Guides

**Let's explore common scenarios for working with the Data Catalog.**

### List entities

Use <Anchor label="list entities" target="_blank" href="https://developer.intellistack.com/reference/listentitiesv2">list entities</Anchor> to retrieve a paginated list of entities for your organization. You can filter by integration, label, or native identifier.

**GET** `/v1/data-catalog/entity`

| name               | type            | required | constraints                    | description                                         |
| ------------------ | --------------- | -------- | ------------------------------ | --------------------------------------------------- |
| `integrationId`    | string (query)  | no       | UUID                           | Filter entities by integration.                     |
| `label`            | string (query)  | no       | —                              | Filter entities by label (fuzzy match).             |
| `nativeIdentifier` | string (query)  | no       | —                              | Filter entities by native identifier (exact match). |
| `showHidden`       | boolean (query) | no       | default `false`                | When `true`, include hidden entities in results.    |
| `pageSize`         | integer (query) | no       | 1–1000, default 10             | Number of items per page.                           |
| `pageNumber`       | integer (query) | no       | 1-based, default 1             | Page number to return.                              |
| `sortFields`       | string (query)  | no       | default `id`                   | Field to sort results by.                           |
| `sortDirection`    | string (query)  | no       | `ASC` or `DESC`, default `ASC` | Sort direction.                                     |

The response below shows a single-page result with one entity.

```json List entities response
{
  "content": [
    {
      "id": "e1b2c3d4-e5f6-7890-1234-567890abcdef",
      "label": "Contacts",
      "descriptor": "People associated with accounts",
      "nativeIdentifier": "Contact",
      "organizationId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
      "integrationId": "i1b2c3d4-e5f6-7890-1234-567890abcdef",
      "dataTags": ["pii", "crm"],
      "createable": true,
      "hidden": false,
      "isFileEntity": false,
      "createdAt": "2025-01-10T08:00:00Z"
    }
  ],
  "page": {
    "size": 1,
    "pageSize": 10,
    "pageNumber": 1,
    "totalElements": 1,
    "totalPages": 1
  }
}
```

### Get an entity by ID

Use <Anchor label="get entity" target="_blank" href="https://developer.intellistack.com/reference/getentityv2">get entity</Anchor> to retrieve a single entity.

**GET** `/v1/data-catalog/entity/{entityId}`

| name       | type          | required | constraints | description         |
| ---------- | ------------- | -------- | ----------- | ------------------- |
| `entityId` | string (path) | yes      | UUID        | Entity to retrieve. |

```json Get entity by ID response
{
  "id": "e1b2c3d4-e5f6-7890-1234-567890abcdef",
  "label": "Contacts",
  "descriptor": "People associated with accounts",
  "nativeIdentifier": "Contact",
  "organizationId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "integrationId": "i1b2c3d4-e5f6-7890-1234-567890abcdef",
  "dataTags": ["pii", "crm"],
  "createable": true,
  "hidden": false,
  "isFileEntity": false,
  "createdAt": "2025-01-10T08:00:00Z"
}
```

### Batch lookup entities

Use <Anchor label="batch lookup entities" target="_blank" href="https://developer.intellistack.com/reference/getentitiesbatchbyidsv2">batch lookup entities</Anchor> to retrieve multiple entities at once. Send an array of entity IDs in the request body and receive a map keyed by entity ID.

**POST** `/v1/data-catalog/entity/batch`

The request body is a JSON array of UUID strings.

```json Batch lookup entities request
["e1b2c3d4-e5f6-7890-1234-567890abcdef", "e2b2c3d4-e5f6-7890-1234-567890abcdef"]
```

```json Batch lookup entities response
{
  "e1b2c3d4-e5f6-7890-1234-567890abcdef": {
    "id": "e1b2c3d4-e5f6-7890-1234-567890abcdef",
    "label": "Contacts",
    "descriptor": "People associated with accounts",
    "nativeIdentifier": "Contact",
    "organizationId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "integrationId": "i1b2c3d4-e5f6-7890-1234-567890abcdef",
    "dataTags": ["pii", "crm"],
    "createable": true,
    "createdAt": "2025-01-10T08:00:00Z"
  },
  "e2b2c3d4-e5f6-7890-1234-567890abcdef": {
    "id": "e2b2c3d4-e5f6-7890-1234-567890abcdef",
    "label": "Accounts",
    "descriptor": "Company or organization records",
    "nativeIdentifier": "Account",
    "organizationId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "integrationId": "i1b2c3d4-e5f6-7890-1234-567890abcdef",
    "dataTags": ["crm"],
    "createable": true,
    "createdAt": "2025-01-12T09:30:00Z"
  }
}
```

A few things to note:

* The response is a map, not an array. Each key is the entity ID you requested.
* If an ID does not match any entity, that key will be absent from the response.

### Get adjacent entities

Use <Anchor label="get adjacent entities" target="_blank" href="https://developer.intellistack.com/reference/getadjacentnodesv2">get adjacent entities</Anchor> to discover which entities are connected to a given entity through relationships. This is useful when building traversal routes for datasets.

**GET** `/v1/data-catalog/entity/{entityId}/adjacent`

| name       | type          | required | constraints | description                                         |
| ---------- | ------------- | -------- | ----------- | --------------------------------------------------- |
| `entityId` | string (path) | yes      | UUID        | Entity whose adjacent connections you want to find. |

The response is an array of adjacent nodes, each containing the target entity ID and the relationships that connect the two entities. Field IDs in the response are normalized to the queried entity's perspective: `sourceFieldId` is the field on the queried entity, and `targetFieldId` is the field on the adjacent entity.

```json Get adjacent entities response
[
  {
    "targetEntityId": "e2b2c3d4-e5f6-7890-1234-567890abcdef",
    "relationships": [
      {
        "linkId": "l1b2c3d4-e5f6-7890-1234-567890abcdef",
        "linkRelationship": [
          {
            "sourceFieldId": "f1b2c3d4-e5f6-7890-1234-567890abcdef",
            "targetFieldId": "f5b2c3d4-e5f6-7890-1234-567890abcdef"
          }
        ]
      }
    ]
  }
]
```

### List data fields

Use <Anchor label="list data fields" target="_blank" href="https://developer.intellistack.com/reference/listdatafieldsv2">list data fields</Anchor> to retrieve a paginated list of fields across all entities. You can filter by entity or label.

**GET** `/v1/data-catalog/data-fields`

| name               | type            | required | constraints                    | description                                    |
| ------------------ | --------------- | -------- | ------------------------------ | ---------------------------------------------- |
| `entityId`         | string (query)  | no       | UUID                           | Filter fields by entity.                       |
| `label`            | string (query)  | no       | —                              | Filter fields by label text.                   |
| `showHiddenFields` | boolean (query) | no       | default `false`                | When `true`, include hidden fields in results. |
| `pageSize`         | integer (query) | no       | 1–1000, default 50             | Number of items per page.                      |
| `pageNumber`       | integer (query) | no       | 1-based, default 1             | Page number to return.                         |
| `sortFields`       | string (query)  | no       | default `id`                   | Field to sort results by.                      |
| `sortDirection`    | string (query)  | no       | `ASC` or `DESC`, default `ASC` | Sort direction.                                |

The response below shows a single field.

```json List data fields response
{
  "content": [
    {
      "id": "f1b2c3d4-e5f6-7890-1234-567890abcdef",
      "entityId": "e1b2c3d4-e5f6-7890-1234-567890abcdef",
      "label": "Email Address",
      "descriptor": "Primary email for the contact",
      "nativeIdentifier": "email",
      "locator": "email",
      "scalarType": "STRING",
      "collectionType": null,
      "searchable": true,
      "sortable": true,
      "createable": true,
      "updateable": true,
      "nullable": true,
      "required": false,
      "isPrimaryKey": false,
      "hidden": false,
      "isManaged": false,
      "dataClassId": "dc-email-001",
      "dataClassName": "Email Address",
      "isDataClassOverridden": false,
      "organizationId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
      "createdAt": "2025-01-10T08:00:00Z"
    }
  ],
  "page": {
    "size": 1,
    "pageSize": 50,
    "pageNumber": 1,
    "totalElements": 1,
    "totalPages": 1
  }
}
```

### Get fields for an entity

Use <Anchor label="get entity fields" target="_blank" href="https://developer.intellistack.com/reference/getentityfieldsv2">get entity fields</Anchor> to retrieve all fields that belong to a specific entity. Unlike the paginated list above, this returns the full array for the entity.

**GET** `/v1/data-catalog/entity/{entityId}/data-fields`

| name               | type            | required | constraints     | description                                    |
| ------------------ | --------------- | -------- | --------------- | ---------------------------------------------- |
| `entityId`         | string (path)   | yes      | UUID            | Entity whose fields to retrieve.               |
| `showHiddenFields` | boolean (query) | no       | default `false` | When `true`, include hidden fields in results. |

```json Get fields for an entity response
[
  {
    "id": "f1b2c3d4-e5f6-7890-1234-567890abcdef",
    "entityId": "e1b2c3d4-e5f6-7890-1234-567890abcdef",
    "label": "Email Address",
    "nativeIdentifier": "email",
    "scalarType": "STRING",
    "searchable": true,
    "sortable": true,
    "createable": true,
    "updateable": true,
    "nullable": true,
    "required": false,
    "isPrimaryKey": false,
    "hidden": false,
    "isManaged": false,
    "dataClassId": "dc-email-001",
    "dataClassName": "Email Address",
    "isDataClassOverridden": false,
    "organizationId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "createdAt": "2025-01-10T08:00:00Z"
  },
  {
    "id": "f2b2c3d4-e5f6-7890-1234-567890abcdef",
    "entityId": "e1b2c3d4-e5f6-7890-1234-567890abcdef",
    "label": "First Name",
    "nativeIdentifier": "first_name",
    "scalarType": "STRING",
    "searchable": true,
    "sortable": true,
    "createable": true,
    "updateable": true,
    "nullable": true,
    "required": false,
    "isPrimaryKey": false,
    "hidden": false,
    "isManaged": false,
    "organizationId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "createdAt": "2025-01-10T08:00:00Z"
  }
]
```

<Callout icon="📘" theme="info">
  This endpoint returns a plain array — not a paginated envelope. Use it when you need every field for a known entity.
</Callout>

### Get a single field

Use <Anchor label="get field" target="_blank" href="https://developer.intellistack.com/reference/getfieldv2">get field</Anchor> to retrieve one field by its entity and field IDs.

**GET** `/v1/data-catalog/entity/{entityId}/data-fields/{fieldId}`

| name       | type          | required | constraints | description                 |
| ---------- | ------------- | -------- | ----------- | --------------------------- |
| `entityId` | string (path) | yes      | UUID        | Entity that owns the field. |
| `fieldId`  | string (path) | yes      | UUID        | Field to retrieve.          |

```json Get a single field response
{
  "id": "f1b2c3d4-e5f6-7890-1234-567890abcdef",
  "entityId": "e1b2c3d4-e5f6-7890-1234-567890abcdef",
  "label": "Email Address",
  "descriptor": "Primary email for the contact",
  "nativeIdentifier": "email",
  "locator": "email",
  "scalarType": "STRING",
  "collectionType": null,
  "searchable": true,
  "sortable": true,
  "createable": true,
  "updateable": true,
  "nullable": true,
  "required": false,
  "isPrimaryKey": false,
  "hidden": false,
  "isManaged": false,
  "dataClassId": "dc-email-001",
  "dataClassName": "Email Address",
  "isDataClassOverridden": false,
  "caseSensitivityCapability": "CASE_INSENSITIVE",
  "organizationId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "createdAt": "2025-01-10T08:00:00Z"
}
```

### Create a field on an entity

Use <Anchor label="create entity field" target="_blank" href="https://developer.intellistack.com/reference/createentityfieldv2">create entity field</Anchor> to add a field to an entity. Fields created through the API are intended for use in workflows when the source does not provide a needed column natively.

**POST** `/v1/data-catalog/entity/{entityId}/data-fields`

| name       | type          | required | constraints | description                 |
| ---------- | ------------- | -------- | ----------- | --------------------------- |
| `entityId` | string (path) | yes      | UUID        | Entity to add the field to. |

Send a field object in the request body. At minimum, provide `label` and `scalarType`.

```json Create a field request
{
  "label": "Preferred Language",
  "descriptor": "Language preference for communications",
  "scalarType": "STRING",
  "createable": true,
  "updateable": true,
  "nullable": true
}
```

The response returns the created field with its generated `id`.

```json Create a field response
{
  "id": "f3b2c3d4-e5f6-7890-1234-567890abcdef",
  "entityId": "e1b2c3d4-e5f6-7890-1234-567890abcdef",
  "label": "Preferred Language",
  "descriptor": "Language preference for communications",
  "scalarType": "STRING",
  "searchable": false,
  "createable": true,
  "updateable": true,
  "nullable": true,
  "isManaged": false,
  "organizationId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "createdAt": "2025-06-15T14:00:00Z"
}
```

<Callout icon="📘" theme="info">
  The API always sets `searchable` to `false` and `discoveredValues` to an empty array on created fields, regardless of what you send in the request body.
</Callout>

### Update a field

Use <Anchor label="update field" target="_blank" href="https://developer.intellistack.com/reference/updatefieldv2">update field</Anchor> to replace a field's definition. This is a full replacement (PUT), so include all properties you want to retain.

**PUT** `/v1/data-catalog/entity/{entityId}/data-fields/{fieldId}`

| name       | type          | required | constraints | description                 |
| ---------- | ------------- | -------- | ----------- | --------------------------- |
| `entityId` | string (path) | yes      | UUID        | Entity that owns the field. |
| `fieldId`  | string (path) | yes      | UUID        | Field to update.            |

```json Update a field request
{
  "label": "Preferred Language",
  "descriptor": "Updated description — language for outbound emails",
  "scalarType": "STRING",
  "createable": true,
  "updateable": true,
  "nullable": true
}
```

The response returns the updated field.

**Validation rules:**

* You cannot update a managed field. Attempting to do so returns a `400` with code `DATA-CAT-ILLEGAL-UPDATE`.
* You cannot set `isManaged` to `true` on an update request.

### Batch lookup fields by entity

Use <Anchor label="batch lookup fields" target="_blank" href="https://developer.intellistack.com/reference/getdatafieldsbatchbyidsv2">batch lookup fields</Anchor> to retrieve fields grouped by entity ID for multiple entities at once. Send an array of entity IDs and receive a map where each key is an entity ID and each value is the array of fields for that entity.

**POST** `/v1/data-catalog/data-fields/batch`

| name               | type            | required | constraints     | description                                    |
| ------------------ | --------------- | -------- | --------------- | ---------------------------------------------- |
| `showHiddenFields` | boolean (query) | no       | default `false` | When `true`, include hidden fields in results. |

```json Batch lookup fields request
["e1b2c3d4-e5f6-7890-1234-567890abcdef", "e2b2c3d4-e5f6-7890-1234-567890abcdef"]
```

```json Batch lookup fields response
{
  "e1b2c3d4-e5f6-7890-1234-567890abcdef": [
    {
      "id": "f1b2c3d4-e5f6-7890-1234-567890abcdef",
      "entityId": "e1b2c3d4-e5f6-7890-1234-567890abcdef",
      "label": "Email Address",
      "nativeIdentifier": "email",
      "scalarType": "STRING",
      "searchable": true,
      "isManaged": false,
      "organizationId": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
    }
  ],
  "e2b2c3d4-e5f6-7890-1234-567890abcdef": [
    {
      "id": "f4b2c3d4-e5f6-7890-1234-567890abcdef",
      "entityId": "e2b2c3d4-e5f6-7890-1234-567890abcdef",
      "label": "Account Name",
      "nativeIdentifier": "name",
      "scalarType": "STRING",
      "searchable": true,
      "isManaged": false,
      "organizationId": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
    }
  ]
}
```

### Update a field's data class

Use <Anchor label="update data class on field" target="_blank" href="https://developer.intellistack.com/reference/updatedataclassonfieldv2">update data class on field</Anchor> to override the auto-classified data class for a specific field. After this call, the field's `isDataClassOverridden` will be `true` and `originalDataClassId` will preserve the previous value.

**PUT** `/v1/data-catalog/entity/{entityId}/data-fields/{fieldId}/data-class-id`

| name       | type          | required | constraints | description                 |
| ---------- | ------------- | -------- | ----------- | --------------------------- |
| `entityId` | string (path) | yes      | UUID        | Entity that owns the field. |
| `fieldId`  | string (path) | yes      | UUID        | Field to reclassify.        |

```json Update data class request
{
  "dataClassId": "dc-phone-001"
}
```

The response returns the updated field with the new `dataClassId`, `isDataClassOverridden` set to `true`, and the previous class preserved in `originalDataClassId`.

```json Update data class response
{
  "id": "f1b2c3d4-e5f6-7890-1234-567890abcdef",
  "entityId": "e1b2c3d4-e5f6-7890-1234-567890abcdef",
  "label": "Phone",
  "nativeIdentifier": "phone",
  "scalarType": "STRING",
  "dataClassId": "dc-phone-001",
  "dataClassName": "Phone Number",
  "isDataClassOverridden": true,
  "originalDataClassId": "dc-text-001",
  "isManaged": false,
  "organizationId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "createdAt": "2025-01-10T08:00:00Z"
}
```

### Update field metadata

Use <Anchor label="update field metadata" target="_blank" href="https://developer.intellistack.com/reference/updatemetadataonfieldv2">update field metadata</Anchor> to set or replace extended metadata on a field — for example, picklist labels and values.

**POST** `/v1/data-catalog/entity/{entityId}/data-fields/{fieldId}/metadata`

| name       | type          | required | constraints | description                  |
| ---------- | ------------- | -------- | ----------- | ---------------------------- |
| `entityId` | string (path) | yes      | UUID        | Entity that owns the field.  |
| `fieldId`  | string (path) | yes      | UUID        | Field to update metadata on. |

The request body is a `fieldMetadata` object. The `labelsAndValuesConfig` property is required. The example below sets up a picklist with two options.

```json Update field metadata request
{
  "labelsAndValuesConfig": {
    "expandable": false,
    "labelAndValues": [
      {
        "label": "Active",
        "value": "active",
        "valueManaged": true
      },
      {
        "label": "Inactive",
        "value": "inactive",
        "valueManaged": true
      }
    ]
  }
}
```

A few things to note:

* `labelsAndValuesConfig` is required in the metadata object. Within it, `expandable` and `labelAndValues` are both required.
* Each item in `labelAndValues` requires `label`, `value`, and `valueManaged`.
* You can include a `translations` map on each item for multi-language support.
* The metadata object also supports `dateTimeOffsetConfig` (for datetime fields) with `storeStrategy` and `defaultOffset`.

The response returns the full updated field, including the new `fieldMetadata`.

### Get field settings

Use <Anchor label="get field settings" target="_blank" href="https://developer.intellistack.com/reference/getfieldsettings">get field settings</Anchor> to retrieve all effective settings for a data field. The effective value is either a user-provided override or the default derived from field metadata.

**GET** `/v1/data-catalog/entity/{entityId}/data-fields/{fieldId}/settings`

| name       | type          | required | constraints | description                 |
| ---------- | ------------- | -------- | ----------- | --------------------------- |
| `entityId` | string (path) | yes      | UUID        | Entity that owns the field. |
| `fieldId`  | string (path) | yes      | UUID        | Field to get settings for.  |

The response is a map of setting type to effective value. Settings that are not applicable to the field's type are omitted. Currently supported setting types are `datetime-strategy` (for DATETIME fields) and `collection-field` (for STRING scalar fields).

```json Get field settings response
{
  "datetime-strategy": {
    "storeStrategy": "UTC_ONLY",
    "defaultOffset": "+00:00",
    "allowedStrategies": ["UTC_ONLY", "DYNAMIC_OFFSET"]
  }
}
```

### Update field settings

Use <Anchor label="update field settings" target="_blank" href="https://developer.intellistack.com/reference/patchfieldsettings">update field settings</Anchor> to apply multiple settings to a data field in a single request.

**PATCH** `/v1/data-catalog/entity/{entityId}/data-fields/{fieldId}/settings`

| name       | type          | required | constraints | description                   |
| ---------- | ------------- | -------- | ----------- | ----------------------------- |
| `entityId` | string (path) | yes      | UUID        | Entity that owns the field.   |
| `fieldId`  | string (path) | yes      | UUID        | Field to update settings for. |

The request body is a map of setting type to configuration. Only settings included in the payload are modified. Set a key to `null` to remove a previously saved override (reverts to default from metadata).

```json Update datetime strategy setting
{
  "datetime-strategy": {
    "storeStrategy": "DYNAMIC_OFFSET",
    "defaultOffset": "-05:00"
  }
}
```

```json Configure a string field as a collection
{
  "collection-field": {
    "delimiter": ","
  }
}
```

A few things to note:

* All changes are applied atomically. If any setting fails validation, the entire transaction rolls back.
* **`datetime-strategy`** controls how datetime values with timezone offsets are stored. Applicable only to DATETIME fields. `storeStrategy` must be `UTC_ONLY` or `DYNAMIC_OFFSET`. `defaultOffset` must match the format `+HH:MM` or `-HH:MM`.
* **`collection-field`** marks a STRING scalar field as containing delimited collection data. `delimiter` must be exactly one character.
* A `403` response indicates the setting is not applicable to the field's type.

### List data classes

Use <Anchor label="list data classes" target="_blank" href="https://developer.intellistack.com/reference/listdataclassesv2">list data classes</Anchor> to retrieve all data classes available in your organization. These are the classification labels you can assign to fields.

**GET** `/v1/data-catalog/data-class`

| name            | type            | required | constraints                    | description               |
| --------------- | --------------- | -------- | ------------------------------ | ------------------------- |
| `pageSize`      | integer (query) | no       | 1–100, default 50              | Number of items per page. |
| `pageNumber`    | integer (query) | no       | 1-based, default 1             | Page number to return.    |
| `sortFields`    | string (query)  | no       | default `id`                   | Field to sort by.         |
| `sortDirection` | string (query)  | no       | `ASC` or `DESC`, default `ASC` | Sort direction.           |

```json List data classes response
{
  "content": [
    {
      "id": "dc-email-001",
      "name": "Email Address",
      "description": "An email address field",
      "category": "Contact Info",
      "version": "1.0",
      "organizationId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
      "createdAt": "2025-01-01T00:00:00Z",
      "updatedAt": "2025-01-01T00:00:00Z"
    },
    {
      "id": "dc-phone-001",
      "name": "Phone Number",
      "description": "A phone number field",
      "category": "Contact Info",
      "version": "1.0",
      "organizationId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
      "createdAt": "2025-01-01T00:00:00Z",
      "updatedAt": "2025-01-01T00:00:00Z"
    }
  ],
  "page": {
    "size": 2,
    "pageSize": 50,
    "pageNumber": 1,
    "totalElements": 2,
    "totalPages": 1
  }
}
```

### Get a data class by ID

Use <Anchor label="get data class" target="_blank" href="https://developer.intellistack.com/reference/getdataclassv2">get data class</Anchor> to retrieve a single data class.

**GET** `/v1/data-catalog/data-class/{id}`

| name | type          | required | constraints | description             |
| ---- | ------------- | -------- | ----------- | ----------------------- |
| `id` | string (path) | yes      | —           | Data class to retrieve. |

```json Get data class by ID response
{
  "id": "dc-email-001",
  "name": "Email Address",
  "description": "An email address field",
  "category": "Contact Info",
  "version": "1.0",
  "organizationId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "createdAt": "2025-01-01T00:00:00Z",
  "updatedAt": "2025-01-01T00:00:00Z"
}
```

## Error responses

Errors use an `ErrorEnvelope` shape with a top-level `message`, a `traceId` for support, and an `errors` array with per-error details. Each error in the array has a `code`, `title`, and `detail`.

When an entity or field does not exist, you will receive a `404`:

```json Resource not found
{
  "message": "No entity found with the specified ID",
  "traceId": "abc12345def67890",
  "errors": [
    {
      "code": "DATA-CAT-RESOURCE-NOT-FOUND",
      "title": "Resource Not Found",
      "detail": "No entity found with the specified ID"
    }
  ]
}
```

When a field update violates a validation rule (for example, trying to update a managed field), you will receive a `400`:

```json Illegal update
{
  "message": "Will not update field with ID: f1b2c3d4-... Field is managed.",
  "traceId": "abc12345def67890",
  "errors": [
    {
      "code": "DATA-CAT-ILLEGAL-UPDATE",
      "title": "Illegal Update Exception",
      "detail": "Will not update field with ID: f1b2c3d4-... Field is managed."
    }
  ]
}
```

When a request body fails validation, you will receive a `400`:

```json Validation failed
{
  "message": "Request body failed validation",
  "traceId": "abc12345def67890",
  "errors": [
    {
      "code": "DATA-CAT-VALIDATION-FAILED",
      "title": "Validation Failed",
      "detail": "Request body failed validation"
    }
  ]
}
```

<br />