Folders 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 Folders API allows you to programmatically manage folders in the Ataccama ONE catalog. Folders organize the catalog items in the workspace of a source, such as SQL catalog items, which are created in the source rather than imported from it. Unlike locations, which are created during metadata import and mirror the structure of the source, folders are created and managed manually.

A folder is nested either directly under a source or under another folder, forming a hierarchy. The parent of a folder can’t be changed after the folder is created.

Use this API to prepare the folder structure before creating SQL catalog items through the Catalog Items API, for example, when migrating SQL catalog items from another environment.

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

API base URL

All Folders 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 folders

Retrieve a paginated list of folders.

Request

curl -X GET "https://{your-environment}.ataccama.one/api/catalog/v1/folders?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 folders to return. Default: `20`. Max: `100`.
`parentUrn`	string	No	Filter folders by their parent: a source URN or a folder URN. Use it to browse a single level of the folder hierarchy. When omitted, folders are not filtered by parent. Example: `?parentUrn=urn:ata:{your-tenant}:catalog:source:28e3ca71-635b-43c4-9d1b-bc9cc642721f`.
`searchQuery`	string	No	Full-text query matched against all string properties of the folder, such as `name` and `description`.
`name`	string	No	Filter folders by exact match on the name.
`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).
`extraProperties`	string	No	Comma-separated list of extra property names to include in the `extraProperties` field of the response. When omitted, no extra properties are returned. See Work with extra properties.

Response example

{
  "meta": {
    "next": "MjA=",
    "total": 12
  },
  "data": [
    {
      "urn": "urn:ata:{your-tenant}:catalog:folder:9b1c4d2e-6f3a-4c5b-8d7e-1a2b3c4d5e6f",
      "name": "Revenue",
      "description": "Manually curated revenue reporting assets",
      "parentUrn": "urn:ata:{your-tenant}:catalog:source:28e3ca71-635b-43c4-9d1b-bc9cc642721f"
    }
  ]
}

To list the catalog items placed in a folder, use the List catalog items endpoint with the parentUrn query parameter.

Create a folder

Create a folder under a source or under another folder.

Request

curl -X POST "https://{your-environment}.ataccama.one/api/catalog/v1/folders" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Revenue",
    "description": "Manually curated revenue reporting assets",
    "parentUrn": "urn:ata:{your-tenant}:catalog:source:28e3ca71-635b-43c4-9d1b-bc9cc642721f"
  }'

Request body fields
Field	Type	Required	Description
`name`	string	Yes	Name of the folder.
`description`	string	No	Description of the folder.
`parentUrn`	string	Yes	URN of the parent: a source URN to create the folder at the top level of the workspace, or a folder URN to nest it in another folder. The parent can’t be changed after the folder is created.
`extraProperties`	object	No	Extra property values to set on the folder, as a map of property names and values. See Work with extra properties.

The response returns the HTTP status code 201 Created with the created folder, including its generated URN.

Get a folder

Retrieve detailed information about a specific folder by its URN.

Request

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

Path parameters
Parameter	Type	Required	Description
`urn`	string	Yes	URN identifier of the folder. For example: `urn:ata:{your-tenant}:catalog:folder:9b1c4d2e-6f3a-4c5b-8d7e-1a2b3c4d5e6f`.

Query parameters
Parameter	Type	Required	Description
`extraProperties`	string	No	Comma-separated list of extra property names to include in the `extraProperties` field of the response. When omitted, no extra properties are returned. See Work with extra properties.

Response example

{
  "urn": "urn:ata:{your-tenant}:catalog:folder:9b1c4d2e-6f3a-4c5b-8d7e-1a2b3c4d5e6f",
  "name": "Revenue",
  "description": "Manually curated revenue reporting assets",
  "parentUrn": "urn:ata:{your-tenant}:catalog:source:28e3ca71-635b-43c4-9d1b-bc9cc642721f"
}

Update a folder

Update specific fields of a folder 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/folders/{urn}" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Revenue reporting assets curated by the finance team"
  }'

Request body fields
Field	Type	Required	Description
`name`	string	No	Updated name of the folder.
`description`	string or null	No	Updated description of the folder.
`extraProperties`	object or null	No	Extra property values to update, as a map of property names and values. Only the properties listed in the body are modified. See Work with extra properties.

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

The parent of the folder can’t be changed.

Delete a folder

Delete a folder from the catalog.

Request

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

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

Work with extra properties

Folders support custom properties defined in the metadata model of your environment. The API refers to these custom properties as extra properties.

Extra properties work the same way for folders as for catalog items:

To retrieve them, list the property names you need in the extraProperties query parameter of the List folders or Get a folder endpoint. When omitted, no extra properties are returned.
To set or update them, use the extraProperties field in the Create a folder or Update a folder request body.

The property names must exactly match the property names defined in the metadata model. To find which properties are available, use the Metadata Model API to retrieve the folder entity definition. For details about supported value types and update behavior, see Work with extra properties in the Catalog Items API documentation.

Complete example

Here’s a complete example using cURL to create a folder and place an SQL catalog item in it:

# 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 the top-level folders of a source
SOURCE_URN="urn:ata:{your-tenant}:catalog:source:28e3ca71-635b-43c4-9d1b-bc9cc642721f"
curl -X GET "https://{your-environment}.ataccama.one/api/catalog/v1/folders?parentUrn=$SOURCE_URN" \
  -H "Authorization: Bearer $TOKEN"

# 3. Create a folder in the source
curl -X POST "https://{your-environment}.ataccama.one/api/catalog/v1/folders" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Revenue",
    "description": "Manually curated revenue reporting assets",
    "parentUrn": "urn:ata:{your-tenant}:catalog:source:28e3ca71-635b-43c4-9d1b-bc9cc642721f"
  }'

# 4. Create an SQL catalog item in the folder
FOLDER_URN="urn:ata:{your-tenant}:catalog:folder:9b1c4d2e-6f3a-4c5b-8d7e-1a2b3c4d5e6f"
curl -X POST "https://{your-environment}.ataccama.one/api/catalog/v1/catalog-items" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "dslQueryCatalogItem",
    "name": "high_value_customers",
    "connectionUrn": "urn:ata:{your-tenant}:processing:connection:b812d964-f94e-4be7-85c3-0073742ade09",
    "query": "SELECT * FROM customers WHERE lifetime_value > 10000",
    "folderUrn": "urn:ata:{your-tenant}:catalog:folder:9b1c4d2e-6f3a-4c5b-8d7e-1a2b3c4d5e6f"
  }'

# 5. List the catalog items in the folder
curl -X GET "https://{your-environment}.ataccama.one/api/catalog/v1/catalog-items?parentUrn=$FOLDER_URN" \
  -H "Authorization: Bearer $TOKEN"

Error handling

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

Status code Description

Status code	Description
`200 OK`	Folder or list of folders returned successfully.
`201 Created`	Folder created successfully.
`204 No Content`	Folder deleted successfully.
`400 Bad Request`	Invalid request parameters or body.
`403 Forbidden`	Insufficient permissions to access the requested resource.
`404 Not Found`	Folder does not exist. When creating a folder, the parent source or folder in `parentUrn` does not exist.

200 OK

Folder or list of folders returned successfully.

201 Created

Folder created successfully.

204 No Content

Folder deleted successfully.

400 Bad Request

Invalid request parameters or body.

403 Forbidden

Insufficient permissions to access the requested resource.

404 Not Found

Folder does not exist. When creating a folder, the parent source or folder in parentUrn does not exist.

Error response example

{
  "type": "RESOURCE_NOT_FOUND",
  "title": "Resource Not Found",
  "detail": "Folder with ID '9b1c4d2e-6f3a-4c5b-8d7e-1a2b3c4d5e6f' was not found"
}

Next steps

Learn about creating SQL catalog items to place in your folders.
Learn about managing sources that folders belong to.
Use the Metadata Model API to discover the extra properties available for folders in your environment.
Download the Catalog API OpenAPI specification for detailed API reference.

Was this page useful?