Catalog Items API

The REST API is currently in Early Access Preview. The API specification and endpoints might change before being marked as stable.

We recommend testing thoroughly and being prepared to adapt to potential changes in future releases.

The Catalog Items API allows you to programmatically access and manage catalog items in Ataccama ONE. Catalog items represent data assets such as tables, files, and datasets imported from your data sources, as well as SQL catalog items created using an SQL query. The API also covers catalog item attributes: the columns or fields of a catalog item, including the glossary terms assigned to them.

Catalog items imported from a source are organized in locations that mirror the structure of the source they were imported from, such as databases and schemas. SQL catalog items are placed in folders in the workspace of the source instead, which you manage through the Folders API. Through this API, you can also create SQL catalog items and update their queries.

Before using the Catalog Items API, configure authentication as described in API Authentication.

API base URL

All Catalog Items API endpoints are accessed through the following base URL:

https://{your-environment}.ataccama.one/api/catalog/v1

Replace {your-environment} with your environment identifier from the Ataccama Cloud Portal.

List catalog item attributes

Retrieve a paginated list of all published catalog item attributes.

Request

curl -X GET "https://{your-environment}.ataccama.one/api/catalog/v1/attributes?size=20" \
  -H "Authorization: Bearer {access_token}"

Query parameters
Parameter	Type	Required	Description
`after`	string	No	Cursor for forward pagination.
`size`	integer	No	Number of catalog item attributes to return. Default: `20`. Max: `100`.
`catalogItemUrn`	string	No	Filter attributes by parent catalog item URN. For example: `urn:ata:{your-tenant}:catalog:catalog-item:123e4567-e89b-12d3-a456-426614174000`.
`searchQuery`	string	No	Full-text query matched against all string properties of the catalog item attribute, such as `name` and `description`.
`name`	string	No	Filter catalog item attributes by exact match on the name.
`sort`	string	No	Comma-separated field names for sorting results. Prefix a field with `-` to sort descending. Supported fields: `name`. Examples: `?sort=name` (ascending), `?sort=-name` (descending).
`extraProperties`	string	No	Comma-separated list of extra property names to include in the `extraProperties` field of the response. When omitted, no extra properties are returned. Example: `?extraProperties=isPii,sensitivity`. See Work with extra properties.
`include`	string	No	Comma-separated list of related resources to include in the response. When omitted, none of them are returned. Supported values: `effectiveCriticality`. Example: `?include=effectiveCriticality`. See Retrieve criticality.

Response example

{
  "meta": {
    "next": "MjA=",
    "total": 250
  },
  "data": [
    {
      "urn": "urn:ata:{your-tenant}:catalog:catalog-attribute:123e4567-e89b-12d3-a456-426614174000",
      "name": "customer_email",
      "dataType": "STRING",
      "columnType": "varchar",
      "description": "Customer email address",
      "catalogItemUrn": "urn:ata:{your-tenant}:catalog:catalog-item:fde84300-7a83-4d24-8c88-30ada80b0b54",
      "termAssignments": [
        {
          "termUrn": "urn:ata:{your-tenant}:catalog:term:3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "source": "MANUAL"
        }
      ]
    }
  ]
}

The termAssignments and termDetectionDenylist fields list the terms assigned to the attribute and the terms that term detection must not assign to it. To manage them, use the Term Assignments API.

Get a catalog item attribute

Retrieve detailed information about a specific catalog item attribute by its URN, including the terms assigned to it.

Request

curl -X GET "https://{your-environment}.ataccama.one/api/catalog/v1/attributes/{urn}" \
  -H "Authorization: Bearer {access_token}"

Path parameters
Parameter	Type	Required	Description
`urn`	string	Yes	URN identifier of the catalog item attribute. For example: `urn:ata:{your-tenant}:catalog:catalog-attribute:123e4567-e89b-12d3-a456-426614174000`.

Query parameters
Parameter	Type	Required	Description
`extraProperties`	string	No	Comma-separated list of extra property names to include in the `extraProperties` field of the response. When omitted, no extra properties are returned. Example: `?extraProperties=isPii,sensitivity`. See Work with extra properties.
`include`	string	No	Comma-separated list of related resources to include in the response. When omitted, none of them are returned. Supported values: `effectiveCriticality`. Example: `?include=effectiveCriticality`. See Retrieve criticality.

Response example

{
  "urn": "urn:ata:{your-tenant}:catalog:catalog-attribute:123e4567-e89b-12d3-a456-426614174000",
  "name": "customer_email",
  "dataType": "STRING",
  "columnType": "varchar",
  "description": "Customer email address",
  "catalogItemUrn": "urn:ata:{your-tenant}:catalog:catalog-item:fde84300-7a83-4d24-8c88-30ada80b0b54",
  "termAssignments": [
    {
      "termUrn": "urn:ata:{your-tenant}:catalog:term:3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "source": "MANUAL"
    },
    {
      "termUrn": "urn:ata:{your-tenant}:catalog:term:1ede1262-f76b-4d00-9929-e92c15d8a5ba",
      "source": "TERM_DETECTION"
    }
  ],
  "termDetectionDenylist": [
    {
      "termUrn": "urn:ata:{your-tenant}:catalog:term:7c9e6679-7425-40de-944b-e07fc1f90ae7"
    }
  ],
  "effectiveCriticality": {
    "isCritical": true
  },
  "extraProperties": {
    "isPii": true,
    "sensitivity": "HIGH"
  }
}

The extraProperties and effectiveCriticality fields are included only when you request them using the extraProperties and include query parameters. For the termAssignments and termDetectionDenylist fields, see the Term Assignments API.

Update a catalog item attribute

Update the description or extra properties of a catalog item attribute using JSON Merge Patch (RFC 7386). You only need to specify the fields you want to change.

Request

curl -X PATCH "https://{your-environment}.ataccama.one/api/catalog/v1/attributes/{urn}" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Primary email address of the customer",
    "extraProperties": {
      "isPii": true,
      "sensitivity": "HIGH"
    }
  }'

Request body fields
Field	Type	Required	Description
`description`	string or null	No	Updated description of the catalog item attribute.
`extraProperties`	object or null	No	Extra property values to update, as a map of property names and values. Only the properties listed in the body are modified. To clear a value, set a scalar property to `null` or a reference array property to `[]`. See Work with extra properties.

The response returns the updated catalog item attribute with all fields (same structure as Get a catalog item attribute).

Assigned terms cannot be changed through this endpoint. To assign or unassign terms, use the Term Assignments API.

List catalog items

Retrieve a paginated list of all published catalog items.

Request

curl -X GET "https://{your-environment}.ataccama.one/api/catalog/v1/catalog-items?size=20" \
  -H "Authorization: Bearer {access_token}"

Query parameters
Parameter	Type	Required	Description
`after`	string	No	Cursor for forward pagination.
`size`	integer	No	Number of catalog items to return. Default: `20`. Max: `100`.
`parentUrn`	string	No	Filter catalog items by their direct parent: a folder URN for catalog items placed in folders, such as SQL catalog items, or a location URN for catalog items imported from a source. Pass `null` to return only catalog items that aren’t placed in any location or folder, such as transformation catalog items. When omitted, catalog items are not filtered by parent. Example: `?parentUrn=urn:ata:{your-tenant}:catalog:folder:9b1c4d2e-6f3a-4c5b-8d7e-1a2b3c4d5e6f`. See Folders API.
`searchQuery`	string	No	Full-text query matched against all string properties of the catalog item, such as `name` and `description`.
`name`	string	No	Filter catalog items by exact match on the name.
`sort`	string	No	Comma-separated field names for sorting results. Prefix a field with `-` to sort descending. Supported fields: `name`. Examples: `?sort=name` (ascending), `?sort=-name` (descending).
`extraProperties`	string	No	Comma-separated list of extra property names to include in the `extraProperties` field of the response. When omitted, no extra properties are returned. Example: `?extraProperties=isPii,community,domains`. See Work with extra properties.
`include`	string	No	Comma-separated list of related resources to include in the response. When omitted, none of them are returned. Supported values: `effectiveCriticality`, `effectiveStewardship`. Example: `?include=effectiveCriticality`. See Retrieve criticality and Retrieve effective stewardship.

Response example

{
  "meta": {
    "next": "MjA=",
    "total": 150
  },
  "data": [
    {
      "urn": "urn:ata:{your-tenant}:catalog:catalog-item:fde84300-7a83-4d24-8c88-30ada80b0b54",
      "name": "customers",
      "description": "This table contains information about our customers",
      "originPath": "public/customers",
      "connection": {
        "urn": "urn:ata:{your-tenant}:processing:connection:b812d964-f94e-4be7-85c3-0073742ade09"
      },
      "source": {
        "urn": "urn:ata:{your-tenant}:catalog:source:28e3ca71-635b-43c4-9d1b-bc9cc642721f"
      }
    }
  ]
}

Create an SQL catalog item

Create a catalog item using an SQL query and place it in a folder. The catalog item is published immediately.

Only SQL catalog items can be created through this endpoint. Catalog items imported from a source are created by documentation flows.

Request

curl -X POST "https://{your-environment}.ataccama.one/api/catalog/v1/catalog-items" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "dslQueryCatalogItem",
    "name": "high_value_customers",
    "description": "Customers with a lifetime value over 10k",
    "connectionUrn": "urn:ata:{your-tenant}:processing:connection:b812d964-f94e-4be7-85c3-0073742ade09",
    "query": "SELECT * FROM customers WHERE lifetime_value > 10000",
    "folderUrn": "urn:ata:{your-tenant}:catalog:folder:9b1c4d2e-6f3a-4c5b-8d7e-1a2b3c4d5e6f"
  }'

Request body fields
Field	Type	Required	Description
`type`	string	Yes	Type of the catalog item to create. The only supported value is `dslQueryCatalogItem`, which creates an SQL catalog item.
`name`	string	Yes	Name of the catalog item.
`description`	string	No	Description of the catalog item.
`connectionUrn`	string	Yes	URN of the connection the SQL query runs against. The connection must belong to the same source as the folder.
`query`	string	Yes	SQL query used to create the catalog item.
`folderUrn`	string	Yes	URN of the folder the catalog item is placed in. The folder can’t be changed after the catalog item is created. To find or create folders, use the Folders API.

The response returns the HTTP status code 201 Created with the created catalog item, including its generated URN (same structure as Get a catalog item).

Response example

{
  "urn": "urn:ata:{your-tenant}:catalog:catalog-item:a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "name": "high_value_customers",
  "description": "Customers with a lifetime value over 10k",
  "connection": {
    "urn": "urn:ata:{your-tenant}:processing:connection:b812d964-f94e-4be7-85c3-0073742ade09"
  },
  "folders": [
    {
      "urn": "urn:ata:{your-tenant}:catalog:folder:9b1c4d2e-6f3a-4c5b-8d7e-1a2b3c4d5e6f",
      "name": "Revenue"
    }
  ],
  "source": {
    "urn": "urn:ata:{your-tenant}:catalog:source:28e3ca71-635b-43c4-9d1b-bc9cc642721f"
  }
}

Creating the catalog item also runs the query on the connection to import the catalog item attributes from the query result. If the import fails, the request still succeeds and the catalog item is created without attributes. To verify the result, retrieve the catalog item attributes using the [List catalog attributes] endpoint.

Get a catalog item

Retrieve detailed information about a specific catalog item by its URN.

Catalog item attributes are not included in the catalog item response. To retrieve attributes for a catalog item, use the List catalog item attributes endpoint with the catalogItemUrn query parameter.

Request

curl -X GET "https://{your-environment}.ataccama.one/api/catalog/v1/catalog-items/{urn}" \
  -H "Authorization: Bearer {access_token}"

Path parameters
Parameter	Type	Required	Description
`urn`	string	Yes	URN identifier of the catalog item. For example: `urn:ata:{your-tenant}:catalog:catalog-item:fde84300-7a83-4d24-8c88-30ada80b0b54`.

Query parameters
Parameter	Type	Required	Description
`extraProperties`	string	No	Comma-separated list of extra property names to include in the `extraProperties` field of the response. When omitted, no extra properties are returned. Example: `?extraProperties=isPii,community,domains`. See Work with extra properties.
`include`	string	No	Comma-separated list of related resources to include in the response. When omitted, none of them are returned. Supported values: `effectiveCriticality`, `effectiveStewardship`. Example: `?include=effectiveCriticality`. See Retrieve criticality and Retrieve effective stewardship.

Response example

{
  "urn": "urn:ata:{your-tenant}:catalog:catalog-item:fde84300-7a83-4d24-8c88-30ada80b0b54",
  "name": "customers",
  "description": "This table contains information about our customers",
  "originPath": "public/customers",
  "connection": {
    "urn": "urn:ata:{your-tenant}:processing:connection:b812d964-f94e-4be7-85c3-0073742ade09"
  },
  "termAssignments": [
    {
      "termUrn": "urn:ata:{your-tenant}:catalog:term:1ede1262-f76b-4d00-9929-e92c15d8a5ba"
    }
  ],
  "locations": [
    {
      "urn": "urn:ata:{your-tenant}:catalog:location:2b9d1f0a-3c4e-4a5b-9c8d-7e6f5a4b3c2d",
      "name": "public"
    },
    {
      "urn": "urn:ata:{your-tenant}:catalog:location:3c0e2a1b-4d5f-4b6c-8d9e-1f2a3b4c5d6e",
      "name": "CustomerDB"
    }
  ],
  "source": {
    "urn": "urn:ata:{your-tenant}:catalog:source:28e3ca71-635b-43c4-9d1b-bc9cc642721f"
  },
  "effectiveStewardship": {
    "groupUrn": "urn:ata:{your-tenant}:iam:group:7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "originUrn": "urn:ata:{your-tenant}:catalog:source:28e3ca71-635b-43c4-9d1b-bc9cc642721f"
  },
  "effectiveCriticality": {
    "isCritical": true
  },
  "primaryDqMonitor": {
    "urn": "urn:ata:{your-tenant}:data-quality:dq-monitor:3c9e6679-7425-40de-944b-e07fc1f90ae7"
  },
  "aliases": [
    {
      "type": "COLLIBRA_ASSET_ID",
      "value": "123e4567-e89b-12d3-a456-426614174000"
    }
  ],
  "extraProperties": {
    "isPii": true,
    "community": "Customer Solutions",
    "domains": [
      "urn:ata:{your-tenant}:catalog:domain:10bae762-0000-8010-8000-000001eb0065"
    ]
  }
}

The extraProperties, effectiveCriticality, and effectiveStewardship fields are included only when you request them using the extraProperties and include query parameters.

The locations and folders fields describe where the catalog item is placed in the catalog hierarchy, ordered from the closest parent to the root:

locations: The location hierarchy mirroring the structure of the source the catalog item was imported from, such as a schema and a database. Populated for catalog items imported from a source.
folders: The folder hierarchy in the workspace of the source. Populated for catalog items placed in folders, such as SQL catalog items. See Folders API.

The response doesn’t include the SQL query of SQL catalog items. To retrieve the query, use the Generic Metadata Entities API to list the dslQuery entity of the catalog item:

curl -X GET "https://{your-environment}.ataccama.one/api/catalog/v1/entities?entityType=dslQuery&parentUrn={urn}&properties=query" \
  -H "Authorization: Bearer {access_token}"

Response example

{
  "meta": {
    "total": 1
  },
  "data": [
    {
      "urn": "urn:ata:{your-tenant}:catalog:dsl-query:c3d4e5f6-7a8b-4c9d-8e1f-2a3b4c5d6e7f",
      "parentUrn": "urn:ata:{your-tenant}:catalog:catalog-item:a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "rootSuperType": "dslQuery",
      "concreteType": "dslQuery",
      "properties": {
        "query": "SELECT * FROM customers WHERE lifetime_value > 10000"
      }
    }
  ]
}

To change the query, use the Update a catalog item endpoint.

Filter catalog items

Filter catalog items based on complex criteria to find specific data assets.

Request

curl -X POST "https://{your-environment}.ataccama.one/api/catalog/v1/catalog-items/filter" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "name": {
        "contains": "customer"
      }
    }
  }'

Query parameters
Parameter	Type	Required	Description
`after`	string	No	Cursor for forward pagination.
`size`	integer	No	Number of catalog items to return. Default: `20`. Max: `100`.
`sort`	string	No	Comma-separated field names for sorting results. Prefix a field with `-` to sort descending. Supported fields: `name`. Examples: `?sort=name` (ascending), `?sort=-name` (descending).
`extraProperties`	string	No	Comma-separated list of extra property names to include in the `extraProperties` field of each returned catalog item. When omitted, no extra properties are returned. Extra properties cannot be used as filter criteria. See Work with extra properties.
`include`	string	No	Comma-separated list of related resources to include in the response for each returned catalog item. When omitted, none of them are returned. Supported values: `effectiveCriticality`, `effectiveStewardship`. Example: `?include=effectiveCriticality`. See Retrieve criticality and Retrieve effective stewardship.

The filter supports complex queries using logical and comparison operators.

Logical operators

and: All conditions must match.
or: At least one condition must match.

Field filters

You can filter by the following fields:

urn: Catalog item URN.
name: Catalog item name.
description: Catalog item description.
originPath: Origin path in the source system.
connection: Filter by connection URN or name.
source: Filter by source URN or name.
aliases: Filter by alias type and value.
attributes: Filter by attribute properties.
termAssignments: Filter by assigned terms.

String operators

For string fields, use these operators:

contains / notContains: Substring match.
equals / notEquals: Exact match.
in / notIn: Match any value in array.
isNull / isNotNull: Check if field is null.

Example: Filter by name

{
  "filter": {
    "name": {
      "in": ["customer", "customers"]
    }
  }
}

Example: Filter by source

{
  "filter": {
    "source": {
      "name": {
        "contains": "Sales"
      }
    }
  }
}

Example: Filter by assigned terms

{
  "filter": {
    "termAssignments": {
      "any": {
        "termUrn": {
          "in": ["urn:ata:{your-tenant}:catalog:term:9e106021-3655-463a-8884-6c7c6c315548"]
        }
      }
    }
  }
}

Example: Complex filter with logical operators

{
  "filter": {
    "or": [
      {
        "name": {
          "contains": "customer"
        }
      },
      {
        "and": [
          {
            "source": {
              "name": {
                "contains": "Sales"
              }
            }
          },
          {
            "termAssignments": {
              "any": {
                "termUrn": {
                  "in": ["urn:ata:{your-tenant}:catalog:term:9e106021-3655-463a-8884-6c7c6c315548"]
                }
              }
            }
          }
        ]
      }
    ]
  }
}

Update a catalog item

Update specific fields of a catalog item using JSON Merge Patch (RFC 7386). You only need to specify the fields you want to change.

Request

curl -X PATCH "https://{your-environment}.ataccama.one/api/catalog/v1/catalog-items/{urn}" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated description for the customer table",
    "extraProperties": {
      "isPii": true,
      "community": "Customer Solutions",
      "domains": [
        "urn:ata:{your-tenant}:catalog:domain:10bae762-0000-8010-8000-000001eb0065"
      ]
    }
  }'

Request body fields
Field	Type	Required	Description
`description`	string or null	No	Updated description for the catalog item.
`query`	string	No	Updated SQL query of an SQL catalog item. Applicable only to SQL catalog items.
`aliases`	array or null	No	Alternative identifiers for the catalog item. The entire array is replaced if provided.
`extraProperties`	object or null	No	Extra property values to update, as a map of property names and values. Only the properties listed in the body are modified. To clear a value, set a scalar property to `null` or a reference array property to `[]`. See Work with extra properties.

The response returns the updated catalog item with all fields (same structure as Get a catalog item).

The type and folder of an SQL catalog item can’t be changed.

Stewardship cannot be updated through this endpoint. To change the group responsible for the catalog item, use the Stewardship API.

Delete a catalog item

Delete a catalog item from the catalog.

Request

curl -X DELETE "https://{your-environment}.ataccama.one/api/catalog/v1/catalog-items/{urn}" \
  -H "Authorization: Bearer {access_token}"

The response returns the HTTP status code 204 No Content on success.

Complete example

Here’s a complete example using cURL to work with catalog items:

# 1. Obtain access token
TOKEN=$(curl -s -X POST "https://{your-environment}.ataccama.one/auth/realms/{your-realm}/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id={your-client-id}" \
  -d "client_secret={your-client-secret}" \
  | jq -r '.access_token')

# 2. List all catalog items (sorted by name)
curl -X GET "https://{your-environment}.ataccama.one/api/catalog/v1/catalog-items?size=20&sort=name" \
  -H "Authorization: Bearer $TOKEN"

# 3. Filter catalog items by name
curl -X POST "https://{your-environment}.ataccama.one/api/catalog/v1/catalog-items/filter" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "name": {
        "contains": "customer"
      }
    }
  }'

# 4. Get a specific catalog item
CATALOG_ITEM_URN="urn:ata:{your-tenant}:catalog:catalog-item:fde84300-7a83-4d24-8c88-30ada80b0b54"
curl -X GET "https://{your-environment}.ataccama.one/api/catalog/v1/catalog-items/$CATALOG_ITEM_URN" \
  -H "Authorization: Bearer $TOKEN"

# 5. Get attributes for the catalog item
curl -X GET "https://{your-environment}.ataccama.one/api/catalog/v1/attributes?catalogItemUrn=$CATALOG_ITEM_URN" \
  -H "Authorization: Bearer $TOKEN"

# 6. Get the catalog item with selected extra properties
curl -X GET "https://{your-environment}.ataccama.one/api/catalog/v1/catalog-items/$CATALOG_ITEM_URN?extraProperties=isPii,community" \
  -H "Authorization: Bearer $TOKEN"

# 7. Get the catalog item with its effective criticality
curl -X GET "https://{your-environment}.ataccama.one/api/catalog/v1/catalog-items/$CATALOG_ITEM_URN?include=effectiveCriticality" \
  -H "Authorization: Bearer $TOKEN"

# 8. Update catalog item description and extra properties
curl -X PATCH "https://{your-environment}.ataccama.one/api/catalog/v1/catalog-items/$CATALOG_ITEM_URN" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated customer data table",
    "extraProperties": {
      "isPii": true
    }
  }'

# 9. Create an SQL catalog item in a folder
curl -X POST "https://{your-environment}.ataccama.one/api/catalog/v1/catalog-items" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "dslQueryCatalogItem",
    "name": "high_value_customers",
    "connectionUrn": "urn:ata:{your-tenant}:processing:connection:b812d964-f94e-4be7-85c3-0073742ade09",
    "query": "SELECT * FROM customers WHERE lifetime_value > 10000",
    "folderUrn": "urn:ata:{your-tenant}:catalog:folder:9b1c4d2e-6f3a-4c5b-8d7e-1a2b3c4d5e6f"
  }'

Work with extra properties

Catalog items and catalog item attributes support additional properties defined in the metadata model of your environment, for example, a data classification flag or the data domains an asset belongs to. The API refers to these properties as extra properties.

Extra properties are returned in the extraProperties field of the response, as a map of property names and values. Supported values are scalars (string, number, or Boolean), URN references, arrays of those, or null.

Extra properties are not included in responses by default. To retrieve them, list the property names you need in the extraProperties query parameter. The property names must exactly match the property names defined in the metadata model.

curl -X GET "https://{your-environment}.ataccama.one/api/catalog/v1/catalog-items/{urn}?extraProperties=isPii,community,domains" \
  -H "Authorization: Bearer {access_token}"

To find which properties are available, use the Metadata Model API to retrieve the catalogItem or attribute entity definition.

To change extra property values, use the Update a catalog item or Update a catalog item attribute endpoint. Filtering by extra property values is not supported.

Criticality is not an extra property. To retrieve it, use the include query parameter instead. See Retrieve criticality.

Retrieve criticality

Criticality marks catalog items and attributes as critical data elements (CDEs). An asset can be marked critical directly, or it can inherit criticality from related assets: an attribute from the terms assigned to it, and a catalog item from its attributes. To learn how criticality is set and how it propagates, see Define Critical Data Elements.

Criticality is not returned by default. To retrieve it, add include=effectiveCriticality to the List catalog items, Filter catalog items, Get a catalog item, List catalog item attributes, or Get a catalog item attribute request:

curl -X GET "https://{your-environment}.ataccama.one/api/catalog/v1/catalog-items/{urn}?include=effectiveCriticality" \
  -H "Authorization: Bearer {access_token}"

The response then contains the effectiveCriticality field with the criticality that applies to the asset, whether it was set directly or inherited:

{
  "urn": "urn:ata:{your-tenant}:catalog:catalog-item:fde84300-7a83-4d24-8c88-30ada80b0b54",
  "name": "customers",
  "effectiveCriticality": {
    "isCritical": true
  }
}

The field has one of the following values:

{"isCritical": true}: The asset is critical.
{"isCritical": false}: The asset is not critical.
null: No criticality is set on the asset and none is inherited.

The response does not show which asset the criticality is inherited from.

Resolving criticality takes additional processing time, so request it only when you need it. You cannot set criticality or filter by it through the Catalog Items API.

Error handling

The API returns standard HTTP status codes and problem details for errors:

Status code Description

Status code	Description
`200 OK`	Request successful.
`201 Created`	Catalog item created successfully.
`204 No Content`	Catalog item deleted successfully.
`400 Bad Request`	Invalid request parameters or body.
`403 Forbidden`	Insufficient permissions to access the requested resource.
`404 Not Found`	Catalog item or attribute does not exist.

200 OK

Request successful.

201 Created

Catalog item created successfully.

204 No Content

Catalog item deleted successfully.

400 Bad Request

Invalid request parameters or body.

403 Forbidden

Insufficient permissions to access the requested resource.

404 Not Found

Catalog item or attribute does not exist.

Error response example

{
  "type": "RESOURCE_NOT_FOUND",
  "title": "Resource Not Found",
  "detail": "Catalog item with ID 'fde84300-7a83-4d24-8c88-30ada80b0b54' was not found"
}

Next steps

Learn about managing folders to organize SQL catalog items in the workspace of a source.
Learn how to create SQL catalog items in the web application.
Learn about managing terms for business glossary automation.
Use the Term Assignments API to assign terms to catalog item attributes in bulk.
Learn about managing stewardship to change which group is responsible for your data assets.
Use the Metadata Model API to discover the extra properties available for catalog items in your environment.
Learn about documentation flows to trigger metadata import, term detection, and data quality evaluation on your connections.
Download the Catalog API OpenAPI specification for detailed API reference.

Was this page useful?

Catalog Items API

API base URL

List catalog item attributes

Get a catalog item attribute

Update a catalog item attribute

List catalog items

Create an SQL catalog item

Get a catalog item

Filter catalog items

Filter options

Logical operators

Field filters

String operators

Update a catalog item

Delete a catalog item

Complete example

Work with extra properties

Retrieve criticality

Error handling

Next steps