# Catalog API (Private Beta)

This API allows you to manage your product catalog dynamically, bypassing the traditional CMS feed integration. The Catalog API acts as a separate integration type and is visible in the integrations settings like other integration methods.

{% hint style="info" %}
Catalog API cannot work alongside a standard catalog integration. You must choose to use either the Catalog API or a catalog Feed/CMS integration for your catalog management.
{% endhint %}

### Catalog API authentication

To manage your catalog securely, the API uses a dedicated API key that is only authorized to manage the catalog. The standard recommendation API key does not have permission to edit the catalog.

To use the Catalog API endpoints, you must generate a **Catalog API key** and authenticate all your requests with it.

```
curl 'https://api-catalog.abtasty.com/ENDPOINT' \
-H 'authorization: Bearer CATALOG_API_KEY'
```

### Catalog structure management

#### Catalog item fields requirements

Catalog items are represented as objects that must contain the following fields:

* **Mandatory fields**: Every catalog item must include the following fields:
  * **`id`** : the unique ID of the item. It should be a `string` of 40 characters maximum.
  * **`is_recommendable`**: a true/false `boolean` indicating if your product can be recommended.
  * **`name`**: the display name of the item. It should be a `string` or `null`.
  * **`absolute_link`**: the PDP url of the item. It should be a `string` or `null`.
  * **`img_link`**: the main image url of the item. It should be a `string` or `null`.
  * **`price`**: the price of the item. It should be a `number` or `null`.
  * **`categories_ids`**: the categories of the item. It should be a `array of string` or `null`.
* **Required to connect with your analytics solution:** These fields are the keys that will be used to link your analytics events to your catalog items. [Learn more on analytics documentation](/recommendations-and-merchandising/how-tos/how-to-configure-your-analytics-integration.md)
  * **`item_purchase_key`**: an identifier accessible in your `purchase` event properties that will be the link between the purchase event and the item. Product id or product key is often used here. It should be an `array of string` or `null`.
  * **`item_pageview_key`**: an identifier accessible in your `pageview` event properties that will be the link between the pageview event and the item. Product canonical url or product id is often used here. It should be an `array of string` or `null`.
* **Custom fields**: You can define as many custom fields as you need by adding them to the payload. Each field sent in the payload will be dynamically added to your catalog schema.

*Example of a catalog item object:*

```
{
    // Mandatory fields
    "id": "my-unique-id",
    "is_recommendable": true,
    "name": "My product name",
    "absolute_link": "https://e-commerce.com/p/my-product-url",
    "img_link": "https://cdn.e-commerce.com/p/my-product/main-image",,
    "price": 14.02,
    "categories_ids": ["category_A", "category_B"],
    // Required for analytics link
    "item_purchase_key": ["my-purchase-item-key"],
    "item_pageview_key": ["https://e-commerce.com/p/my-product-url"],
    // Custom fields
    "custom_field_1": "xyz",
    "color": "red",
    "availability_per_shop": ["001": true, "002": false, "003": true],
    ...
}
```

#### Dynamic catalog schema & typing constraints

Catalog API schema is dynamic. When sending product data through the API, catalog item fields are accepted and created dynamically based on your payload.

The API strictly enforces data types. A custom field's data type is determined by the first value sent through the API. For example*: if you create a product with the field "color" and the value "red", a catalog field named "color" is automatically created and assigned the type "string". All future products with a field "color" should now have either an empty value or a string value.* 

#### Supported fields types

* String
* Number
* Boolean
* Array of string \[String]
* Object of strings \[String:String]
* Object of numbers \[String:Number]
* Object of booleans \[String:Boolean]

### Catalog API Endpoints (v1)

{% hint style="info" %}
Base domain is `https://api-catalog.abtasty.com/`
{% endhint %}

#### Add or replace a product

`PUT /indexes/catalog/{itemID}`

Description: Use this endpoint to add a new product or entirely replace an existing product in the catalog based on its `itemID`.

Payload example:

```
{
    "id": "my-unique-id",
    "is_recommendable": true,
    "name": "My product name",
    "absolute_link": "https://e-commerce.com/p/my-product-url",
    "img_link": "https://cdn.e-commerce.com/p/my-product/main-image",,
    "price": 14.02,
    "categories_ids": ["category_A", "category_B"],
    "item_purchase_key": ["my-purchase-item-key"],
    "item_pageview_key": ["https://e-commerce.com/p/my-product-url"],
    "custom_field_1": "xyz",
    ...
}
```

#### Delete a product

`DELETE /indexes/catalog/{itemID}`

Description: Deletes a single product from the catalog matching the specified `itemID`.

Payload example:

```
{
    "id": "my-unique-id",
}
```

#### Delete all products

`DELETE /indexes/catalog`

Description: Deletes all products from the catalog while keeping in memory the existing schema.

Payload: null

#### Batch operations

`POST /indexes/catalog/batch`

Description: This endpoint allows you to add, replace, or delete multiple products in the catalog using a single API request.

Batch size limit: Payload size should be less than 50MB and maximum 10 000 operations per call.

Payload example:

```
[
  {
    "operation":"create-replace",
    "product": {
        "id": "my-unique-id",
        "is_recommendable": true,
        "name": "My product name",
        "absolute_link": "https://e-commerce.com/p/my-product-url",
        "img_link": "https://cdn.e-commerce.com/p/my-product/main-image",,
        "price": 14.02,
        "categories_ids": ["category_A", "category_B"],
        "item_purchase_key": ["my-purchase-item-key"],
        "item_pageview_key": ["https://e-commerce.com/p/my-product-url"],
        ...
    }
  },
  {
    "operation":"delete",
    "product":{ "id": "my-unique-id-2" }
  },
  ...
]
```

### Catalog synchronization recurrence

When building your integration with Catalog API, be aware of the following technical limitations and synchronization behaviors:

* Catalog API operations are validated synchronously.
* The catalog visible in the platform and used for your strategy results is only updated after a synchronization job runs, not after each API call. By default, synchronization runs once per day. The update frequency can be increased according to your needs.


---

# 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://docs.abtasty.com/recommendations-and-merchandising/reference/catalog-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.