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