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

# Using the Streaming Items API

{% hint style="warning" %}
[<mark style="color:orange;">This API requires Authentication.</mark>](/product-discovery/sending-and-managing-product-data/what-is-the-items-api/authorization-to-apis.md)
{% endhint %}

{% hint style="info" %}
Required fields are marked with a red asterisk (<mark style="color:red;">\*</mark>) in the **Name** column.
{% endhint %}

Use the streaming Items API for partial real time item updates throughout the day.

## Upsert items

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

This endpoint allows you to create or modify a list of items.

#### Query Parameters

| Name                                          | Type   | Description                                                                       |
| --------------------------------------------- | ------ | --------------------------------------------------------------------------------- |
| tenant<mark style="color:red;">\*</mark>      | string | Your tenant[^1] ID                                                                |
| environment<mark style="color:red;">\*</mark> | string | Your environment[^2] ID                                                           |
| 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](/product-discovery/sending-and-managing-product-data/what-is-the-items-api/authorization-to-apis.md) |

#### Request Body

| Name                                    | Type  | Description   |
| --------------------------------------- | ----- | ------------- |
| items<mark style="color:red;">\*</mark> | array | List of items |

{% tabs %}
{% tab title="200 Return a list of receipt ids" %}

```
[
 {
  itemId: {{item id}},
  receiptId: {{receipt id}}
 }
]
```

{% endtab %}

{% tab title="400: Bad Request tenant and environment are required" %}

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

{% endtab %}

{% tab title="401 see Troubleshooting api errors" %}

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

{% endtab %}
{% endtabs %}

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

```json
[
    {
        "id": "A0001",
        "catalogVersion": 1,
        "type": "product",
        "attributes": {
            "title": "My item",
            "description": "This is my item.",
            "categories": [ "category_id_1","category_id_2"]
        }
    }
]
```

{% endcode %}

{% hint style="warning" %}
If a category tree has been defined for a catalogue version, the categories attribute becomes mandatory.
{% endhint %}

{% hint style="info" %}
Please keep the message size of each API call under 1MB for better performance.
{% endhint %}

## Patch items

<mark style="color:purple;">`PATCH`</mark> `https://items.attraqt.io/items`

This method allows you to patch attributes of given items.

Unlike the upsert, patch an item will only update attributes that are present in the request. It means that you don't need to send the whole item, but only the updated attributes.

#### Query Parameters

| Name                                          | Type   | Description                                                                       |
| --------------------------------------------- | ------ | --------------------------------------------------------------------------------- |
| tenant<mark style="color:red;">\*</mark>      | string | Your tenant[^1] ID                                                                |
| environment<mark style="color:red;">\*</mark> | string | Your environment[^2] ID                                                           |
| 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                            |
| --------------------------------------- | ----- | -------------------------------------- |
| items<mark style="color:red;">\*</mark> | array | List of items with attributes to patch |

{% tabs %}
{% tab title="200 Return a list of receipt ids" %}

```
[
 {
  itemId: {{item id}},
  receiptId: {{receipt id}}
 }
]
```

{% endtab %}

{% tab title="400: Bad Request tenant and environment are required" %}

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

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Mandatory attributes aren't checked with this method. Only the attribute's types are validated.
{% endhint %}

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

```json
[
    {
        "id": "A0001",
        "catalogVersion": 1,
        "type": "product",
        "attributes": {
            "title": "My patched title",
        }
    }
]
```

{% endcode %}

## Delete items

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

This endpoint allows you to delete items.

#### Query Parameters

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

#### Headers

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

#### Request Body

| Name                                       | Type  | Description      |
| ------------------------------------------ | ----- | ---------------- |
| item IDs<mark style="color:red;">\*</mark> | array | List of item IDs |

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

```
[
 {
  itemId: {{item id}},
  receiptId: {{receipt id}}
 }
]
```

{% endtab %}
{% endtabs %}

{% code title="Example of item deletion body" %}

```json
[
    {
        "id": "A0001",
        "catalogVersion": 1,
        "type": "product"
    }
]
```

{% endcode %}

[^1]: A tenant represents a customer or group of customers using Product Discovery features. It is a distinct entity with its own users, service accounts, environments and specific configurations. This allows for the segmentation and management of resources and permissions in an isolated and secure way for each customer or group of customers.

[^2]: An environment is a distinct entity within a tenant, representing a specific configuration for the deployment and use of the Product Discovery features on customer side. It is used to separate different instances or versions of the application according to the customer’s needs, whether these relate to the development, test or production phase. Some customers may have a specific environment for each country in which they operate.