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 discovered data assets such as tables, files, and datasets that have been cataloged from your data sources.

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 attributes

Retrieve a paginated list of all published catalog 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 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`.
`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).

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"
    }
  ]
}

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`.
`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=isCritical,community,domains`. See Work with extra properties.

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"
      }
    }
  ]
}

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 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=isCritical,community,domains`. See Work with extra properties.

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": [
    {
      "name": "public"
    },
    {
      "name": "CustomerDB",
      "description": "This database contains all customer related data"
    }
  ],
  "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"
  },
  "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": {
    "isCritical": true,
    "community": "Customer Solutions",
    "domains": [
      "urn:ata:{your-tenant}:catalog:domain:10bae762-0000-8010-8000-000001eb0065"
    ]
  }
}

The extraProperties field is included only when you request specific properties using the extraProperties query parameter.

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.

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",
    "stewardshipGroupUrn": "urn:ata:{your-tenant}:iam:group:123e4567-e89b-12d3-a456-426614174000",
    "extraProperties": {
      "isCritical": 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.
`stewardshipGroupUrn`	string or null	No	URN of the stewardship group responsible for this catalog item.
`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).

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=isCritical,community" \
  -H "Authorization: Bearer $TOKEN"

# 7. 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": {
      "isCritical": true
    }
  }'

Work with extra properties

Catalog items support additional properties defined in the metadata model of your environment, for example, a criticality flag or a domain assignment configured for your organization. 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=isCritical,community,domains" \
  -H "Authorization: Bearer {access_token}"

To find which properties are available for catalog items, use the Metadata Model API to retrieve the catalogItem entity definition.

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

Error handling

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

Status code Description

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

200 OK

Request successful.

204 No Content

Delete successful.

400 Bad Request

Invalid request parameters or body.

403 Forbidden

Insufficient permissions to access the requested resource.

404 Not Found

Catalog item 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 terms for business glossary automation.
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 attributes

List catalog items

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

Error handling

Next steps