- 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.
/v4.
Base URL
The base URL ishttps://api.depict.ai, and every path starts with /v4. Requests need no key and no authentication header.
Quickstart
Three requests cover a first integration. Replaceacme with your store’s name.
- Read your markets and locales once, when your storefront builds or starts.
- Fetch a search page for a market from that response.
- Render the
productsin the response. Each one is a product card with a title, images, a price and its sizes. Pass the response’scursorback 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, andsort, 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,typesandrecent_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,,bgets400 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 theevents 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.
