> 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/item-schema/using-the-item-schema-api.md).

# Using the Item Schema 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 an item schema

<mark style="color:green;">`POST`</mark> `https://items.attraqt.io/item-schemas`

#### 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 |
| -------------------------------------------- | ------ | ----------- |
| itemSchema<mark style="color:red;">\*</mark> | object | itemSchema  |

{% tabs %}
{% tab title="200 itemSchema successfully created." %}

```
{}
```

{% endtab %}

{% tab title="400: Bad Request itemSchema validation failed (see error table below)" %}

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

{% endtab %}

{% tab title="400: Bad Request schema names should be unique per tenant" %}

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

{% endtab %}
{% endtabs %}

| Error category            | Description                                          |
| ------------------------- | ---------------------------------------------------- |
| ITEM\_SCHEMA\_TENANT\_ENV | Tenant and Environment are required                  |
| ITEM\_SCHEMA\_NAME        | Name required                                        |
| ITEM\_SCHEMA\_VERSION     | version should not be set when creating a itemSchema |
| ITEM\_SCHEMA\_ATTRIBUTES  | schema contains an invalid attribute                 |

{% hint style="warning" %}
The schema version is managed by the API, **don't include it on creation**. When you create an item schema **the** **version is set to 1**.
{% endhint %}

{% code title="Example of an item schema creation body:" %}

```javascript
{
    "name": "product",
    "attributes": [
        {
            "name": "title",
            "type": "TEXT"
        },
        {
            "name": "description",
            "type": "TEXT"
        }
    ],
    "nestedItemSchemas": [
        {
            "attributes": [
                {
                    "name": "price",
                    "type": "INTEGER"
                },
                {
                    "name": "color",
                    "type": "TEXT"
                }
            ]
        }
    ]
}
```

{% endcode %}

## Update an item schema

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

This endpoint allows you to update an existing item schema.

#### Path Parameters

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

#### 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          |
| -------------------------------------------- | ------ | -------------------- |
| itemSchema<mark style="color:red;">\*</mark> | string | itemSchema to update |

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

```
```

{% endtab %}

{% tab title="400: Bad Request Item Schema should exist to be updated" %}

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

{% endtab %}

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

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

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Updating an item schema will increment his version by 1.
{% endhint %}

## Delete an item schema

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

#### Path Parameters

| Name                                      | Type    | Description                       |
| ----------------------------------------- | ------- | --------------------------------- |
| name<mark style="color:red;">\*</mark>    | string  | Name of itemSchema to delete.     |
| version<mark style="color:red;">\*</mark> | integer | ​Version of itemSchema 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="400: Bad Request itemSchema is used in a catalog" %}

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

{% endtab %}

{% tab title="400: Bad Request itemSchema not found" %}

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

{% endtab %}
{% endtabs %}

## Get an item schema

<mark style="color:blue;">`GET`</mark> `/item-schemas/{name}/{version}`

Get a full item schema by providing its slug and version.

#### Path Parameters

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

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

```
{{item schema}}
```

{% endtab %}

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

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

{% endtab %}
{% endtabs %}