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

# Listings

> How to call the Platform API listing endpoints: addressing by listing_id or external_id, listing metadata and content cards, the navigation tree, and fetching products.

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

Listings are category, collection and campaign pages. The Platform API splits a listing page across two calls: a GET for the listing's metadata (title, breadcrumbs, subcategories, content cards) and a POST for its products.

| Endpoint | Method | Purpose |
| - | - | - |
| `/v3/listings` | GET | The full listing tree — build navigation menus from one call |
| `/v3/listings/{listing_id}` | GET | Metadata for one listing, addressed by Depict id |
| `/v3/listings/external_id/{external_id}` | GET | Metadata for one listing, addressed by your own id |
| `/v3/listings/{listing_id}/products` | POST | Products in a listing, addressed by Depict id |
| `/v3/listings/external_id/{external_id}/products` | POST | Products in a listing, addressed by your own id |

## Limits and behavior

* Every route exists in two addressing variants: by Depict `listing_id` (a UUID) or by `external_id` (the listing's id in your PIM, CMS or e-commerce platform). Use whichever id system you store.
* The products response contains no listing metadata — no title, breadcrumbs or content cards. Fetch metadata with the GET routes.
* Filters, sorting and pagination on the products endpoint work exactly as on [search](/api-guide/search); the same limits apply (cursor `limit` 1–250, `hits_per_page` 1–200, no mixing of pagination styles).
* There is no `query` field on listing requests. The per-response tracking id is `product_listing_request_id` (search: `search_request_id`) and each display carries `product_listing_result_id` (search: `search_result_id`).
* The GET routes carry a 10-second cache header — they are designed to be called on every page load.
* An unknown `listing_id` or `external_id` returns 404.
* v2's body-based addressing (`query_id` — typically the slug — plus `type` to disambiguate name collisions) does not exist on v3. v3 addresses listings by path parameter, so slug ambiguity cannot occur.
* Response fields with null values are omitted from the JSON (`exclude_none` serialization).

## The listing object

All listing endpoints return listings in this shape:

| Field | Type | Description |
| - | - | - |
| `listing_id` | string (UUID) | Depict's id for the listing |
| `external_id` | string | The listing's id in your own system. May be absent |
| `listing_type` | string | One of `category`, `campaign`, `smart_pick`, `brand`, `look`, `style`, `long_tail_collection` — see [types of listing pages](/reference/glossary/types-of-listing-pages) |
| `title` | string | Display title of the listing |
| `slug` | string | URL slug. May be absent |
| `page_url` | string | The listing's page URL, when supplied. May be absent; use your storefront route mapping otherwise |
| `image_urls` | array of strings | Images for the listing |
| `show_in_breadcrumbs` | boolean | Whether to show the listing in navigation breadcrumbs |
| `show_in_quicklinks` | boolean | Whether to show the listing in quicklinks |

## Listing metadata

`GET /v3/listings/{listing_id}` or `GET /v3/listings/external_id/{external_id}` with query parameters `merchant`, `market`, `locale` (all required) and optional `session_id`.

The response is [the listing object](#the-listing-object) plus:

| Field | Type | Description |
| - | - | - |
| `ancestors` | array of listings | Ordered ancestors, root first — use for breadcrumbs |
| `siblings` | array of listings | Listings sharing the same parent, including the requested listing itself |
| `children` | array of listings | Direct children — use for subcategory navigation |
| `content_blocks` | array | The listing's content cards, to place in the product grid |

### Content cards

Content cards are merchandising tiles (images or videos) placed in the product grid. On the wire the field is named `content_blocks`. Each element:

| Field | Type | Description |
| - | - | - |
| `span_columns` | integer | Grid columns the card spans |
| `span_rows` | integer | Grid rows the card spans |
| `row` | integer | Grid row the card is placed on |
| `position` | string | Horizontal placement: `left`, `center` or `right` |
| `content` | object | The media: `type` (`image` or `video`), `url`, optional `link`, and an optional single-line text overlay as `text` with `text_position` (one of `top-left`, `top-center`, `top-right`, `middle-left`, `middle-center`, `middle-right`, `bottom-left`, `bottom-center`, `bottom-right`) |

## Navigation tree

`GET /v3/listings` with query parameters `merchant`, `market`, `locale` (all required) and an optional repeatable `types` parameter to filter by `listing_type`.

The response is a list of [listing objects](#the-listing-object), each extended with a recursive `children` array of the same shape — the complete listing tree in one call.

## Products in a listing

`POST /v3/listings/{listing_id}/products` or `POST /v3/listings/external_id/{external_id}/products` with a JSON body:

| Field | Type | Required | Description |
| - | - | - | - |
| `merchant` | string | Yes | Your merchant identifier |
| `market` | string | Yes | Market identifier |
| `locale` | string | Yes | Locale identifier |
| `filters` | array | No | Same semantics as [search filters](/api-guide/search#filters) |
| `sort` | object | No | Same semantics as [search sorting](/api-guide/search#sorting) |
| `session_id` | string | No | Session identifier; required for the request to be tracked and attributable |
| `metadata` | object | No | String-to-string map; only use values agreed with Depict |
| `cursor` / `limit` / `page` / `hits_per_page` | — | No | [Pagination](/api-guide/search#pagination), same rules as search |

Example request:

```json theme={null}
{
  "merchant": "MERCHANT_ID",
  "market": "MARKET",
  "locale": "en",
  "limit": 40,
  "session_id": "SESSION_ID"
}
```

### Response

| Field | Type | Description |
| - | - | - |
| `displays` | array of objects | The products, one object per card. Merchant-specific product data; each display carries a `product_listing_result_id` used for [tracking](/api-guide/tracking/product-cards) |
| `n_hits` | integer | Total number of products in the listing. Not necessarily exact |
| `sorts` | array | Available sorting methods |
| `filters` | array | Available filters |
| `product_listing_request_id` | string | Identifier for this response, used in tracking |
| `cursor` | string | Cursor for the next page. Absent when there are no more results |
| `page` | integer | Echoed page index when page-based pagination was used; absent otherwise |

## Quicklinks and breadcrumbs when replacing the UI SDK

The metadata response supplies `ancestors`, `children` and `siblings`. It does
not supply a computed `quick_links` or `breadcrumbs` array.

To preserve the UI SDK's quicklink selection:

1. Select `children` when the unfiltered array is not empty.
2. Otherwise, select `siblings`.
3. Keep entries whose `show_in_quicklinks` value is `true`.
4. Keep the returned order.

For breadcrumbs, use `ancestors` in their returned order. Display entries
whose `show_in_breadcrumbs` value is `true`.

If your design also shows parent quicklinks, read them directly from the
metadata's `ancestors`. Filter these parents by `show_in_quicklinks`. Exclude
the current `listing_id` from the parent group. Remove duplicate listing IDs.
Do not require the current listing to occur in the selected quicklink group.
It usually does not occur in `children`.

Build links with your storefront's route function and the full ancestor
`slug` chain. For a child link, include the current listing's `slug` before
the child's `slug`. For a sibling link, use the current listing's ancestors.
Keep all route segments, even when a navigation flag hides a segment's label.
If a slug is absent, use your existing CMS route mapping.


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