# Catalog API overview

> The catalog calls, one page each, and the authentication, request format, responses and limits they share.

The catalog API creates, updates, deletes and resyncs the products of one shop. Each call has its own page:

| Call                                                                                           | Endpoint                                 | What it does                                                           |
| ---------------------------------------------------------------------------------------------- | ---------------------------------------- | ---------------------------------------------------------------------- |
| [Create or update products](https://releva.ai/documentation/reference/catalog/create-or-update-products/)       | `POST /products`                         | Send new and changed products, with variants, languages and markets    |
| [Update product availability](https://releva.ai/documentation/reference/catalog/update-product-availability/)   | `POST /products/availability`            | Change only `available` on existing products                           |
| [Delete a product](https://releva.ai/documentation/reference/catalog/delete-a-product/)                         | `DELETE /products/{id}`                  | Remove one product for good                                            |
| [Let Releva pull your catalog](https://releva.ai/documentation/reference/catalog/let-releva-pull-your-catalog/) | your endpoint, and `POST /products/sync` | The endpoint Releva reads in a full sync, and the call that starts one |

All endpoints are under `https://releva.ai/api/v0`. For how these fit together, read [How your catalog gets into Releva](https://releva.ai/documentation/learn/catalog/how-your-catalog-gets-into-releva/). The generated field-by-field reference for each endpoint lives in the API reference.

## Authentication

Send your shop’s secret key as a bearer token:

```plaintext
authorization: Bearer $RELEVA_SECRET_KEY
```

The key is a UUID and identifies the shop (domain). Everything you send applies to that shop; there is no shop id in the body. Find the key in the Releva admin under **Settings › Shop & Integration**.

Authentication failures answer **`400`**, not `401`:

| Problem                        | Message                                                                       |
| ------------------------------ | ----------------------------------------------------------------------------- |
| No `authorization` header      | `Authorization header is missing.`                                            |
| Header is not `Bearer <token>` | ``Authorization header is malformed. It should look like `Bearer <string>`.`` |
| Token is not a UUID            | `Authorization header contains an invalid Bearer token.`                      |
| No shop has this key           | `Domain with the provided secret key cannot be found.`                        |

A shop that has been switched off answers **`402`** with `Domain is disabled. Please reach out to support@releva.ai to enable it.`

## Request format

* HTTPS only. Plain HTTP answers `400 {"message":"We do not support non-HTTPS requests."}`.
* Send JSON with `content-type: application/json`. With any other content type the body is not parsed and you get `400 {"message":"The '' field is required."}`.
* Bodies are limited to **800 KB**. Larger bodies answer `413 {"message":"request entity too large"}`. There is no maximum number of products per request other than that limit. Split large catalogs into batches of a few hundred products.
* Product objects are validated strictly: any key that is not in the schema is rejected.

## Responses

Every successful call answers **`202 Accepted`** with the body `{}`. Processing is asynchronous; the change is visible a few seconds later. See [Writes are asynchronous](https://releva.ai/documentation/learn/catalog/how-your-catalog-gets-into-releva/#writes-are-asynchronous).

Errors have one shape:

```plaintext
{ "message": "The 'products[0].listPrice' field must be a number. The 'products[0].categories' field is required." }
```

There is no error code or field property. When several fields fail validation, the messages are joined with a space.

| Status | When                                                                                    |
| ------ | --------------------------------------------------------------------------------------- |
| `202`  | Accepted and queued                                                                     |
| `400`  | Authentication failed, validation failed, or the body could not be parsed               |
| `402`  | The shop is disabled                                                                    |
| `413`  | Body larger than 800 KB                                                                 |
| `500`  | Unexpected error. The body is `{"message":"An internal error occurred."}`. Retry later. |

## Limits

* Body size: 800 KB per request.
* Rate limits: none on the catalog endpoints. Be reasonable; one request per product change or batches of a few hundred products are both fine.
* Processing: one queued write per product. Ingestion is usually complete within about 10 seconds.

## Versioning

All catalog endpoints are under `/api/v0`. Changes are listed in the [API changelog](https://releva.ai/documentation/changelog/api/). Unknown fields are rejected, so new fields are safe to add only after they appear in the reference.

## Next steps

* [Create or update products](https://releva.ai/documentation/reference/catalog/create-or-update-products/): Start with the call that sends your products, with a field table and a working request.
* [How your catalog gets into Releva](https://releva.ai/documentation/learn/catalog/how-your-catalog-gets-into-releva/): Learn how products are identified, merged and made visible after you send them.
* [Find a product in your catalog](https://releva.ai/documentation/guides/catalog/find-a-product/): Search for a product in the admin to check what Releva stored.