---
title: "Create terms in batch"
method: POST
path: "/catalog/v1/terms/batch/create"
tags: ["Terms"]
---

# Create terms in batch

`POST /catalog/v1/terms/batch/create`

## Request

- Base URL: `https://your-environment.ataccama.one/api`
- URL: `https://your-environment.ataccama.one/api/catalog/v1/terms/batch/create`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/ataccama/apis/ataccama-one-agentic-data-trust-platform-public-api/docs/catalog/v1/terms/batch/create/post.ts> (a function with typed inputs; its response is checked against the schema)

Create multiple terms in a single API call and publish them.

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.

At least one term is required, and at most 100 terms can be created per request.

The request is atomic: either every item succeeds or every item fails. The response never mixes success and failure outcomes.
The `meta` summary therefore always has either `success == total` (and `fail == 0`) or `fail == total` (and `success == 0`).

Results are returned in the same order as the request items. Each item can carry an optional `id`, a
caller-supplied correlation identifier echoed back in the corresponding result item.

Stewardship cannot be changed through this endpoint. To change the group responsible for the entity, use `POST /catalog/v1/stewardship/manage`.

## Request body

- object
  - `data` TermBatchCreateItem[], required
    - `type` string, required: The exact type of term as defined in the metadata model, for example, `businessTerm` or `securityTerm`.
    - `name` string, required: Name of the term.
    - `description` string: Description of the term.
    - `detectionRules` TermDetectionRules: Detection rules define how the term is automatically assigned to catalog items and attributes. Rule assignments are combined using the logical `operator`; each assignment references a detection rule and an optional confidence `threshold` (0–100) for the rule match.
      - `operator` string: @ExtensibleEnum Logical operator for combining rules: `AND` or `OR`. The set is extensible. New values might be added over time, so make sure your integration handles unknown values gracefully.
      - `ruleAssignments` DetectionRuleAssignment[]: Detection rule assignments.
        - `detectionRuleUrn` string, uri, required: A URN identifying a detection rule resource in the Catalog API. Format: urn:ata:{tenant}:catalog:detection-rule:{uuid} Example: urn:ata:acme-corp:catalog:detection-rule:123e4567-e89b-12d3-a456-426614174000.
        - `threshold` number, float: Confidence threshold for the rule match, if the rule supports one.
    - `attributeToCatalogItemTermRules` AttributeToCatalogItemTermRules: Rules for propagating term assignments from attributes to their parent catalog items.
      - `operator` string: @ExtensibleEnum Logical operator for combining rules: `AND` or `OR`. The set is extensible. New values might be added over time, so make sure your integration handles unknown values gracefully.
      - `rules` AttributeToCatalogItemTermRule[]
        - `operator` string: @ExtensibleEnum Logical operator for combining rules: `AND` or `OR`. The set is extensible. New values might be added over time, so make sure your integration handles unknown values gracefully.
        - `terms` TermAssignment[]
          - `termUrn` string, uri, required: A URN identifying a term resource in the Catalog API. Format: urn:ata:{tenant}:catalog:term:{uuid} Example: urn:ata:acme-corp:catalog:term:123e4567-e89b-12d3-a456-426614174000.
    - `extraProperties` ExtraProperties: A map of properties associated with the entity defined in the metadata model. Only scalar and reference properties are supported, including arrays. In responses, only properties explicitly requested via the `extraProperties` query parameter are included. In `PATCH` requests, only the properties listed in the body are modified; set a property to `null` (for scalars) or `[]` (for reference arrays) to clear its value. To find which extra properties are available for an entity, retrieve its entity definition through the Metadata model entities endpoints: `catalogItem` for catalog items, `attribute` for catalog attributes, `source` for sources, `folder` for folders, and the term's own `type` (for example, `businessTerm`) for terms.
    - `id` string: Caller-supplied correlation identifier echoed back in the corresponding result item.

## Response `207`

Multi-status batch outcome. Because creates are atomic, every item in `results` reports the same outcome — all `OK` (with `data`)
on success, or all non-`OK` (with `error`) on failure. `meta.success` therefore equals `meta.total` on success and `0` on failure.

- object
  - `meta` BatchOperationMeta, required: Summary of a batch operation outcome. Lets clients assess batch health without iterating every item.
    - `total` integer, required: Number of items in the request.
    - `success` integer, required: Number of items with `OK` status.
    - `fail` integer, required: Number of items with non-`OK` status. `success + fail` equals `total`.
  - `results` TermBatchResultItem[], required
    - `id` string: Echoes the caller-supplied correlation `id` from the corresponding request item, when one was supplied.
    - `status` string, required: @ExtensibleEnum Outcome status. `OK` indicates success; any other value indicates failure and matches the corresponding error `type`.
    - `data` Term
      - `urn` string, uri, required: A URN identifying a term resource in the Catalog API. Format: urn:ata:{tenant}:catalog:term:{uuid} Example: urn:ata:acme-corp:catalog:term:123e4567-e89b-12d3-a456-426614174000.
      - `effectiveStewardship` EffectiveStewardship: The stewardship that applies to an entity: either assigned directly to the entity or inherited from an ancestor, such as the source of a catalog item. Resolving effective stewardship takes additional processing time, so request it only when you need it.
        - `groupUrn` string, uri, required: A URN identifying a group resource in the IAM API. To find a group's URN, use the Groups endpoints of the IAM API. Format: urn:ata:{tenant}:iam:group:{uuid} Example: urn:ata:acme-corp:iam:group:123e4567-e89b-12d3-a456-426614174000.
        - `originUrn` string, uri, required: A URN identifying a resource in any realm of the Public API. URNs follow RFC 8141. Format: urn:ata:{tenant}:{realm}:{resource-type}:{uuid} Components: - `urn` — fixed scheme - `ata` — Ataccama namespace - `{tenant}` — tenant identifier from the authentication context - `{realm}` — API realm, for example `catalog` or `reference-data` - `{resource-type}` — resource type within the realm, for example `catalog-item` or `table` - `{uuid}` — UUID (v4 or v7) of the resource Example: urn:ata:acme-corp:reference-data:table:123e4567-e89b-12d3-a456-426614174000.
      - `effectiveCriticality` EffectiveCriticality: Effective criticality of this resource, either set directly on it or inherited. Critical resources are the critical data elements (CDEs) of the catalog. Criticality propagates along the chain business process → term → attribute → catalog item. A resource that has no criticality of its own is critical whenever at least one of the resources it inherits from is effectively critical; a value set directly on the resource always overrides what it would inherit. Which relations propagate criticality is configurable, see [Define critical data elements](https://docs.ataccama.com/ataccama-one-agentic/latest/data-catalog/define-critical-data-elements.html). Returned only when requested with `include=effectiveCriticality`. The value is `null` when no criticality is set on the resource and none is inherited. The response does not show which resource the criticality is inherited from. Criticality cannot be set or used as a filter criterion through the Catalog API. It is managed in the web application.
        - `isCritical` boolean, required: Whether the resource is critical.
      - `extraProperties` ExtraProperties: A map of properties associated with the entity defined in the metadata model. Only scalar and reference properties are supported, including arrays. In responses, only properties explicitly requested via the `extraProperties` query parameter are included. In `PATCH` requests, only the properties listed in the body are modified; set a property to `null` (for scalars) or `[]` (for reference arrays) to clear its value. To find which extra properties are available for an entity, retrieve its entity definition through the Metadata model entities endpoints: `catalogItem` for catalog items, `attribute` for catalog attributes, `source` for sources, `folder` for folders, and the term's own `type` (for example, `businessTerm`) for terms.
      - `type` string, required: The exact type of term as defined in the metadata model, for example, `businessTerm` or `securityTerm`.
      - `name` string, required: Name of the term.
      - `description` string: Description of the term.
      - `detectionRules` TermDetectionRules: Detection rules define how the term is automatically assigned to catalog items and attributes. Rule assignments are combined using the logical `operator`; each assignment references a detection rule and an optional confidence `threshold` (0–100) for the rule match.
        - `operator` string: @ExtensibleEnum Logical operator for combining rules: `AND` or `OR`. The set is extensible. New values might be added over time, so make sure your integration handles unknown values gracefully.
        - `ruleAssignments` DetectionRuleAssignment[]: Detection rule assignments.
          - `detectionRuleUrn` string, uri, required: A URN identifying a detection rule resource in the Catalog API. Format: urn:ata:{tenant}:catalog:detection-rule:{uuid} Example: urn:ata:acme-corp:catalog:detection-rule:123e4567-e89b-12d3-a456-426614174000.
          - `threshold` number, float: Confidence threshold for the rule match, if the rule supports one.
      - `attributeToCatalogItemTermRules` AttributeToCatalogItemTermRules: Rules for propagating term assignments from attributes to their parent catalog items.
        - `operator` string: @ExtensibleEnum Logical operator for combining rules: `AND` or `OR`. The set is extensible. New values might be added over time, so make sure your integration handles unknown values gracefully.
        - `rules` AttributeToCatalogItemTermRule[]
          - `operator` string: @ExtensibleEnum Logical operator for combining rules: `AND` or `OR`. The set is extensible. New values might be added over time, so make sure your integration handles unknown values gracefully.
          - `terms` TermAssignment[]
            - `termUrn` string, uri, required: A URN identifying a term resource in the Catalog API. Format: urn:ata:{tenant}:catalog:term:{uuid} Example: urn:ata:acme-corp:catalog:term:123e4567-e89b-12d3-a456-426614174000.
    - `error` ProblemDetail
      - `type` string, required: Error type identifier.
      - `title` string, required: Short, human-readable summary of the problem type.
      - `detail` string, required: Detailed specific explanation of the problem.

## Other responses

- `400`: Bad request. The request parameters or body are invalid.
- `403`: Forbidden. You do not have permission to access the requested resource.

---

[API](https://skmtc.dev/ataccama/apis/ataccama-one-agentic-data-trust-platform-public-api.md) - [All operations](https://skmtc.dev/ataccama/apis/ataccama-one-agentic-data-trust-platform-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/ataccama/apis/ataccama-one-agentic-data-trust-platform-public-api/revisions/46f16e0487f8?raw)