Generic Metadata Entities 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 Generic Metadata Entities API allows you to programmatically create, read, update, and delete entities of any type defined in the metadata model. While the typed APIs, such as the Catalog Items API and the Terms API, expose a fixed set of fields for one entity type, the Generic Metadata Entities API works with any entity type and any of its properties.

The main purpose of this API is working with custom entity types defined in your metadata model. You can also use it to work with built-in entity types that don’t have a dedicated API yet. For entity types with a dedicated API, such as catalog items and terms, use the typed endpoints instead.

Before using the Generic Metadata Entities API, configure authentication as described in API Authentication.

API base URL

All Generic Metadata Entities 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.

How entities are structured

Every entity returned by this API has the same envelope:

urn: The unique identifier of the entity.
parentUrn: The URN of the parent entity. null when the entity is attached directly to the metadata root.
rootSuperType: The root super type of the entity in the metadata model type hierarchy, for example, term.
concreteType: The concrete (most specific) type of the entity, for example, businessTerm.
properties: A map of properties defined for the entity in the metadata model. Only the properties you explicitly request through the properties query parameter are included.

Property names must match the metadata model exactly. Supported property value types are scalars (string, number, Boolean), URN references, arrays of those, or null.

The available entity types and their properties are defined by the metadata model of your environment, including any customizations. To discover which entity types exist and which properties each type supports, use the Metadata Model API. The examples on this page use the built-in businessTerm entity type because its default properties make the examples easy to follow. The requests are identical for any entity type, including custom ones.

List entities

Retrieve a paginated list of entities of a given type.

Request

curl -X GET "https://{your-environment}.ataccama.one/api/catalog/v1/entities?entityType=businessTerm&properties=name,abbreviation&size=20" \
  -H "Authorization: Bearer {access_token}"

Query parameters
Parameter	Type	Required	Description
`entityType`	string	Yes	Entity type to list, matching the value of `rootSuperType` or `concreteType` returned in entity responses. The available types are defined in the metadata model. Examples: `term`, `businessTerm`, `catalogItem`.
`parentUrn`	string	No	Filter entities by parent URN. When omitted, entities are not filtered by parent.
`after`	string	No	Cursor for forward pagination.
`size`	integer	No	Number of entities to return. Default: `20`. Max: `100`.
`sort`	string	No	Comma-separated property names for sorting results. Prefix a field with `-` to sort descending. Any scalar property defined for the entity in the metadata model can be used as a sort key. Examples: `?sort=name` (ascending), `?sort=-name,abbreviation` (name descending, then abbreviation ascending).
`properties`	string	No	Comma-separated list of property names to include in the `properties` field of the response. When omitted, no properties are returned. Property names must match the metadata model exactly. Only scalar properties, references, and their arrays are supported. Example: `?properties=name,abbreviation`.

Response example

{
  "meta": {
    "next": "MjA=",
    "total": 150
  },
  "data": [
    {
      "urn": "urn:ata:{your-tenant}:catalog:term:123e4567-e89b-12d3-a456-426614174000",
      "parentUrn": null,
      "rootSuperType": "term",
      "concreteType": "businessTerm",
      "properties": {
        "name": "Supplier",
        "abbreviation": "SUP"
      }
    }
  ]
}

Create an entity

Create a new entity of any concrete type defined in the metadata model.

Request

curl -X POST "https://{your-environment}.ataccama.one/api/catalog/v1/entities" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "concreteType": "businessTerm",
    "parentProperty": "terms",
    "properties": {
      "name": "PII",
      "abbreviation": "PII",
      "securityClassification": "Confidential"
    }
  }'

Request body fields
Field	Type	Required	Description
`concreteType`	string	Yes	The concrete (most specific) type of the entity in the metadata model. For example: `businessTerm`.
`parentUrn`	string or null	No	URN of the parent entity under which the new entity is created. Omit or pass `null` to create the entity directly under the metadata root.
`parentProperty`	string	Yes	Name of the property on the parent that holds child entities of this type, as defined in the metadata model. For example: `terms`.
`properties`	object	No	A map of properties to set on the new entity, keyed by property name as defined in the metadata model.

The response returns the HTTP status code 201 Created with the created entity.

Get an entity

Retrieve an entity by its URN.

Request

curl -X GET "https://{your-environment}.ataccama.one/api/catalog/v1/entities/{urn}?properties=name,abbreviation,securityClassification" \
  -H "Authorization: Bearer {access_token}"

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

Query parameters
Parameter	Type	Required	Description
`properties`	string	No	Comma-separated list of property names to include in the `properties` field of the response. When omitted, no properties are returned.

Response example

{
  "urn": "urn:ata:{your-tenant}:catalog:term:123e4567-e89b-12d3-a456-426614174000",
  "parentUrn": null,
  "rootSuperType": "term",
  "concreteType": "businessTerm",
  "properties": {
    "name": "Supplier",
    "abbreviation": "SUP",
    "securityClassification": null
  }
}

Update an entity

Update the properties of an entity using JSON Merge Patch (RFC 7386). Only the properties listed in properties are modified.

Set a property to null (for scalars) or [] (for reference arrays) to clear its value. Properties not listed are left untouched.

Request

curl -X PATCH "https://{your-environment}.ataccama.one/api/catalog/v1/entities/{urn}" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": {
      "abbreviation": "SUPP",
      "securityClassification": null
    }
  }'

Request body fields
Field	Type	Required	Description
`properties`	object	Yes	A map of properties to merge into the entity, keyed by property name as defined in the metadata model.

The response returns the updated entity (same structure as Get an entity).

Delete an entity

Delete an entity by its URN.

Request

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

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

Batch operations

Batch endpoints let you create, update, or delete up to 100 entities in a single request.

All batch endpoints share the same conventions:

The request body contains a data array with 1 to 100 items.
Each item can carry an optional id, a caller-supplied correlation identifier echoed back in the corresponding result item.
Results are returned in the same order as the request items.
The response returns the HTTP status code 207 Multi-Status with a meta summary (total, success, fail) and a results array where each item reports its own status (OK on success).

Batch create and batch update are atomic: either every item succeeds or every item fails. Batch delete processes each item independently: a failure on one item does not stop the rest.

Create entities in batch

Request

curl -X POST "https://{your-environment}.ataccama.one/api/catalog/v1/entities/batch/create" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      {
        "id": "item-1",
        "concreteType": "businessTerm",
        "parentProperty": "terms",
        "properties": {
          "name": "PII",
          "abbreviation": "PII"
        }
      },
      {
        "id": "item-2",
        "concreteType": "businessTerm",
        "parentProperty": "terms",
        "properties": {
          "name": "Sensitive Data"
        }
      }
    ]
  }'

Each item has the same fields as Create an entity, as well as the optional correlation id.

Response example

{
  "meta": {
    "total": 2,
    "success": 2,
    "fail": 0
  },
  "results": [
    {
      "id": "item-1",
      "status": "OK",
      "data": {
        "urn": "urn:ata:{your-tenant}:catalog:term:123e4567-e89b-12d3-a456-426614174000",
        "parentUrn": null,
        "rootSuperType": "term",
        "concreteType": "businessTerm"
      }
    },
    {
      "id": "item-2",
      "status": "OK",
      "data": {
        "urn": "urn:ata:{your-tenant}:catalog:term:3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "parentUrn": null,
        "rootSuperType": "term",
        "concreteType": "businessTerm"
      }
    }
  ]
}

Update entities in batch

Each item must include the entity urn and the properties to merge, following the same JSON Merge Patch semantics as Update an entity.

Request

curl -X POST "https://{your-environment}.ataccama.one/api/catalog/v1/entities/batch/patch" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      {
        "id": "item-1",
        "urn": "urn:ata:{your-tenant}:catalog:term:123e4567-e89b-12d3-a456-426614174000",
        "properties": {
          "abbreviation": "SUPP"
        }
      },
      {
        "urn": "urn:ata:{your-tenant}:catalog:term:3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "properties": {
          "domains": [
            "urn:ata:{your-tenant}:catalog:domain:10bae762-0000-8010-8000-000001eb0065"
          ]
        }
      }
    ]
  }'

The response follows the same structure as Create entities in batch, with each successful result containing the updated entity.

Delete entities in batch

Each item identifies the entity to delete by its urn.

Request

curl -X POST "https://{your-environment}.ataccama.one/api/catalog/v1/entities/batch/delete" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      {
        "id": "item-1",
        "urn": "urn:ata:{your-tenant}:catalog:term:123e4567-e89b-12d3-a456-426614174000"
      },
      {
        "id": "item-2",
        "urn": "urn:ata:{your-tenant}:catalog:term:3fa85f64-5717-4562-b3fc-2c963f66afa6"
      }
    ]
  }'

Items that existed and were deleted are reported with status: OK and data.deleted: true. Items where no entity with the given URN was found are reported with status: RESOURCE_NOT_FOUND. Inspect meta for the success and fail totals.

Response example

{
  "meta": {
    "total": 2,
    "success": 1,
    "fail": 1
  },
  "results": [
    {
      "id": "item-1",
      "status": "OK",
      "data": {
        "deleted": true
      }
    },
    {
      "id": "item-2",
      "status": "RESOURCE_NOT_FOUND",
      "error": {
        "type": "RESOURCE_NOT_FOUND",
        "title": "Resource Not Found",
        "detail": "Entity with URN 'urn:ata:{your-tenant}:catalog:term:3fa85f64-5717-4562-b3fc-2c963f66afa6' was not found"
      }
    }
  ]
}

Complete example

Here’s a complete example using cURL to work with generic metadata entities:

# 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 business terms with selected properties
curl -X GET "https://{your-environment}.ataccama.one/api/catalog/v1/entities?entityType=businessTerm&properties=name,abbreviation&sort=name" \
  -H "Authorization: Bearer $TOKEN"

# 3. Create a new business term
curl -X POST "https://{your-environment}.ataccama.one/api/catalog/v1/entities" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "concreteType": "businessTerm",
    "parentProperty": "terms",
    "properties": {
      "name": "PII",
      "abbreviation": "PII"
    }
  }'

# 4. Get the entity with its properties
ENTITY_URN="urn:ata:{your-tenant}:catalog:term:123e4567-e89b-12d3-a456-426614174000"
curl -X GET "https://{your-environment}.ataccama.one/api/catalog/v1/entities/$ENTITY_URN?properties=name,abbreviation" \
  -H "Authorization: Bearer $TOKEN"

# 5. Update a property
curl -X PATCH "https://{your-environment}.ataccama.one/api/catalog/v1/entities/$ENTITY_URN" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": {
      "securityClassification": "Confidential"
    }
  }'

# 6. Delete the entity
curl -X DELETE "https://{your-environment}.ataccama.one/api/catalog/v1/entities/$ENTITY_URN" \
  -H "Authorization: Bearer $TOKEN"

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`	Entity created successfully.
`204 No Content`	Delete successful.
`207 Multi-Status`	Batch request processed. Inspect `meta` and `results` for per-item outcomes.
`400 Bad Request`	Invalid request parameters or body.
`403 Forbidden`	Insufficient permissions to access the requested resource.
`404 Not Found`	Entity does not exist.

200 OK

Request successful.

201 Created

Entity created successfully.

204 No Content

Delete successful.

207 Multi-Status

Batch request processed. Inspect meta and results for per-item outcomes.

400 Bad Request

Invalid request parameters or body.

403 Forbidden

Insufficient permissions to access the requested resource.

404 Not Found

Entity does not exist.

Error response example

{
  "type": "RESOURCE_NOT_FOUND",
  "title": "Resource Not Found",
  "detail": "Entity with URN 'urn:ata:{your-tenant}:catalog:term:123e4567-e89b-12d3-a456-426614174000' was not found"
}

Next steps

Learn about the Metadata Model API for discovering entity types and their properties.
Learn about the Catalog Items API for typed access to catalog items.
Learn about the Terms API for typed access to business and technical terms.
Download the Catalog API OpenAPI specification for detailed API reference.

Was this page useful?