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

# Endpoints

> Every Platform API endpoint, with its parameters and response. Covers browse, products, context, recommendations, suggest and listings.

Every path starts with `/v4/{merchant}`. [Making requests](https://docs.depict.ai/api-v4/introduction.md#making-requests) explains how to send parameters, markets and locales. [Response contract](https://docs.depict.ai/api-v4/contract.md#product) describes the product card that several endpoints return.

## browse

`GET /v4/{merchant}/browse` returns a search page or a listing page. Send a `query` for search, a `listing` for a listing page, or both to search within a listing.

| Parameter (GET) | POST field | Notes |
| - | - | - |
| `market` | `market` | Required |
| `locale` | `locale` | Optional |
| `query` | `query` | The shopper's search text, at most 512 characters. Leave it out, or send it blank, for a listing page |
| `listing` | `listing: {"id": ...}` | The listing's `id` from [listings](#listings) |
| `listing_external_id` | `listing: {"external_id": ...}` | Your own id for the listing, at most 500 characters. Send `listing` or `listing_external_id`, not both |
| `filter_by` | `filter_by` | Narrows the results. See [Filters and sorts](https://docs.depict.ai/api-v4/filters.md) |
| `sort=<field>.<asc\|desc>` | `sort: {"field", "order"}` | `relevance`, `price`, `newest`, `title`, `discount` or one of your custom sorts. Leave it out for the default order. See [Sorts](https://docs.depict.ai/api-v4/filters.md#sorts) |
| `include` | `include` | What to return besides the cards. See [Sections](#sections) |
| `cursor` | `cursor` | The `cursor` from the previous page |
| `limit` | `limit` | Products per page, 1 to 100. Default 24 |

### Sections

`include` names the sections you want besides the cards. The sections are `facets`, `sorts`, `content` and `listing`.

* Without `include` you get `facets` and `sorts`.
* Naming a section replaces that default, so send `facets,sorts,listing` to get all three.
* Send an empty `include=` for no sections.
* The [card extras](https://docs.depict.ai/api-v4/contract.md#card-extras) `attributes` and `variants` add to the cards and keep the default sections. `include=variants` returns facets and sorts too.

### Example

A listing page, filtered to red or blue products from 100 to 500, cheapest first:

```http theme={null}
GET /v4/acme/browse?market=se&locale=sv-SE&listing=4f1c0000-0000-0000-0000-000000000000&filter_by=color%3A%3D%5Bred%2Cblue%5D%20%26%26%20price%3A%5B100..500%5D&sort=price.asc&limit=24
```

The same request as a POST:

```http theme={null}
POST /v4/acme/browse

{"market": "se", "locale": "sv-SE", "listing": {"id": "4f1c0000-0000-0000-0000-000000000000"},
 "filter_by": "color:=[red,blue] && price:[100..500]", "sort": {"field": "price", "order": "asc"}}
```

### Response

| Field | Notes |
| - | - |
| `request_id` | The request's id |
| `currency` | The currency of every price in `products`, such as `SEK`. Absent when there are no products |
| `products` | [Product cards](https://docs.depict.ai/api-v4/contract.md#product) in result order, at most `limit` |
| `total` | How many products match. Absent when the total can't be counted. On some searches it grows on a later page, as more related products follow the first matches |
| `cursor` | Pass it back to get the next page. Absent on the last page |
| `facets` | In the `facets` section. Your store's filters, with values and counts. See [Facets](https://docs.depict.ai/api-v4/filters.md#facets) |
| `sorts` | In the `sorts` section. Your store's sorts, with the one in use marked `selected` |
| `content` | In the `content` section. Your store's content pages, such as articles, that match the `query`. Each has a `title`, a site-relative `url` and `highlights`, which can be `[]`, and may have a `description` and `snippet`. At most `limit`, paged with the same `cursor` as the products. `[]` when there is no query, nothing matches, or your store has no content search |
| `listing` | In the `listing` section, on a listing page. The [listing header](#listing-header) |

### Which products browse returns

* `browse` returns products a shopper can buy. It leaves out inactive products, products without a price, and products not sold in the request's market.
* If your store hides out-of-stock products, a product shows while any of its sizes is in stock in the market, or when it is exempt from auto-hide. On search, your search's own hide-out-of-stock setting applies. A search inside a listing follows the listing's stock rule. A filter on a size shows only products in stock in that size.
* Products you hide from search are left out of every request without a listing. Products you hide in a listing, or from listing pages, are left out of listing pages. A search inside a listing follows the listing's hides, not the search hides.
* A listing holds the products assigned to it and the products its rules match. A listing with neither serves an empty page, unless it has pins or hides. Then it serves your whole catalog with those applied.
* A listing that doesn't exist, or has no text in the locale's language, gets `404 unknown_listing`.
* A listing's pins and hides are read for the request's market. A market without its own uses its market group's, then your global ones. A boost or bury rule applies in the markets it names, or in every market when it names none.
* You get one card per product, as your store groups products for display. You don't get one card per variant.

### Order

This is the order when you send no `sort`.

* A listing page follows the listing's merchandising. Pins keep their slots, then come boost and bury rules, then the market's boost and bury score, then newest first.
* Search orders products by relevance to the query, using text matches and closeness in meaning. Your search boost and bury rules contribute to that score.
* Inside a listing, search rules don't apply. Pins don't apply to any search, even within a listing.
* A request with no query and no listing returns your whole catalog in merchandising order.

A sort replaces the pins and rules. On a listing page, the boost and bury score breaks its ties.

### Search

Depict's hybrid search combines keyword-based text matching with vector-based matching by meaning.

* Search uses the fields and weights in your store's **Searchable fields** setting in the portal.
* Text matching allows one typo per word, tried only when the exact words find nothing. Product codes get no typos.
* Product names support prefix matching, so the beginning of a word can match. Added searchable attributes use whole-word matching.
* Search uses only the first 100 characters of the query.
* Matching by meaning adds relevant products that may not contain the query's words.
* When nothing matches, search returns no results. Your storefront shows the no-results state you configured in the portal.
* A shopper sort changes the result order. The request remains a search.

A typed query always runs as a search. These rules follow your search settings.

* A color word filters by color. If your store has no products in that color, search returns no results.

* A query that looks like a product code, such as an SKU or article number, also searches your product code fields, and the matching products lead the page. A hyphenated code also finds a code stored without hyphens.

* Query rules apply searchandising choices per query and are configured in the portal.

* A product added by a query rule joins the results and is ranked like the other products. It is not pinned.

* Products a rule hides stay hidden when the query is the rule's term, in the request's language.

#### Text matching

Text matches the way your catalog writes it, so `t-shirt` matches "T-Shirt", and case doesn't matter. A leading `-` is a space, not an exclusion.

## products

`GET /v4/{merchant}/products` returns product cards by id, for example for a wishlist or a cart.

| Parameter | Notes |
| - | - |
| `market`, `locale` | As on every endpoint |
| `ids` | 1 to 50 ids, comma-separated, each at most 500 characters. Each is a variant's `product_id` or SKU, or a card's or colorway's `group_id` |
| `include` | [Card extras](https://docs.depict.ai/api-v4/contract.md#card-extras): `attributes`, `variants` or both |

```http theme={null}
GET /v4/acme/products?market=se&ids=V-1001-M,V-9999
```

```json theme={null}
{"request_id": "...", "currency": "SEK", "products": [{"group_id": "G-1001", "...": "..."}], "missing": ["V-9999"]}
```

* `products` follow the order of `ids`. If two ids belong to the same colorway, its card appears once, for the first id. Ids from different colorways each get a card.
* For a variant id, the card shows that variant's colorway, with that variant `selected`. For a colorway's `group_id`, the card shows that colorway, with its first variant in stock selected.
* Variant ids come back in the kind you sent, so ask by SKU and you get SKUs. If one request mixes SKUs with other ids, every card uses SKUs. When every id is a group id, variant ids come back as your storefront's ids.
* `missing` lists the ids that have no card in this market. The product is unknown, inactive, not priced there, or has no title in the locale. It is absent when every id has a card.
* `currency` is absent when `products` is empty.

## context

`GET /v4/{merchant}/context` describes your store. It takes no parameters. Call it once when your storefront builds or starts.

```json theme={null}
{
  "request_id": "...",
  "markets": [
    {
      "key": "se",
      "name": "Sweden",
      "currency": "SEK",
      "locales": ["sv-SE", "en-SE"],
      "default_locale": "sv-SE"
    }
  ],
  "recommendation_types": [
    {"type": "similar", "inputs": ["anchor"]}
  ]
}
```

* `markets` lists the markets that have a price list. Send a market's `key` as `market` on the other endpoints.
* `locales` are the locales your store can be searched in. Every market lists the same locales. `default_locale` is the market's own default.
* `recommendation_types` lists the types [`/recommendations`](https://docs.depict.ai/api-v4/recommendations) takes for your store, each with the inputs it reads. It is absent when your store has none.

## recommendations

`GET /v4/{merchant}/recommendations` returns recommended products, such as similar products on a product page. See [Recommendations](https://docs.depict.ai/api-v4/recommendations.md).

## suggest

`GET /v4/{merchant}/suggest` returns suggestions while the shopper types. Matching listings come first, then up to 4 popular searches. Popular searches leave out the shopper's own query and near-duplicates.

| Parameter | Notes |
| - | - |
| `market`, `locale` | As on every endpoint |
| `query` | Required, at most 512 characters. Send an empty `query=` before the shopper types. See [The start view](#the-start-view) |
| `limit` | How many listings to suggest, 1 to 100. Default 3 |

```http theme={null}
GET /v4/acme/suggest?market=se&locale=sv-SE&query=jack
```

```json theme={null}
{
  "request_id": "...",
  "suggestions": [
    {
      "type": "listing",
      "listing": {"id": "4f1c0000-0000-0000-0000-000000000001", "external_id": "women-jackets", "title": "Jackets", "slug": "women/jackets", "type": "category", "images": []},
      "path": ["Women"]
    },
    {"type": "query", "query": "rain jacket"}
  ]
}
```

* A listing suggestion has the listing and its `path`, the titles of its parent listings from the top level down.
* A query suggestion has a popular search to run.
* Your store gets listing suggestions, popular searches or both, as Depict has set it up. If one kind can't be loaded, you get the other, not an error.

### The start view

An empty `query=` returns what to show before the shopper types.

* Your pinned suggestion listings come first.
* A store with a saved start view gets its start-view phrases instead of popular searches, and there can be more than 4.
* If you turned suggested searches off for the start view, an empty query returns listings only.

## listings

Two endpoints share the `/listings` path: your listing tree, and one listing's header.

| Parameter (GET) | POST field | Notes |
| - | - | - |
| `market` | `market` | Required |
| `locale` | `locale` | Optional |
| Not in a GET | `types` | Tree only, and only in a POST. Returns only listings of these types, as an array such as `["category", "brand"]`. A type your store doesn't have returns an empty tree. A GET with `types` gets `400 bad_request` |
| `external_id` | `external_id` | Header only. One listing by your own id for it, at most 500 characters |

Breadcrumbs, quick links and tree nodes use a listing reference:

| Field | Notes |
| - | - |
| `id` | Depict's id for the listing. Pass it to `browse` as `listing` |
| `external_id` | Your own id for the listing. Absent when it has none |
| `title` | In the request's language. `""` when the listing has no title |
| `slug` | The listing's path on your site in the locale. Absent when it has none |

### Listing tree

`GET /v4/{merchant}/listings?market=` returns your listings in the locale, as a tree. Use it to build menus. When a listing has no text in the request's locale, v4 uses another locale of the same language. This holds for the tree and for the listing header.

Only categories, as a POST:

```http theme={null}
POST /v4/acme/listings

{"market": "se", "locale": "sv-SE", "types": ["category"]}
```

```json theme={null}
{
  "request_id": "...",
  "listings": [
    {
      "id": "4f1c0000-0000-0000-0000-000000000000",
      "external_id": "women",
      "title": "Women",
      "slug": "women",
      "type": "category",
      "children": [
        {
          "id": "4f1c0000-0000-0000-0000-000000000001",
          "external_id": "women-jackets",
          "title": "Jackets",
          "slug": "women/jackets",
          "type": "category",
          "children": []
        }
      ]
    }
  ]
}
```

* `listings` holds the top-level listings. Each node is a listing reference with `type` and `children`, to any depth.
* Children are sorted in the order you pinned them on the parent, then by title. Top-level listings are sorted by title.
* A listing is left out when it has no text in the locale's language, or when `types` doesn't name its type. Its children are left out too.
* Disabled listings are included.

### Listing header

`GET /v4/{merchant}/listings/{id}?market=`, or `GET /v4/{merchant}/listings?market=&external_id=`, returns what a listing page shows around its products. Browse returns the same header with `include=listing`.

```http theme={null}
GET /v4/acme/listings/4f1c0000-0000-0000-0000-000000000001?market=se&locale=sv-SE
```

```json theme={null}
{
  "request_id": "...",
  "listing": {
    "id": "4f1c0000-0000-0000-0000-000000000001",
    "external_id": "women-jackets",
    "title": "Jackets",
    "slug": "women/jackets",
    "type": "category",
    "show_in_breadcrumbs": true,
    "breadcrumbs": [
      {"id": "4f1c0000-0000-0000-0000-000000000000", "external_id": "women", "title": "Women", "slug": "women"}
    ],
    "quick_links": [
      {"id": "4f1c0000-0000-0000-0000-000000000002", "external_id": "women-rain-jackets", "title": "Rain jackets", "slug": "women/jackets/rain"}
    ],
    "images": [],
    "content_blocks": []
  }
}
```

| Field | Notes |
| - | - |
| `id`, `external_id`, `title`, `slug` | As in a listing reference |
| `type` | `category`, `campaign`, `brand`, `style` or `look`. More types may be added |
| `show_in_breadcrumbs` | Whether to show the listing itself as the last breadcrumb |
| `breadcrumbs` | The parent listings set to show in breadcrumbs, top level first, up to 8 levels. Add the listing itself last when `show_in_breadcrumbs` is `true` |
| `quick_links` | The listings set to show as quick links. They are the listing's children. When it has no children, they are its siblings of the same type, the listing itself included |
| `images` | Image URLs. `[]` when none |
| `content_blocks` | Merchandising tiles in the listing's product grid. See below |

Breadcrumbs and quick links come ready to render. Quick links follow the order you pinned them in, then title. Parents, siblings and children without text in the locale's language are left out.

A listing that doesn't exist, or has no text in the locale's language, gets `404 unknown_listing`. Sending both an id and an `external_id` gets `400 bad_request`. Disabled listings are served.

A content block:

| Field | Notes |
| - | - |
| `row` | The grid row it starts on |
| `position` | `left`, `right` or `center` |
| `span_columns`, `span_rows` | How many columns and rows it covers |
| `aspect_ratio` | `1.5` on a landscape block that keeps its own 3:2 shape. Absent on a block sized by the grid |
| `visibility` | `desktop` or `mobile` when the block shows on that kind of device only. Absent when it shows on every device. Treat a value you don't know as absent |
| `content.type` | `image` or `video` |
| `content.url` | The image or video |
| `content.link` | Where the block links to. Absent when it has no link |
| `content.text` | Overlay text, one line, at most 140 characters. Absent when none |
| `content.text_position` | `top`, `middle` or `bottom`, then `left`, `center` or `right`, joined by a hyphen, such as `top-left`. Default `bottom-center` |
| `content.cta` | Call-to-action text, one line, at most 60 characters. Absent when none |


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