# Using the Catalog API

{% hint style="info" %}
[This API requires Authentication.](/product-discovery/sending-and-managing-product-data/what-is-the-items-api/authorization-to-apis.md)
{% endhint %}

## Create a catalog

<mark style="color:green;">`POST`</mark> `/catalogs`

#### Query Parameters

| Name                                          | Type   | Description |
| --------------------------------------------- | ------ | ----------- |
| tenant<mark style="color:red;">\*</mark>      | string |             |
| environment<mark style="color:red;">\*</mark> | string |             |

#### Headers

<table><thead><tr><th width="255">Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>Authorization<mark style="color:red;">*</mark></td><td>string</td><td>Bearer token containing the following permission:</td></tr></tbody></table>

#### Request Body

| Name                                      | Type   | Description |
| ----------------------------------------- | ------ | ----------- |
| catalog<mark style="color:red;">\*</mark> | object | catalog     |

{% tabs %}
{% tab title="200 catalog successfully created, return the catalog version." %}

```
{{catalog.version}}
```

{% endtab %}

{% tab title="400: Bad Request Code 3 : Tenant and Environment are required" %}

```javascript
{
    // Response
}
```

{% endtab %}

{% tab title="400: Bad Request The limit of 2 catalogs is reached" %}

```javascript
{
    // Response
}
```

{% endtab %}

{% tab title="400: Bad Request Catalog validation failed" %}

```javascript
{
    // Response
}
```

{% endtab %}

{% tab title="409: Conflict Error during the catalog creation on FHR" %}

```javascript
{
    // Response
}
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
**Remember!** Catalog API can handle only 2 catalogs at the same time. If this limit is reached, one inactive catalog must be deleted by using the API before creating a new one. Determining the inactive catalog is done by listing all catalogs API.
{% endhint %}

{% hint style="info" %}
Create a catalog returns the created catalog version. The catalog state is managed by the API. New catalogs are always set as Inactive and you must use the "Activate" method to this activate it.
{% endhint %}

{% hint style="info" %}
The `catalogCategoryTrees` nested JSON object is optional.
{% endhint %}

{% code title="Example of a catalog creation body:" %}

```javascript
{
    "catalogItemSchemas": [
        {
            "name": "product",
            "version": 1
        }
    ],
    "catalogCategoryTrees": [
       {
           "name": "root_name",
           "version": 2
       }
    ]
}
```

{% endcode %}

### Multiple category trees

In the standard usecase the catalog will contain one single category tree. However, based on the data model used the category tree might grow and get harder to manage. We consider category trees larger than 4 MB too large, and we recommend splitting the tree if this limit is approached.

{% hint style="info" %}
One single category tree cannot exceed 4 MB in size. Use multiple trees if that is the case.
{% endhint %}

{% code title="Example of catalog creation with multiple category trees" %}

```javascript
{
    "catalogItemSchemas": [
        {
            "name": "product",
            "version": 1
        }
    ],
    "catalogCategoryTrees": [
        {
            "name": "categoryTreeDividedPart1",
            "version": 2
        },
        {
            "name": "categoryTreeDividedPart2",
            "version": 1
        }
    ]
}
```

{% endcode %}

## Delete a catalog

<mark style="color:red;">`DELETE`</mark> `https://items.attraqt.io/catalogs/{version}`

#### Path Parameters

| Name                                      | Type    | Description                    |
| ----------------------------------------- | ------- | ------------------------------ |
| version<mark style="color:red;">\*</mark> | integer | ​Version of catalog to delete. |

#### Query Parameters

| Name                                          | Type   | Description |
| --------------------------------------------- | ------ | ----------- |
| tenant<mark style="color:red;">\*</mark>      | string |             |
| environment<mark style="color:red;">\*</mark> | string |             |

#### Headers

| Name                                            | Type   | Description                                       |
| ----------------------------------------------- | ------ | ------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | Bearer token containing the following permission: |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}

{% tab title="404: Not Found The requested catalog is not found" %}

```javascript
{
    // Response
}
```

{% endtab %}

{% tab title="400: Bad Request The catalog must be inactive to be deleted" %}

```javascript
{
    // Response
}
```

{% endtab %}
{% endtabs %}

{% hint style="danger" %}
Only **Inactive** catalogs can be deleted.

**Attention**: removing a catalog will delete items attached to this catalog, this operation can't be undone
{% endhint %}

## Activate a catalog version

<mark style="color:green;">`POST`</mark> `https://items.attraqt.io/catalogs/activate/{version}`

#### Path Parameters

| Name                                      | Type    | Description                      |
| ----------------------------------------- | ------- | -------------------------------- |
| version<mark style="color:red;">\*</mark> | integer | ​Version of catalog to activate. |

#### Query Parameters

| Name                                          | Type    | Description                                                                                                                                                                                                                                                                                                                                                                                                                     |
| --------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| tenant<mark style="color:red;">\*</mark>      | string  |                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| environment<mark style="color:red;">\*</mark> | string  |                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| minItemCount                                  | integer | The minimum number of items expected in this catalog activation. If the item processing pipeline detects less items than this number, then the catalog activation will fail. The feedback message in [the corresponding Feedback API](https://crownpeak.gitbook.io/developer-documentation/item-catalog-management/feedback/feedback-api#catalog-activation-statistics) will indicate both this number and the detected number. |

#### Headers

| Name                                            | Type   | Description                                       |
| ----------------------------------------------- | ------ | ------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | Bearer token containing the following permission: |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}

{% tab title="400: Bad Request Tenant and Environment are required" %}

```javascript
{
    // Response
}
```

{% endtab %}

{% tab title="400: Bad Request Catalog already active or a catalog is already in activation" %}

```javascript
{
    // Response
}
```

{% endtab %}

{% tab title="404: Not Found Catalog Not found" %}

```javascript
{
    // Response
}
```

{% endtab %}

{% tab title="409: Conflict Error delivering metadata to FHR or during the catalog activation on FHR" %}

```javascript
{
    // Response
}
```

{% endtab %}
{% endtabs %}

## Get active catalogue version

<mark style="color:blue;">`GET`</mark> `https://items.attraqt.io/catalogs/active`

Get the catalog version currently promoted

#### Query Parameters

| Name                                          | Type   | Description |
| --------------------------------------------- | ------ | ----------- |
| tenant<mark style="color:red;">\*</mark>      | string |             |
| environment<mark style="color:red;">\*</mark> | string |             |

#### Headers

| Name                                            | Type   | Description                                       |
| ----------------------------------------------- | ------ | ------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | Bearer token containing the following permission: |

{% tabs %}
{% tab title="200 " %}

```
{{catalog}}
```

{% endtab %}

{% tab title="404: Not Found " %}

```javascript
{
    // Response
}
```

{% endtab %}
{% endtabs %}

## List catalogs

<mark style="color:blue;">`GET`</mark> `https://items.attraqt.io/catalogs`

#### Query Parameters

| Name                                          | Type   | Description |
| --------------------------------------------- | ------ | ----------- |
| tenant<mark style="color:red;">\*</mark>      | string |             |
| environment<mark style="color:red;">\*</mark> | string |             |

#### Headers

| Name                                            | Type   | Description                                       |
| ----------------------------------------------- | ------ | ------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | Bearer token containing the following permission: |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

### Api errors

| Error category            | Description                                                   |
| ------------------------- | ------------------------------------------------------------- |
| CATALOG\_TENANT\_ENV      | Tenant and Environment are required                           |
| CATALOG\_SCHEMAS          | Error in given Item Schema                                    |
| CATALOG\_CATEGORY\_TREES  | Error in given Category tree                                  |
| CATALOG\_LIMIT\_REACHED   | The limit of 2 catalogs is reached                            |
| CATALOG\_ALREADY\_ACTIVE  | The catalog is already active or in activation state          |
| CATALOG\_FHR\_FAILED      | Error in FHR api                                              |
| CATALOG\_NOT\_ACTIVE      | The catalog must be in activating state to perform the action |
| CATALOG\_DELETION\_ACTIVE | The catalog must be inactive to be deleted                    |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://crownpeak.gitbook.io/product-discovery/sending-and-managing-product-data/what-is-the-items-api/working-with-items/item-catalog/using-the-catalog-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.