Terms 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 Terms API allows you to programmatically manage business and technical terms in your Ataccama ONE glossary. You can create, read, update, and delete terms, as well as manage detection rules for automated term assignment.

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

API base URL

All Terms 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 terms

Retrieve a paginated list of all published terms.

Request

curl -X GET "https://{your-environment}.ataccama.one/api/catalog/v1/terms?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 terms 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).

Response example

{
  "meta": {
    "next": "MjA=",
    "total": 45
  },
  "data": [
    {
      "urn": "urn:ata:{your-tenant}:catalog:term:123e4567-e89b-12d3-a456-426614174000",
      "type": "businessTerm",
      "name": "PII",
      "description": "Personally Identifiable Information",
      "detectionRules": {
        "operator": "OR",
        "ruleAssignments": [
          {
            "detectionRuleUrn": "urn:ata:{your-tenant}:catalog:detection-rule:576d90b8-4c9f-483b-a309-9f7b6b367f80",
            "threshold": 80
          }
        ]
      }
    },
    {
      "urn": "urn:ata:{your-tenant}:catalog:term:223e4567-e89b-12d3-a456-426614174000",
      "type": "securityTerm",
      "name": "Sensitive Data",
      "description": "Data requiring additional security controls"
    }
  ]
}

Get a term

Retrieve detailed information about a specific term by its URN.

Request

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

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

Response example

{
  "urn": "urn:ata:{your-tenant}:catalog:term:123e4567-e89b-12d3-a456-426614174000",
  "type": "businessTerm",
  "name": "PII",
  "description": "Personally Identifiable Information",
  "detectionRules": {
    "operator": "OR",
    "ruleAssignments": [
      {
        "detectionRuleUrn": "urn:ata:{your-tenant}:catalog:detection-rule:576d90b8-4c9f-483b-a309-9f7b6b367f80",
        "threshold": 80
      },
      {
        "detectionRuleUrn": "urn:ata:{your-tenant}:catalog:detection-rule:63c58461-1a6c-4d0c-9176-572c9b122d79",
        "threshold": 85
      }
    ]
  }
}

Update a term

Update specific fields of a term 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/terms/{urn}" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Term Name",
    "description": "Updated description for this term",
    "detectionRules": {
      "operator": "AND",
      "ruleAssignments": [
        {
          "detectionRuleUrn": "urn:ata:{your-tenant}:catalog:detection-rule:576d90b8-4c9f-483b-a309-9f7b6b367f80",
          "threshold": 90
        }
      ]
    }
  }'

Request body fields
Field	Type	Required	Description
`name`	string or null	No	Updated name for the term.
`description`	string or null	No	Updated description for the term.
`detectionRules`	object or null	No	Detection rules configuration for automated term assignment.
`attributeToCatalogItemTermRules`	object or null	No	Rules for propagating term assignments from attributes to their parent catalog items.

Detection rules structure

Detection rules define how terms are automatically assigned to catalog items and attributes.

Fields
Field	Type	Required	Description
`operator`	string	No	Logical operator for combining rules: `AND` or `OR`.
`ruleAssignments`	array	No	Array of detection rule assignments.

Each detection rule assignment contains:

detectionRuleUrn (required): URN of the detection rule to use.
threshold (optional): Confidence threshold (0-100) for the rule match.

Example with multiple detection rules

{
  "detectionRules": {
    "operator": "OR",
    "ruleAssignments": [
      {
        "detectionRuleUrn": "urn:ata:{your-tenant}:catalog:detection-rule:576d90b8-4c9f-483b-a309-9f7b6b367f80",
        "threshold": 80
      },
      {
        "detectionRuleUrn": "urn:ata:{your-tenant}:catalog:detection-rule:63c58461-1a6c-4d0c-9176-572c9b122d79",
        "threshold": 75
      }
    ]
  }
}

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

Delete a term

Delete a term from the glossary.

Request

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

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

Create terms in bulk

Create multiple terms in a single API call. This is useful for importing glossary terms from external systems or populating the catalog with predefined terms.

The server generates URNs for the created terms automatically.

Request

curl -X POST "https://{your-environment}.ataccama.one/api/catalog/v1/terms/bulk" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "terms": [
      {
        "type": "businessTerm",
        "name": "PII",
        "description": "Personally Identifiable Information",
        "detectionRules": {
          "operator": "OR",
          "ruleAssignments": [
            {
              "detectionRuleUrn": "urn:ata:{your-tenant}:catalog:detection-rule:576d90b8-4c9f-483b-a309-9f7b6b367f80",
              "threshold": 80
            },
            {
              "detectionRuleUrn": "urn:ata:{your-tenant}:catalog:detection-rule:63c58461-1a6c-4d0c-9176-572c9b122d79"
            }
          ]
        }
      },
      {
        "type": "securityTerm",
        "name": "Sensitive Data",
        "detectionRules": {
          "operator": "AND",
          "ruleAssignments": [
            {
              "detectionRuleUrn": "urn:ata:{your-tenant}:catalog:detection-rule:576d90b8-4c9f-483b-a309-9f7b6b367f80"
            }
          ]
        }
      }
    ]
  }'

Request constraints
Constraint	Description
Min items	1 term required.
Max items	100 terms per request.

Request body fields for each term
Field	Type	Required	Description
`type`	string	Yes	Type of term (for example, `businessTerm`, `securityTerm`).
`name`	string	Yes	Name of the term.
`description`	string	No	Description of the term.
`detectionRules`	object	No	Detection rules configuration.
`attributeToCatalogItemTermRules`	object	No	Rules for propagating term assignments from attributes to their parent catalog items.

Response example

{
  "data": [
    {
      "urn": "urn:ata:{your-tenant}:catalog:term:676d90b8-4c9f-483b-a309-9f7b6b367f80",
      "type": "businessTerm",
      "name": "PII",
      "description": "Personally Identifiable Information",
      "detectionRules": {
        "operator": "OR",
        "ruleAssignments": [
          {
            "detectionRuleUrn": "urn:ata:{your-tenant}:catalog:detection-rule:576d90b8-4c9f-483b-a309-9f7b6b367f80",
            "threshold": 80
          },
          {
            "detectionRuleUrn": "urn:ata:{your-tenant}:catalog:detection-rule:63c58461-1a6c-4d0c-9176-572c9b122d79"
          }
        ]
      }
    },
    {
      "urn": "urn:ata:{your-tenant}:catalog:term:776d90b8-4c9f-483b-a309-9f7b6b367f80",
      "type": "securityTerm",
      "name": "Sensitive Data",
      "detectionRules": {
        "operator": "AND",
        "ruleAssignments": [
          {
            "detectionRuleUrn": "urn:ata:{your-tenant}:catalog:detection-rule:576d90b8-4c9f-483b-a309-9f7b6b367f80"
          }
        ]
      }
    }
  ]
}

Complete example

Here’s a complete example using cURL to manage terms:

# 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 terms (sorted by name)
curl -s -X GET "https://{your-environment}.ataccama.one/api/catalog/v1/terms?size=20&sort=name" \
  -H "Authorization: Bearer $TOKEN"

# 3. Create terms in bulk
curl -s -X POST "https://{your-environment}.ataccama.one/api/catalog/v1/terms/bulk" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "terms": [
      {
        "type": "businessTerm",
        "name": "Customer ID",
        "description": "Unique identifier for customers"
      },
      {
        "type": "businessTerm",
        "name": "Email Address",
        "description": "Customer email address"
      }
    ]
  }'

# 4. Get a specific term
TERM_URN="urn:ata:{your-tenant}:catalog:term:a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
curl -s -X GET "https://{your-environment}.ataccama.one/api/catalog/v1/terms/${TERM_URN}" \
  -H "Authorization: Bearer $TOKEN"

# 5. Update the term
curl -s -X PATCH "https://{your-environment}.ataccama.one/api/catalog/v1/terms/${TERM_URN}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated description: Unique identifier for customer records"
  }'

Example: Import terms from external system

Automate glossary management by importing terms from external systems:

# Import terms from a JSON file
curl -X POST "https://{your-environment}.ataccama.one/api/catalog/v1/terms/bulk" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @terms_to_import.json

terms_to_import.json

{
  "terms": [
    {
      "type": "businessTerm",
      "name": "Revenue",
      "description": "Total income from sales"
    },
    {
      "type": "businessTerm",
      "name": "Customer Lifetime Value",
      "description": "Total revenue expected from a customer"
    }
  ]
}

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`	Terms created successfully.
`204 No Content`	Delete successful.
`400 Bad Request`	Invalid request parameters or body (for example, too many terms in bulk request).
`403 Forbidden`	Insufficient permissions to access the requested resource.
`404 Not Found`	Term does not exist.

200 OK

Request successful.

201 Created

Terms created successfully.

204 No Content

Delete successful.

400 Bad Request

Invalid request parameters or body (for example, too many terms in bulk request).

403 Forbidden

Insufficient permissions to access the requested resource.

404 Not Found

Term does not exist.

Error response example

{
  "type": "VALIDATION_ERROR",
  "title": "Validation Error",
  "detail": "The request body contains invalid parameters.",
  "errors": [
    {
      "detail": "Maximum 100 terms allowed per bulk request",
      "pointer": "#/terms"
    }
  ]
}

Best practices for the Terms API

Use bulk creation for efficiency: When creating multiple terms, use the bulk endpoint to reduce the number of API calls.
Organize with detection rules: Attach detection rules to terms for automatic assignment to catalog items.
Keep descriptions clear: Provide meaningful descriptions to help users understand term definitions.

Next steps

Learn about managing catalog items to apply terms to your data assets.
Download the Catalog API OpenAPI specification for detailed API reference.

Was this page useful?