# 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.


---

# 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/items/using-the-items-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.