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

Base URL

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

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.
  1. Fetch a search page for a market from that response.
  1. Render the products in the response. Each one is a product card with a title, images, a price and its sizes. Pass the response’s cursor back to get the next page.

Endpoints

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

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.