Skip to main content
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.

​
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; 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:

​
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 plus:

​
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: 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, 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: Example request:

​
Response

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.