> For the complete documentation index, see [llms.txt](https://fredhopper.gitbook.io/product-discovery/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://fredhopper.gitbook.io/product-discovery/sending-and-managing-product-data/what-is-the-items-api/working-with-items/category-tree/using-the-category-tree-api.md).

# Using the Category Tree 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 category tree

<mark style="color:green;">`POST`</mark> `/category-trees`

#### Query Parameters

| Name                                          | Type   | Description                                                                       |
| --------------------------------------------- | ------ | --------------------------------------------------------------------------------- |
| environment<mark style="color:red;">\*</mark> | string |                                                                                   |
| tenant<mark style="color:red;">\*</mark>      | string |                                                                                   |
| fhrValidation                                 | String | True/false. Enforces specific validation to comply with the Fredhopper data model |

#### Headers

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

#### Request Body

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

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

```javascript
{
    "version": 1
}
```

{% endtab %}

{% tab title="400: Bad Request categoryTree validation failed (see api errors belows)" %}

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

{% endtab %}

{% tab title="409: Conflict categoryTree already exists" %}

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

{% endtab %}
{% endtabs %}

{% hint style="danger" %}
The root name can't be "0".
{% endhint %}

## Category tree request example

{% code title="> POST /category-trees" %}

```javascript
{
    "name": "catalog01",
    "localizedNames": [
        {
            "locale": "en_GB",
            "name": "Home"
        },
        {
            "locale": "de_DE",
            "name": "Startseite"
        }
    ],
    "tenant": "demo",
    "environment": "fas:live1",
    "children": [
        {
            "name": "dresses21",
            "localizedNames": [
                {
                    "locale": "en_GB",
                    "name": "Dresses"
                },
                {
                    "locale": "de_DE",
                    "name": "Kleider"
                }
            ]
        }
    ]
}
```

{% endcode %}

## Update a category tree

<mark style="color:orange;">`PUT`</mark> `https://items.attraqt.io/category-trees/{name}`

#### Path Parameters

| Name                                   | Type   | Description             |
| -------------------------------------- | ------ | ----------------------- |
| name<mark style="color:red;">\*</mark> | string | Category tree root name |

#### Query Parameters

| Name                                          | Type   | Description                                                                       |
| --------------------------------------------- | ------ | --------------------------------------------------------------------------------- |
| tenant<mark style="color:red;">\*</mark>      | String |                                                                                   |
| environment<mark style="color:red;">\*</mark> | String |                                                                                   |
| fhrValidation                                 | String | True/false. Enforces specific validation to comply with the Fredhopper data model |

#### Headers

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

#### Request Body

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

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

```javascript
{
    "version": 2    
}
```

{% endtab %}

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

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

{% endtab %}

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

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

{% endtab %}
{% endtabs %}

## List category trees

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

#### Query Parameters

| Name                                          | Type   | Description |
| --------------------------------------------- | ------ | ----------- |
| nameSearchPattern                             | string |             |
| 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 |

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

```javascript
{
    "categoryTrees": [
      {
        "tenant": "foo",
        "environment": "main",
        "version": 1,
        "name": "root",
        "children": [
          {
            "name": "child-1",
            "localizedNames": [
              {
                "name": "feuille",
                "locale": "fr"
              }
            ],
            "children": []
          }
        ],
        "localizedNames": [
          {
            "name": "racine",
            "locale": "fr"
          }
        ]
      }
    ]
  }
```

{% endtab %}
{% endtabs %}

## Get a category tree

<mark style="color:blue;">`GET`</mark> `https://items.attraqt.io/category-trees/{name}/{version}`

#### Path Parameters

| Name                                      | Type   | Description                  |
| ----------------------------------------- | ------ | ---------------------------- |
| version<mark style="color:red;">\*</mark> | number | Version of the category tree |
| name<mark style="color:red;">\*</mark>    | string | Category tree root name      |

#### 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 " %}

```javascript
 {
  "tenant": "foo",
  "environment": "main",
  "version": 1,
  "name": "root",
  "children": [
    {
      "name": "child-1",
      "localizedNames": [
        {
          "name": "feuille",
          "locale": "fr"
        }
      ],
      "children": []
    }
  ],
  "localizedNames": [
    {
      "name": "racine",
      "locale": "fr"
    }
  ]
}
```

{% endtab %}

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

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

{% endtab %}
{% endtabs %}

## Delete a category tree

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

#### Path Parameters

| Name                                      | Type   | Description                  |
| ----------------------------------------- | ------ | ---------------------------- |
| version<mark style="color:red;">\*</mark> | number | Version of the category tree |
| name<mark style="color:red;">\*</mark>    | string | Category tree root name      |

#### 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="400: Bad Request categoryTree used in catalog" %}

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

{% endtab %}

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

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

{% endtab %}
{% endtabs %}

###

### Api errors

| Error category                  | Description                                                      |
| ------------------------------- | ---------------------------------------------------------------- |
| CATEGORY\_TREE\_NAME            | Name is invalid                                                  |
| CATEGORY\_TREE\_LOCALE          | Category tree contain a invalid locale or localized name         |
| CATEGORY\_TREE\_LEAF            | Category tree contain a invalid leaf or leaf name                |
| CATEGORY\_TREE\_DELETION\_USE   | CategoryTree is currently used in a Catalog                      |
| CATEGORY\_TREE\_ALREADY\_EXISTS | The category tree already exists, use update method              |
| CATEGORY\_TREE\_NOT\_FOUND      | Impossible to update the category tree: category tree not exists |