--- title: "Create catalog item" method: POST path: "/catalog/v1/catalog-items" tags: ["Catalog Items"] --- # Create catalog item `POST /catalog/v1/catalog-items` ## Request - Base URL: `https://your-environment.ataccama.one/api` - URL: `https://your-environment.ataccama.one/api/catalog/v1/catalog-items` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Create a catalog item using an SQL query and place it in a folder. The catalog item is published immediately. Only SQL catalog items can be created through this endpoint. The `type` field selects the kind of catalog item to create, and currently only `dslQueryCatalogItem` is supported. Catalog items imported from a source are created by documentation flows (`POST /catalog/v1/documentation-flow/start`). Creating the catalog item also runs the query on the connection to import the catalog item attributes from the query result. If the import fails, the request still succeeds and the catalog item is created without attributes. To verify the result, retrieve the catalog item attributes using [List catalog attributes](#tag/catalog-attributes/GET/catalog/v1/attributes) with the `catalogItemUrn` query parameter. To find or create the target folder, use the Folders endpoints. Stewardship cannot be changed through this endpoint. To change the group responsible for the entity, use `POST /catalog/v1/stewardship/manage`. ## Request body - NewCatalogItem: A catalog item defined by an SQL query, placed in a folder. - `type` string, required: Type of the catalog item to create. The only supported value is `dslQueryCatalogItem`, which creates an SQL catalog item. - `name` string, required: Name of the catalog item. - `description` string: Description of the catalog item. - `connectionUrn` string, uri, required: A URN identifying a Connection to a source system. Format: urn:ata:{tenant}:processing:connection:{uuid} Example: urn:ata:acme-corp:processing:connection:123e4567-e89b-12d3-a456-426614174000. - `query` string, required: SQL query used to create the catalog item. - `folderUrn` string, uri, required: A URN identifying a Folder resource in the Catalog API. Format: urn:ata:{tenant}:catalog:folder:{uuid} Example: urn:ata:acme-corp:catalog:folder:123e4567-e89b-12d3-a456-426614174000. ## Response `201` The created catalog item. SQL catalog items carry the folder hierarchy in `folders` and no `locations`. - CatalogItem: A data asset such as a table, file, or dataset imported from one of your data sources, or an SQL catalog item created from an SQL query. - `urn` string, uri: A URN identifying a catalog item resource in the Catalog API. Format: urn:ata:{tenant}:catalog:catalog-item:{uuid} Example: urn:ata:acme-corp:catalog:catalog-item:123e4567-e89b-12d3-a456-426614174000. - `name` string, required: Name of the catalog item. - `description` string: Description of the catalog item. - `originPath` string: Origin path of the catalog item in the source system. - `connection` object: Connection to the system this item is located in. - `urn` string, uri, required: A URN identifying a Connection to a source system. Format: urn:ata:{tenant}:processing:connection:{uuid} Example: urn:ata:acme-corp:processing:connection:123e4567-e89b-12d3-a456-426614174000. - `termAssignments` TermAssignment[]: Terms assigned to the catalog item itself. Read-only through the API; term assignments on catalog items can be managed only in the web application; the term-assignment endpoints work with catalog item attributes. - `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. - `locations` LocationReference[]: The location hierarchy mirroring the structure of the source the catalog item was imported from, such as a schema and a database, ordered from the closest parent to the root. Populated for catalog items imported from a source. - `urn` string, uri, required: A URN identifying a Location resource in the Catalog API. Locations are the hierarchy nodes derived from a source during import (for example, schemas or databases) and are read-only. Format: urn:ata:{tenant}:catalog:location:{uuid} Example: urn:ata:acme-corp:catalog:location:123e4567-e89b-12d3-a456-426614174000. - `name` string, required: Location name. - `folders` FolderReference[]: The folder hierarchy in the workspace of the source, ordered from the closest parent to the root. Populated for catalog items placed in folders, such as SQL catalog items. - `urn` string, uri, required: A URN identifying a Folder resource in the Catalog API. Format: urn:ata:{tenant}:catalog:folder:{uuid} Example: urn:ata:acme-corp:catalog:folder:123e4567-e89b-12d3-a456-426614174000. - `name` string, required - `source` object - `urn` string, uri, required: A URN identifying a source resource in the Catalog API. Format: urn:ata:{tenant}:catalog:source:{uuid} Example: urn:ata:acme-corp:catalog:source: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. - `primaryDqMonitor` object: Primary DQ monitor for this catalog item. - `urn` string, uri: A URN identifying the DQ monitor resource in the Data Quality API. Format: urn:ata:{tenant}:data-quality:dq-monitor:{uuid} Example: urn:ata:acme-corp:data-quality:dq-monitor:123e4567-e89b-12d3-a456-426614174000. - `aliases` CatalogAlias[]: Alternative identifiers for the catalog item, for example, its identifier in another catalog. - `type` string, required: Type of the alias, for example, `COLLIBRA_ASSET_ID`. - `value` string: Value of the alias. - `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. ## Other responses - `400`: Bad request. The request parameters or body are invalid. - `403`: Forbidden. You do not have permission to access the requested resource. - `404`: Not found. The requested resource does not exist. --- [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)