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

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.
Response example
{
  "meta": {
    "next": "MjA=",
    "total": 45
  },
  "data": [
    {
      "urn": "urn:ata:acme-corp:catalog:term:123e4567-e89b-12d3-a456-426614174000",
      "type": "businessTerm",
      "name": "PII",
      "description": "Personally Identifiable Information",
      "detectionRules": {
        "operator": "OR",
        "ruleAssignments": [
          {
            "detectionRuleUrn": "urn:ata:acme-corp:catalog:detection-rule:576d90b8-4c9f-483b-a309-9f7b6b367f80",
            "threshold": 80
          }
        ]
      }
    },
    {
      "urn": "urn:ata:acme-corp: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:acme-corp:catalog:term:123e4567-e89b-12d3-a456-426614174000",
  "type": "businessTerm",
  "name": "PII",
  "description": "Personally Identifiable Information",
  "detectionRules": {
    "operator": "OR",
    "ruleAssignments": [
      {
        "detectionRuleUrn": "urn:ata:acme-corp:catalog:detection-rule:576d90b8-4c9f-483b-a309-9f7b6b367f80",
        "threshold": 80
      },
      {
        "detectionRuleUrn": "urn:ata:acme-corp: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:acme-corp:catalog:detection-rule:576d90b8-4c9f-483b-a309-9f7b6b367f80",
          "threshold": 90
        }
      ]
    }
  }'
Request body fields
Field Type Description

name

string or null

Updated name for the term.

description

string or null

Updated description for the term.

detectionRules

object or null

Detection rules configuration for automated term assignment.

Detection rules structure

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

Fields
Field Type Description

operator

string

Logical operator for combining rules: AND or OR.

ruleAssignments

array

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:acme-corp:catalog:detection-rule:576d90b8-4c9f-483b-a309-9f7b6b367f80",
        "threshold": 80
      },
      {
        "detectionRuleUrn": "urn:ata:acme-corp: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.

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": [
      {
        "urn": "urn:ata:acme-corp:catalog:term:676d90b8-4c9f-483b-a309-9f7b6b367f80",
        "type": "businessTerm",
        "name": "PII",
        "description": "Personally Identifiable Information",
        "detectionRules": {
          "operator": "OR",
          "ruleAssignments": [
            {
              "detectionRuleUrn": "urn:ata:acme-corp:catalog:detection-rule:576d90b8-4c9f-483b-a309-9f7b6b367f80",
              "threshold": 80
            }
          ]
        }
      },
      {
        "urn": "urn:ata:acme-corp:catalog:term:776d90b8-4c9f-483b-a309-9f7b6b367f80",
        "type": "securityTerm",
        "name": "Sensitive Data",
        "description": "Data requiring additional security controls",
        "detectionRules": {
          "operator": "AND",
          "ruleAssignments": [
            {
              "detectionRuleUrn": "urn:ata:acme-corp:catalog:detection-rule:576d90b8-4c9f-483b-a309-9f7b6b367f80",
              "threshold": 85
            }
          ]
        }
      }
    ]
  }'
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

urn

string

Yes

URN identifier for the term (must be pre-generated in the format urn:ata:{your-tenant}:catalog:term:{uuid}).

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.
Response example
{
  "data": [
    {
      "urn": "urn:ata:acme-corp:catalog:term:676d90b8-4c9f-483b-a309-9f7b6b367f80",
      "type": "businessTerm",
      "name": "PII",
      "description": "Personally Identifiable Information",
      "detectionRules": {
        "operator": "OR",
        "ruleAssignments": [
          {
            "detectionRuleUrn": "urn:ata:acme-corp:catalog:detection-rule:576d90b8-4c9f-483b-a309-9f7b6b367f80",
            "threshold": 80
          }
        ]
      }
    },
    {
      "urn": "urn:ata:acme-corp:catalog:term:776d90b8-4c9f-483b-a309-9f7b6b367f80",
      "type": "securityTerm",
      "name": "Sensitive Data",
      "description": "Data requiring additional security controls",
      "detectionRules": {
        "operator": "AND",
        "ruleAssignments": [
          {
            "detectionRuleUrn": "urn:ata:acme-corp:catalog:detection-rule:576d90b8-4c9f-483b-a309-9f7b6b367f80",
            "threshold": 85
          }
        ]
      }
    }
  ]
}

Complete example

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

#!/bin/bash

# Configuration
ENVIRONMENT="your-environment"
REALM="your-realm"
CLIENT_ID="your-client-id"
CLIENT_SECRET="your-client-secret"

BASE_URL="https://${ENVIRONMENT}.ataccama.one"
AUTH_URL="${BASE_URL}/auth/realms/${REALM}/protocol/openid-connect/token"
API_URL="${BASE_URL}/api/catalog/v1"

# 1. Obtain access token
echo "Obtaining access token..."
TOKEN=$(curl -s -X POST "$AUTH_URL" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=$CLIENT_ID" \
  -d "client_secret=$CLIENT_SECRET" \
  | jq -r '.access_token')

# 2. List all terms
echo "Listing all terms..."
curl -s -X GET "${API_URL}/terms?size=20" \
  -H "Authorization: Bearer $TOKEN" | jq '.'

# 3. Create terms in bulk
echo "Creating terms in bulk..."
curl -s -X POST "${API_URL}/terms/bulk" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "terms": [
      {
        "urn": "urn:ata:your-tenant:catalog:term:a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
        "type": "businessTerm",
        "name": "Customer ID",
        "description": "Unique identifier for customers"
      },
      {
        "urn": "urn:ata:your-tenant:catalog:term:b2c3d4e5-6f7a-8b9c-0d1e-2f3a4b5c6d7e",
        "type": "businessTerm",
        "name": "Email Address",
        "description": "Customer email address"
      }
    ]
  }' | jq '.'

# 4. Get a specific term
TERM_URN="urn:ata:your-tenant:catalog:term:a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
echo "Getting term: $TERM_URN"
curl -s -X GET "${API_URL}/terms/${TERM_URN}" \
  -H "Authorization: Bearer $TOKEN" | jq '.'

# 5. Update the term
echo "Updating term..."
curl -s -X PATCH "${API_URL}/terms/${TERM_URN}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated description: Unique identifier for customer records"
  }' | jq '.'

echo "Term management complete!"

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": [
    {
      "urn": "urn:ata:your-tenant:catalog:term:c3d4e5f6-7a8b-9c0d-1e2f-3a4b5c6d7e8f",
      "type": "businessTerm",
      "name": "Revenue",
      "description": "Total income from sales"
    },
    {
      "urn": "urn:ata:your-tenant:catalog:term:d4e5f6a7-8b9c-0d1e-2f3a-4b5c6d7e8f9a",
      "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

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.

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

  • Use bulk creation for efficiency: When creating multiple terms, use the bulk endpoint to reduce the number of API calls.

  • Pre-generate URNs: Generate valid URNs in the format urn:ata:{your-tenant}:catalog:term:{uuid} before creating terms.

  • 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

Was this page useful?