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

# Introduction

> The Depict Platform API serves search, listing pages, product cards and recommendations for your storefront. How to get access, make requests and read responses.

The Platform API serves the product data your storefront shows. You send a request for a search page, a listing page, a set of products or a row of recommendations. You get back product cards in the order to show them, with prices and stock for the shopper's market.

* One endpoint, `browse`, serves both search pages and listing pages.
* Every endpoint returns the same small product card. You ask for more fields only where a page needs them.
* Every response follows a typed contract with a version number.

The current version is v4, and every path starts with `/v4`.

| Page | What it covers |
| - | - |
| This page | The base URL, endpoints, how to make requests, response headers |
| [Endpoints](https://docs.depict.ai/api-v4/endpoints.md) | Parameters and responses for each endpoint |
| [Filters and sorts](https://docs.depict.ai/api-v4/filters.md) | The `filter_by` syntax, facets and sorts |
| [Response contract](https://docs.depict.ai/api-v4/contract.md) | The product card, colorways, card extras, versioning and error codes |
| [Merchant attributes](https://docs.depict.ai/api-v4/attributes.md) | Fields on the card that only your store defines |
| [Recommendations](https://docs.depict.ai/api-v4/recommendations.md) | Recommendation types, inputs and errors |
| [Events](https://docs.depict.ai/api-v4/events.md) | How to report impressions, clicks, carts and purchases |
| [Upgrade from v3/v2](https://docs.depict.ai/api-v4/upgrade.md) | What to change in an integration built on the v3 or v2 endpoints |

## Base URL

The base URL is `https://api.depict.ai`, and every path starts with `/v4`. Requests need no key and no authentication header.

```bash theme={null}
curl -s "https://api.depict.ai/v4/acme/context"
```

## Quickstart

Three requests cover a first integration. Replace `acme` with your store's name.

1. Read your markets and locales once, when your storefront builds or starts.

```bash theme={null}
curl -s "https://api.depict.ai/v4/acme/context"
```

2. Fetch a search page for a market from that response.

```bash theme={null}
curl -s "https://api.depict.ai/v4/acme/browse?market=se&locale=sv-SE&query=jacket"
```

3. Render the `products` in the response. Each one is a [product card](https://docs.depict.ai/api-v4/contract.md#product) with a title, images, a price and its sizes. Pass the response's `cursor` back to get the next page.

## Endpoints

| Endpoint | What it returns |
| - | - |
| [`GET /v4/{merchant}/browse`](https://docs.depict.ai/api-v4/endpoints#browse) | A search page or a listing page, with products, facets and sorts |
| [`GET /v4/{merchant}/products`](https://docs.depict.ai/api-v4/endpoints#products) | Product cards by id |
| [`GET /v4/{merchant}/context`](https://docs.depict.ai/api-v4/endpoints#context) | Your markets, locales and recommendation types |
| [`GET /v4/{merchant}/recommendations`](https://docs.depict.ai/api-v4/recommendations) | Recommended products |
| [`GET /v4/{merchant}/suggest`](https://docs.depict.ai/api-v4/endpoints#suggest) | Suggestions while the shopper types a search |
| [`GET /v4/{merchant}/listings`](https://docs.depict.ai/api-v4/endpoints#listings), [`GET /v4/{merchant}/listings/{id}`](https://docs.depict.ai/api-v4/endpoints#listing-header) | Your listing tree, or one listing's header |
| [`POST /v4/{merchant}/events`](https://docs.depict.ai/api-v4/events) | Takes the events your storefront reports. POST only |

## Making requests

### Path

Every path is `/v4/{merchant}/{endpoint}`. `merchant` is your store's name in Depict, in lowercase, such as `acme`. An unknown name gets `404 unknown_merchant`.

### GET or POST

Every endpoint that returns data takes a GET with a query string. You can also send a POST with the same parameters as one JSON object in the body. Both give the same answer, so use POST when a request is too long for a URL.

In a POST body, lists are JSON arrays, and `sort`, `listing`, `anchor` and each entry of `recent_views` are objects. Each endpoint shows its POST fields. A few rules apply to every such POST. [`events`](https://docs.depict.ai/api-v4/events) has its own body format.

* The body is a JSON object of at most 64 KiB. An endpoint without parameters still needs `{}`.
* An unknown field gets `400 bad_request`.
* A POST can't also have a query string.
* Any content type works.

### Query strings

* Separate list values with commas. The lists are `ids`, `cart`, `exclude`, `include`, `types` and `recent_views`. Send a comma inside an id as `%2C`.
* `+` means a space. Send a literal plus as `%2B`.
* An unknown parameter, a parameter sent twice, or an empty item in a list such as `ids=a,,b` gets `400 bad_request`.

### Market and locale

Every endpoint that returns data, except `/context`, needs a `market`. Use the market's `key` from [`/context`](https://docs.depict.ai/api-v4/endpoints#context). The API also accepts the market's name, and a two-letter country code when a market is named after that country.

`locale` is optional. It is a language tag such as `sv-SE`, and `sv_SE` works too. Without a locale, the market's `default_locale` from `/context` applies. If your store has more than one language, send the locale on every request so the language never depends on a default.

If no locale matches exactly, the API uses one with the same language, so `sv-FI` gets a Swedish locale. The Norwegian tags `no` and `nn` fall back to your `nb` locale.

* A market that matches nothing, or has no prices, gets `404 unknown_market`.
* A locale that matches no language of your store gets `404 unknown_locale`.
* A locale that isn't a language tag gets `400 bad_request`.

### Ids

Ids are strings from your own catalog. In a POST body, send every id as a JSON string, numeric ids too. If your storefront writes a variant id as `<item id>-<variant id>`, such as `14356-9065`, send that form and the API answers in it. Apart from `request_id` and each card's `tracking_id`, the only Depict ids you see are listing ids.

### Pages

`browse` returns one page at a time. Pass the `cursor` from a response to get the next page. `limit` sets the page size, from 1 to 100, and defaults to 24. A cursor that didn't come from a response gets `400 bad_request`.

## Tracking

Depict learns from what shoppers click and buy, so report those actions to the [`events`](https://docs.depict.ai/api-v4/events) endpoint. Every product card has a `tracking_id`. Send it back on the card's impression and click events.

Send the header `track: false` on requests no shopper sees, such as tests and server-side checks. Depict then records no clicks or views for the cards in that response. Requests from known crawlers are never tracked.

## Response headers

| Header | What it holds |
| - | - |
| `x-depict-request-id` | The request's id. The body has it too, as `request_id`, or `error.request_id` on an error. Include it when you report a problem |
| `x-depict-contract` | The contract version the body follows, `6.0`. See [Versioning](https://docs.depict.ai/api-v4/contract.md#versioning). Can be missing on an unexpected `500` |
| `allow` | On a `405`, the methods the path takes |
| `cache-control` | `no-store` |

Responses expose `x-depict-request-id` and `x-depict-contract` to your code. Other `x-depict-*` headers are for Depict's diagnostics. Don't rely on them.


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