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

Term Assignments 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 Term Assignments API allows you to programmatically assign glossary terms to catalog item attributes, unassign them, and control which terms term detection can assign automatically. To learn how terms are assigned in Ataccama ONE, see Detect and Apply Terms.

Use this API to assign terms in bulk, for example, when migrating manually assigned terms from another catalog or from a previous Ataccama ONE deployment, or to keep the assigned terms in sync with an external data governance tool.

The API works with catalog item attributes only. Terms assigned to catalog items themselves are returned in the termAssignments field of the Catalog Items API responses, but they can only be managed in the web application.

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

API base URL

All Term Assignments 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.

Retrieve assigned terms

The assigned terms are part of every catalog item attribute returned by the List catalog item attributes and Get a catalog item attribute endpoints. You don’t need any query parameter to retrieve them.

Request
curl -X GET "https://{your-environment}.ataccama.one/api/catalog/v1/attributes/{urn}" \
  -H "Authorization: Bearer {access_token}"
Response example (trimmed)
{
  "urn": "urn:ata:{your-tenant}:catalog:catalog-attribute:123e4567-e89b-12d3-a456-426614174000",
  "name": "customer_email",
  "catalogItemUrn": "urn:ata:{your-tenant}:catalog:catalog-item:fde84300-7a83-4d24-8c88-30ada80b0b54",
  "termAssignments": [
    {
      "termUrn": "urn:ata:{your-tenant}:catalog:term:3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "source": "MANUAL"
    },
    {
      "termUrn": "urn:ata:{your-tenant}:catalog:term:1ede1262-f76b-4d00-9929-e92c15d8a5ba",
      "source": "TERM_DETECTION"
    }
  ],
  "termDetectionDenylist": [
    {
      "termUrn": "urn:ata:{your-tenant}:catalog:term:7c9e6679-7425-40de-944b-e07fc1f90ae7"
    }
  ]
}

The response contains the following fields:

  • termAssignments: The terms assigned to the attribute. Each entry contains the termUrn of the term and the source, which tells you how the term was assigned:

    • MANUAL: The term was assigned by a user in the web application or through this API.

    • TERM_DETECTION: The term was assigned automatically by term detection.

      Other values can be added in future releases.

  • termDetectionDenylist: The terms that term detection must never assign to the attribute automatically. Each entry contains only the termUrn. See How the denylist works.

To find out which terms the URNs refer to, retrieve the terms through the Terms API.

How the denylist works

Term detection assigns terms to attributes automatically, based on the detection rules attached to the terms. If you unassign a detected term, nothing stops the next term detection run from assigning it again. To keep the term off the attribute, add it to the attribute’s denylist.

The denylist affects term detection only:

  • Term detection never assigns a denylisted term to the attribute.

  • Adding a term to the denylist doesn’t unassign the term if it’s already assigned. To do both in one call, unassign the term with addToDenylist set to true (see Unassign terms from attributes).

  • Removing a term from the denylist makes it eligible for term detection again, but doesn’t assign the term.

Manage assigned terms and the denylist in batch

Assigned terms and the denylist are managed through four batch endpoints. All of them accept a data array of 1 to 100 items, where each item names one attribute and the terms to process on it:

Request item fields
Field Type Required Description

id

string

No

Correlation identifier of your choice. It is returned in the corresponding result item.

attributeUrn

string

Yes

URN of the attribute. For example: urn:ata:{your-tenant}:catalog:catalog-attribute:123e4567-e89b-12d3-a456-426614174000.

termUrns

array

Yes

URNs of the terms to process on the attribute. At least one term is required.
Request constraints
Constraint Description

Min items

One item required.

Max items

100 items per request.

Each item is processed independently: a failure on one item doesn’t affect the other items. All four endpoints return the same response structure, described in Batch results.

Assign terms to attributes

Assign terms to attributes. Terms assigned through the API always have the source MANUAL.

Request
curl -X POST "https://{your-environment}.ataccama.one/api/catalog/v1/attributes/term-assignments/batch/assign" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      {
        "id": "item-1",
        "attributeUrn": "urn:ata:{your-tenant}:catalog:catalog-attribute:123e4567-e89b-12d3-a456-426614174000",
        "termUrns": [
          "urn:ata:{your-tenant}:catalog:term:3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "urn:ata:{your-tenant}:catalog:term:1ede1262-f76b-4d00-9929-e92c15d8a5ba"
        ]
      },
      {
        "id": "item-2",
        "attributeUrn": "urn:ata:{your-tenant}:catalog:catalog-attribute:8875f356-1b8c-43f4-8e15-651feacfca2e",
        "termUrns": [
          "urn:ata:{your-tenant}:catalog:term:3fa85f64-5717-4562-b3fc-2c963f66afa6"
        ]
      }
    ]
  }'

An item fails with the status TERM_ALREADY_ASSIGNED when a term is already assigned to the attribute.

Unassign terms from attributes

Unassign terms from attributes, regardless of whether they were assigned manually or by term detection.

To also add the unassigned terms to the attribute’s denylist, so that term detection doesn’t assign them again, set addToDenylist to true on the item. When omitted, the terms are only unassigned.

Request
curl -X POST "https://{your-environment}.ataccama.one/api/catalog/v1/attributes/term-assignments/batch/unassign" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      {
        "id": "item-1",
        "attributeUrn": "urn:ata:{your-tenant}:catalog:catalog-attribute:123e4567-e89b-12d3-a456-426614174000",
        "termUrns": [
          "urn:ata:{your-tenant}:catalog:term:1ede1262-f76b-4d00-9929-e92c15d8a5ba"
        ],
        "addToDenylist": true
      }
    ]
  }'

An item fails with the status TERM_NOT_ASSIGNED when a term isn’t assigned to the attribute.

Add terms to the denylist

Add terms to the denylist of attributes. Terms that are already assigned stay assigned.

Request
curl -X POST "https://{your-environment}.ataccama.one/api/catalog/v1/attributes/term-assignments/denylist/batch/add" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      {
        "id": "item-1",
        "attributeUrn": "urn:ata:{your-tenant}:catalog:catalog-attribute:123e4567-e89b-12d3-a456-426614174000",
        "termUrns": [
          "urn:ata:{your-tenant}:catalog:term:7c9e6679-7425-40de-944b-e07fc1f90ae7"
        ]
      }
    ]
  }'

An item fails with the status TERM_ALREADY_DENYLISTED when a term is already on the attribute’s denylist.

Remove terms from the denylist

Remove terms from the denylist of attributes. Term detection can assign these terms to the attributes again.

Request
curl -X POST "https://{your-environment}.ataccama.one/api/catalog/v1/attributes/term-assignments/denylist/batch/remove" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      {
        "id": "item-1",
        "attributeUrn": "urn:ata:{your-tenant}:catalog:catalog-attribute:123e4567-e89b-12d3-a456-426614174000",
        "termUrns": [
          "urn:ata:{your-tenant}:catalog:term:7c9e6679-7425-40de-944b-e07fc1f90ae7"
        ]
      }
    ]
  }'

An item fails with the status TERM_NOT_DENYLISTED when a term isn’t on the attribute’s denylist.

Batch results

All four endpoints return the HTTP status code 207 Multi-Status with a meta summary (total, success, fail) and a results array in the same order as the request items. Each result reports its own status: OK when all terms in the item were processed. Any other value indicates failure and is accompanied by an error whose type matches the status.

Response example
{
  "meta": {
    "total": 2,
    "success": 1,
    "fail": 1
  },
  "results": [
    {
      "id": "item-1",
      "status": "OK"
    },
    {
      "id": "item-2",
      "status": "RESOURCE_NOT_FOUND",
      "error": {
        "type": "RESOURCE_NOT_FOUND",
        "title": "Resource Not Found",
        "detail": "Catalog attribute with URN 'urn:ata:{your-tenant}:catalog:catalog-attribute:8875f356-1b8c-43f4-8e15-651feacfca2e' was not found"
      }
    }
  ]
}

The following statuses are returned:

Status Description

OK

All terms in the item were processed.

RESOURCE_NOT_FOUND

The attribute or one of the terms doesn’t exist.

TERM_ALREADY_ASSIGNED

Assign only: the term is already assigned to the attribute.

TERM_NOT_ASSIGNED

Unassign only: the term isn’t assigned to the attribute.

TERM_ALREADY_DENYLISTED

Add to denylist only: the term is already on the attribute’s denylist.

TERM_NOT_DENYLISTED

Remove from denylist only: the term isn’t on the attribute’s denylist.

Other statuses can be added in future releases.

The results don’t return the attribute’s assigned terms. To verify the outcome, retrieve the attribute (see Retrieve assigned terms).

Example: Migrate manually assigned terms

This example assigns terms maintained in another system to the attributes of a catalog item.

  1. Find the URNs of the attributes.

    List the attributes of the catalog item and match them to your source data by name:

    curl -X GET "https://{your-environment}.ataccama.one/api/catalog/v1/attributes?catalogItemUrn={catalog_item_urn}&size=100" \
  -H "Authorization: Bearer {access_token}"

  2. Find the URNs of the terms.

    List your terms through the Terms API and match them by name.

  3. Assign the terms in batch.

    Build one request item per attribute with the URNs of all terms to assign to it, and send the items in batches of up to 100 to the Assign terms to attributes endpoint. Use the id field to carry your own identifiers, so that you can trace failed items back to your source data.

  4. Check the results.

    Inspect meta.fail and the status of each result item. To make the migration safe to rerun, skip the terms that are already assigned or treat the TERM_ALREADY_ASSIGNED status as success.

Error handling

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

Status code Description

207 Multi-Status

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

400 Bad Request

Invalid request parameters or body (for example, too many items in the request).

403 Forbidden

Insufficient permissions to access the requested resource.
Error response example
{
  "type": "VALIDATION_ERROR",
  "title": "Validation Error",
  "detail": "The request body contains invalid parameters.",
  "errors": [
    {
      "detail": "Maximum 100 items allowed per request",
      "pointer": "#/data"
    }
  ]
}

Next steps

Was this page useful?