> ## Documentation Index
> Fetch the complete documentation index at: https://docs.depict.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Interfacing directly with the API

> How to call POST /v3/recommend/products: request fields, how product_ids selects the recommendation flavor, the response shape on the wire, and the status of category recommendations.

<Warning>
  The Platform API currently has two active versions. Build new integrations
  against the `/v3` endpoints — `/v3` is the successor to `/v2`. `/v2` is
  expected to be deprecated within roughly 6 months and `/v3` within roughly 9
  months, with a v4 API expected in Q4. These are expectations, not committed
  dates — confirm timelines with your Depict contact before planning a
  migration deadline.
</Warning>

If you don't want to use our API Client you can make the requests yourself. Recommendations are served by a single endpoint:

```
POST https://api.depict.ai/v3/recommend/products
```

It replaces the three v2 endpoints `/v2/recommend/products/general`, `/v2/recommend/products/product` and `/v2/recommend/products/products` — the number of ids in `product_ids` selects the behavior. The full request/response schema is in the API Reference tab, under **Platform API**.

## Limits and behavior

* `limit` is 1–128.
* No category parameter exists on `/v3/recommend/products`, and category recommendations have no v3 endpoint — see [Category recommendations](#category-recommendations).
* Valid `type` values are configured per merchant. Get your list from your Depict contact; an unconfigured combination returns an error (see [Errors](#errors)).
* Unknown request fields are silently ignored — a misspelled field name is dropped, not rejected.
* The response on the wire differs from the response model in the OpenAPI spec — see [Response](#response).

## Request

| Field | Type | Required | Description |
| - | - | - | - |
| `merchant` | string | Yes | Your merchant identifier, provided by Depict |
| `market` | string | Yes | Market identifier |
| `locale` | string | Yes | Locale identifier |
| `type` | string | Yes | The recommendation type, e.g. `cross_sell`. Configured per merchant |
| `product_ids` | array of strings | No | Zero, one or multiple product identifiers — selects the behavior, see below. Default `[]` |
| `limit` | integer | No | Maximum number of recommendations, 1–128 |
| `session_id` | string | No | Session identifier; links the request to tracking |

`product_ids` selects which recommendations you get:

| `product_ids` | Behavior | Typical placement | v2 endpoint it replaces |
| - | - | - | - |
| Empty / omitted | General recommendations for the page type | Front page | `/v2/recommend/products/general` |
| One id | Recommendations for that product | Product page | `/v2/recommend/products/product` |
| Two or more ids | Recommendations for the set of products | Cart | `/v2/recommend/products/products` |

Example request:

```json theme={null}
{
  "merchant": "MERCHANT_ID",
  "market": "MARKET",
  "locale": "en",
  "type": "TYPE",
  "product_ids": ["product-1", "product-2"],
  "session_id": "SESSION_ID"
}
```

## Response

On the wire the response is:

| Field | Type | Description |
| - | - | - |
| `displays` | array of objects | The recommendations, one object per product card. Merchant-specific product data; each display carries a `recommendation_id` used for [tracking](/api-guide/tracking/product-cards) |
| `error` | string | Error message. Absent on success |
| `variant` | integer | A/B test variant, when an experiment is running. May be absent |
| `experiment_id` | string | A/B test experiment identifier. May be absent |

<Warning>
  The OpenAPI spec declares a different response model for this endpoint
  (typed displays without `variant`/`experiment_id`). The serving code
  bypasses that model: what actually comes back is the shape above, with
  displays as untyped merchant-specific objects. Code against the wire shape
  documented here, not against the spec's declared response model.
</Warning>

## Category recommendations

<Warning>
  `POST /v2/recommend/products/category` is deprecated and closed to new
  integrations. It remains available for its existing consumers, and its
  removal is aligned with the upcoming v4 recommendations launch — not with
  the general v2 deprecation timeline. No v3 equivalent exists today, and
  `/v3/listings` is not a substitute: it serves merchandised category browsing,
  which is a different contract from category recommendations.
</Warning>

If you have an existing integration on this endpoint: it takes a v2-shaped body (`tenant`, `market`, `category_id`, `type`) and returns the same response shape as above. Do not build new functionality on it.

## Errors

* An unconfigured merchant returns 400 with `{"detail": "Merchant {merchant} not configured for recommendations."}`.
* An unconfigured `(merchant, market, type)` combination returns `{"error": "(tenant, market, type) not yet configured. Please contact Depict."}`. The message wording uses the v2 vocabulary (`tenant`) and may change — match on the presence of `error`, not on the exact message text.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.