# Items API

> Current Froomle documentation · [View canonical page](https://docs.froomle.com/froomle-doc-main/v2/api_reference/items/index.html)

The Items API allows you to manage your item catalog in real-time.

<a id="_specifications"></a>

## Specifications

<a id="_environment_50d200e6d3e8eda8"></a>

### Add a new item to the catalog or update it if it already existed (RESTfully).

```
PUT /{environment}/items/{item_type}/{item_id}
```

<a id="_parameters"></a>

#### Parameters

| Type | Name | Schema |
| --- | --- | --- |
| **Path** | **environment**<br>_required_ | string |
| **Path** | **item\_id**<br>_required_ | string |
| **Path** | **item\_type**<br>_required_ | string |
| **Body** | **body**<br>_optional_ | [Item](https://docs.froomle.com/froomle-doc-main/v2/api_reference/items/index.html#_item) |

<a id="_responses"></a>

#### Responses

| HTTP Code | Description | Schema |
| --- | --- | --- |
| **200** | The item was successfully updated | No Content |
| **401** | Access token is missing or invalid | No Content |
| **404** | The item type is not configured for this environment or the item id is not yet known in the system | No Content |
| **415** | The item information provided does not match the item information specification | No Content |
| **422** | The body is not of the right type, JSON expected | No Content |

<a id="_consumes"></a>

#### Consumes

-   `application/json`
    

<a id="_tags"></a>

#### Tags

-   env
    

<a id="_curl_example"></a>

#### cURL Example

```console
$ curl --location --request PUT 'https://{subdomain}.froomle.com/api/{environment}/items/{item_type}/client_item_id_001' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer X' \
--data-raw '{
   "environment": "{environment}",
	"item_id": "client_item_id_001",
	"item_type": "article",
  "title": "Froomle title",
  "description": "Lorem ipsum ... Article/product full text",
	"uri": "https://www.froomle.com/client_item_id_001",
	"categories": [
        "/Sports/Football",
        "/News/National"
    ],
    "tags": [
        "Red Devils",
        "Martinez",
        "Heizel",
        "Qatar2022"
    ],
	"images": [
        "https://www.froomle.com/content/client_item_id_001.jpg"
    ],
    "publication_datetime": "2021-07-29T13:02:03+02:00",
}'
```

* * *

While the `PUT` endpoint above is preferred for RESTful integrations, the `POST` endpoint below is provided for systems where the item ID is more easily included in the request body (such as webhooks).

<a id="_post_item_webhook"></a>

### Add or update an item (Webhook-friendly)

```
POST /{environment}/items/{item_type}
```

This endpoint allows you to add or update an item without specifying the `item_id` in the URL path. This is particularly useful for integrations like webhooks (e.g., from a CMS) where the full item data is sent in the request body and you want to avoid extra URL construction logic.

<a id="_parameters_2"></a>

#### Parameters

| Type | Name | Schema |
| --- | --- | --- |
| **Path** | **environment**<br>_required_ | string |
| **Path** | **item\_type**<br>_required_ | string |
| **Body** | **body**<br>_optional_ | [Item](https://docs.froomle.com/froomle-doc-main/v2/api_reference/items/index.html#_item) |

<a id="_responses_2"></a>

#### Responses

| HTTP Code | Description | Schema |
| --- | --- | --- |
| **200** | The item was successfully updated | No Content |
| **401** | Access token is missing or invalid | No Content |
| **404** | The item type is not configured for this environment | No Content |
| **415** | The item information provided does not match the item information specification | No Content |
| **422** | The body is not of the right type, JSON expected | No Content |

<a id="_consumes_2"></a>

#### Consumes

-   `application/json`
    

<a id="_tags_2"></a>

#### Tags

-   env
    

<a id="_curl_example_2"></a>

#### cURL Example

```console
$ curl --location --request POST 'https://{subdomain}.froomle.com/api/{environment}/items/{item_type}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer X' \
--data-raw '{
   "environment": "{environment}",
	"item_id": "client_item_id_001",
	"item_type": "article",
  "title": "Froomle title",
  "description": "Lorem ipsum ... Article/product full text",
	"uri": "https://www.froomle.com/client_item_id_001",
	"categories": [
        "/Sports/Football",
        "/News/National"
    ],
    "tags": [
        "Red Devils",
        "Martinez",
        "Heizel",
        "Qatar2022"
    ],
	"images": [
        "https://www.froomle.com/content/client_item_id_001.jpg"
    ],
    "publication_datetime": "2021-07-29T13:02:03+02:00",
}'
```

* * *

<a id="_environment_6a97509983258dd6"></a>

### Delete an item from the catalog

```
DELETE /{environment}/items/{item_type}/{item_id}
```

<a id="_parameters_3"></a>

#### Parameters

| Type | Name | Schema |
| --- | --- | --- |
| **Path** | **environment**<br>_required_ | string |
| **Path** | **item\_id**<br>_required_ | string |
| **Path** | **item\_type**<br>_required_ | string |

<a id="_responses_3"></a>

#### Responses

| HTTP Code | Description | Schema |
| --- | --- | --- |
| **200** | The item was successfully disabled | No Content |
| **401** | Access token is missing or invalid | No Content |
| **404** | The item id is not yet known in the system | No Content |

<a id="_tags_3"></a>

#### Tags

-   env
    

<a id="_curl_example_3"></a>

#### cURL Example

```console
$ curl --location --request DELETE 'https://{subdomain}.froomle.com/api/{environment}/items/{item_type}/client_item_id_001' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer X'
```

* * *

<a id="_items_api_items_enable_item"></a>

### Enable the item, can be used to re-enable a previously disabled item.

```
POST /{environment}/items/{item_type}/{item_id}/enable
```

<a id="_parameters_4"></a>

#### Parameters

| Type | Name | Description | Schema |
| --- | --- | --- | --- |
| **Path** | **environment**<br>_required_ | The environment for which you want to enable an item | string |
| **Path** | **item\_id**<br>_required_ | The item to enable | string |
| **Path** | **item\_type**<br>_required_ | The item\_type of the item to be enabled | string |

<a id="_responses_4"></a>

#### Responses

| HTTP Code | Description | Schema |
| --- | --- | --- |
| **200** | OK | No Content |
| **400** | Error in the request | No Content |
| **500** | Error in processing the request | No Content |

<a id="_curl_example_4"></a>

#### cURL Example

```console
$ curl --location --request POST 'https://{subdomain}.froomle.com/api/{environment}/items/{item_type}/client_item_id_001/enable' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer X'
```

* * *

<a id="_items_api_items_disable_item"></a>

### Disable the item, disabling an item means it won’t be recommended again, but its data can still be used for model training.

```
POST /{environment}/items/{item_type}/{item_id}/disable
```

<a id="_parameters_5"></a>

#### Parameters

| Type | Name | Description | Schema |
| --- | --- | --- | --- |
| **Path** | **environment**<br>_required_ | The environment for which you want to disable an item | string |
| **Path** | **item\_id**<br>_required_ | The item to disable | string |
| **Path** | **item\_type**<br>_required_ | The item\_type of the item to be disabled | string |

<a id="_responses_5"></a>

#### Responses

| HTTP Code | Description | Schema |
| --- | --- | --- |
| **200** | OK | No Content |
| **400** | Error in the request | No Content |
| **500** | Error in processing the request | No Content |

<a id="_curl_example_5"></a>

#### cURL Example

```console
$ curl --location --request POST 'https://{subdomain}.froomle.com/api/{environment}/items/{item_type}/client_item_id_001/disable' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer X'
```

* * *

<a id="_environment_3ca8c2bcaec4f968"></a>

### Retrieve an item from the catalog.

```
GET /{environment}/items/{item_type}/{item_id}
```

<a id="_parameters_6"></a>

#### Parameters

| Type | Name | Schema |
| --- | --- | --- |
| **Path** | **environment**<br>_required_ | string |
| **Path** | **item\_id**<br>_required_ | string |
| **Path** | **item\_type**<br>_required_ | string |

<a id="_responses_6"></a>

#### Responses

| HTTP Code | Description | Schema |
| --- | --- | --- |
| **200** | The item was successfully retrieved | No Content |
| **401** | Access token is missing or invalid | No Content |
| **404** | The item id is not yet known in the system | No Content |

<a id="_tags_4"></a>

#### Tags

-   env
    

<a id="_curl_example_6"></a>

#### cURL Example

```console
$ curl --location --request GET 'https://{subdomain}.froomle.com/api/{environment}/items/{item_type}/client_item_id_001' \
--header 'Authorization: Bearer X'
```

* * *

<a id="_definitions"></a>

## Definitions

<a id="_item"></a>

### Item

The body of the create POST and update PUT requests, as well as the return value of GET requests.

| Name | Description | Schema |
| --- | --- | --- |
| **categories**<br>_optional_ | The relevant of the categories of the item. | < string > array |
| **environment**<br>_required_ | The environment in which the item will reside | string |
| **images**<br>_optional_ |  | < object > array |
| **item\_attributes**<br>_optional_ |  | [ItemAttribute](https://docs.froomle.com/froomle-doc-main/v2/api_reference/items/index.html#_itemattribute) |
| **item\_id**<br>_required_ | The identifier of the item | string |
| **item\_type**<br>_required_ | The type of the entity (e.g. item, article, video, …). These types are Froomle-defined, please consult your solutions architect for the correct type. | enum ({item\_type}) |
| **language**<br>_optional_ |  | string |
| **tags**<br>_optional_ |  | < string > array |
| **title**<br>_optional_ |  | string |
| **uri**<br>_optional_ |  | string |

* * *

<a id="_itemattribute"></a>

### ItemAttribute

Information that might be relevant for analysis, but not for the filtering of the recommendations.

| Name | Schema |
| --- | --- |
| **name**<br>_optional_ | string |
| **value**<br>_optional_ | object |