Ataccama ONE Agentic Cloud Portal ONE Desktop ONE DQ&C ONE MDM ONE RDM ONE Runtime Server
User Community Service Desk Downloads

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.
Response example
{
  "meta": {
    "next": "MjA=",
    "total": 250
  },
  "data": [
    {
      "urn": "urn:ata:acme-corp:catalog:catalog-attribute:123e4567-e89b-12d3-a456-426614174000",
      "name": "customer_email",
      "dataType": "STRING",
      "columnType": "varchar",
      "description": "Customer email address",
      "catalogItemUrn": "urn:ata:acme-corp: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.
Response example
{
  "meta": {
    "next": "MjA=",
    "total": 150
  },
  "data": [
    {
      "urn": "urn:ata:acme-corp: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:acme-corp:todo:connection:b812d964-f94e-4be7-85c3-0073742ade09"
      },
      "source": {
        "urn": "urn:ata:acme-corp: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.
Response example
{
  "urn": "urn:ata:acme-corp: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:acme-corp:todo:connection:b812d964-f94e-4be7-85c3-0073742ade09"
  },
  "termAssignments": [
    {
      "termUrn": "urn:ata:acme-corp:catalog:term:1ede1262-f76b-4d00-9929-e92c15d8a5ba"
    }
  ],
  "locations": [
    {
      "name": "public"
    },
    {
      "name": "CustomerDB",
      "description": "This database contains all customer related data"
    }
  ],
  "source": {
    "urn": "urn:ata:acme-corp:catalog:source:28e3ca71-635b-43c4-9d1b-bc9cc642721f"
  },
  "effectiveStewardship": {
    "groupUrn": "urn:ata:acme-corp:iam:group:7c9e6679-7425-40de-944b-e07fc1f90ae7"
  },
  "primaryDqMonitor": {
    "urn": "urn:ata:acme-corp:data-quality:dq-monitor:3c9e6679-7425-40de-944b-e07fc1f90ae7"
  },
  "aliases": [
    {
      "type": "COLLIBRA_ASSET_ID",
      "value": "123e4567-e89b-12d3-a456-426614174000"
    }
  ]
}

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.

Filter options

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:acme-corp: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:acme-corp: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:acme-corp:iam:group:123e4567-e89b-12d3-a456-426614174000"
  }'
Request body fields
Field Type Description description

string or null

Updated description for the catalog item.

stewardshipGroupUrn

string or null

URN of the stewardship group responsible for this catalog item.

aliases

array or null

Alternative identifiers for the catalog item. The entire array is replaced if provided.

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
curl -X GET "https://{your-environment}.ataccama.one/api/catalog/v1/catalog-items?size=20" \
  -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. Update catalog item description
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"
  }'

Error handling

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

Status code Description

200 OK

Request successful.

204 No Content

Delete successful.

400 Bad Request

Invalid request parameters or body.

403 Forbidden

Insufficient permissions or catalog item is forbidden.

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

Was this page useful?