Ataccama ONE Agentic ONE Desktop ONE DQ&C ONE MDM ONE RDM ONE Runtime Server
Downloads

Metadata Model 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 Metadata Model API lets you query the metadata model of your environment: which entity types exist, how they relate to each other in the type hierarchy, and which properties each type defines. All endpoints are read-only.

Use this API to discover the entity types and property names you need when working with the Generic Metadata Entities API. For example, before creating entities of a custom type, retrieve its definition to see which properties it supports and which of them are editable.

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

API base URL

All Metadata Model 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 entity definitions are structured

Every entity definition returned by this API has the same structure:

  • name: The unique entity-type identifier, for example, businessTerm. Use it as the path parameter when retrieving a single entity definition.

  • description: A human-readable description of the entity type.

  • nodePaths: The node paths under which entities of this type are located in the metadata model.

  • superEntities: The names of the entity types this type extends, ordered from the direct parent up to the root type.

  • subEntities: The names of the entity types that directly extend this type.

  • properties: The properties defined on the entity type. See Property types.

  • editable: Whether entities of this type can be created, updated, or deleted. If false, entities of this type are read-only, typically because they represent computed content.

The entity types and their properties reflect the metadata model of your environment, including any customizations.

Property types

Each item in properties describes one property of the entity type:

  • name: The property name as referenced by entity instances.

  • description: A human-readable description of the property.

  • type: The kind of the property. One of SCALAR, SINGLE_EMBEDDED, ARRAY_EMBEDDED, SINGLE_REFERENCE, or ARRAY_REFERENCE.

  • editable: Whether the property is writable. If false, the property is read-only, typically because its value is computed, for example, delegated to another property.

Depending on type, each property carries one additional field:

Property type Additional field Description

SCALAR

scalarType

Name of the scalar type that determines the value type, for example, string, boolean, or integer.

SINGLE_EMBEDDED

entityName

Name of the metadata model entity embedded as a single value under this property.

ARRAY_EMBEDDED

entityName

Name of the metadata model entity embedded as an array of values under this property.

SINGLE_REFERENCE

entityName

Name of the metadata model entity referenced as a single value under this property.

ARRAY_REFERENCE

entityName

Name of the metadata model entity referenced as an array of values under this property.

List metadata model entities

Retrieve a paginated list of entity definitions.

Request
curl -X GET "https://{your-environment}.ataccama.one/api/catalog/v1/metadata-model/entities?searchQuery=term&size=20" \
  -H "Authorization: Bearer {access_token}"
Query parameters
Parameter Type Required Description

after

string

No

Cursor for forward pagination. When omitted, the list starts at the beginning.

size

integer

No

Number of entity definitions to return.

Default: 20.

Max: 100.

searchQuery

string

No

Full-text query matched against the entity name and description.

Example: ?searchQuery=term.
Response example
{
  "meta": {
    "next": "MjA=",
    "total": 150
  },
  "data": [
    {
      "name": "businessTerm",
      "description": "A term that captures business meaning attached to catalog data.",
      "nodePaths": [
        "/catalog/terms"
      ],
      "superEntities": [
        "term"
      ],
      "subEntities": [],
      "properties": [
        {
          "name": "isCritical",
          "description": "Whether the term represents critical business information.",
          "type": "SCALAR",
          "scalarType": "boolean",
          "editable": true
        },
        {
          "name": "parent",
          "description": "Parent business term in the term hierarchy.",
          "type": "SINGLE_REFERENCE",
          "entityName": "term",
          "editable": true
        }
      ],
      "editable": true
    }
  ]
}

Get a metadata model entity

Retrieve a single entity definition by its name.

Request
curl -X GET "https://{your-environment}.ataccama.one/api/catalog/v1/metadata-model/entities/businessTerm" \
  -H "Authorization: Bearer {access_token}"
Path parameters
Parameter Type Required Description

name

string

Yes

The entity-type identifier, matching the name field of the entity definition. For example: term, businessTerm, catalogItem.
Response example
{
  "name": "businessTerm",
  "description": "A term that captures business meaning attached to catalog data.",
  "nodePaths": [
    "/catalog/terms"
  ],
  "superEntities": [
    "term"
  ],
  "subEntities": [],
  "properties": [
    {
      "name": "isCritical",
      "description": "Whether the term represents critical business information.",
      "type": "SCALAR",
      "scalarType": "boolean",
      "editable": true
    },
    {
      "name": "parent",
      "description": "Parent business term in the term hierarchy.",
      "type": "SINGLE_REFERENCE",
      "entityName": "term",
      "editable": true
    },
    {
      "name": "aliases",
      "description": "Aliases of this business term.",
      "type": "ARRAY_EMBEDDED",
      "entityName": "catalogAlias",
      "editable": true
    },
    {
      "name": "parentName",
      "description": "Name of the parent business term. Delegated to parent.name.",
      "type": "SCALAR",
      "scalarType": "string",
      "editable": false
    }
  ],
  "editable": true
}

Error handling

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

Status code Description

200 OK

Request successful.

400 Bad Request

Invalid request parameters.

403 Forbidden

Insufficient permissions to access the requested resource.

404 Not Found

No entity definition with the given name exists.
Error response example
{
  "type": "RESOURCE_NOT_FOUND",
  "title": "Resource Not Found",
  "detail": "Metadata model entity with name 'businessTerm' was not found"
}

Next steps

Was this page useful?