Custom search UI: quickstart - Depict Documentation

This API will be removed at the end of this year. It is the current-generation storefront search API, and it is the supported and recommended way to build a custom search UI today — the Depict search modal runs on exactly these endpoints. A successor API is coming, and every team building on this one should plan for a migration before year end. Migration documentation will follow; ask your Depict contact to be notified when it is published.

This guide is for developers building a custom search interface against the Depict storefront search API. It covers the four calls a working search UI needs, plus the tracking events that keep analytics and attribution intact. The API is public and unauthenticated for the read endpoints: it is called directly from the shopper’s browser, and every request identifies the store with a merchant id. There is no API key to manage for search.

What you need

Value	Example	Where it comes from
`merchant_id`	`search-1234567890`	Depict onboarding. On a Shopify store running the Depict app it is `search-` followed by your Shopify shop ID.
`locale`	`en`	The storefront language. Drives translated product attributes and the localized UI strings the API returns.
`country`	`US`	ISO 3166-1 alpha-2 country of the shopper. Resolved server side to one of your Shopify markets, which determines prices, currency and availability.

locale and country are required on every request. A country that is not mapped to one of your markets returns 404, as does an unknown merchant_id.

Base URL

https://runway.depict.ai

1. Run a search

POST /search_v2 is a plain HTTPS POST — one request per page, no WebSocket or Server-Sent Events — whose response body is streamed as newline-delimited key:value lines, so you can render products before the response has finished. Each line is a key, a colon, then JSON. If you would rather not stream, await the whole body and split it on newlines; both patterns are in REST or streaming?.

curl -N https://runway.depict.ai/search_v2 \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/x-ndjson' \
  -d '{
    "query": "loafers",
    "merchant_id": "YOUR_MERCHANT_ID",
    "locale": "en",
    "country": "US",
    "page": 1,
    "session_id": "SESSION_ID",
    "search_id": "SEARCH_ID"
  }'

async function search(body, onEvent) {
  const response = await fetch("https://runway.depict.ai/search_v2", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Accept: "application/x-ndjson",
    },
    body: JSON.stringify(body),
  });
  if (!response.ok || !response.body) {
    throw new Error(`Search failed: ${response.status}`);
  }

  const reader = response.body.getReader();
  const decoder = new TextDecoder();
  let buffer = "";
  // Some keys arrive as several fragments; accumulate per key and parse when complete.
  const accumulated = {};

  for (;;) {
    const { value, done } = await reader.read();
    if (done) break;
    buffer += decoder.decode(value, { stream: true });

    let newline;
    while ((newline = buffer.indexOf("\n")) !== -1) {
      const line = buffer.slice(0, newline);
      buffer = buffer.slice(newline + 1);

      const colon = line.indexOf(":");
      if (colon === -1) continue;
      const key = line.slice(0, colon);
      accumulated[key] = (accumulated[key] ?? "") + line.slice(colon + 1);

      try {
        onEvent(key, JSON.parse(accumulated[key]));
      } catch {
        // Not a complete JSON value yet — wait for the next fragment.
      }
    }
  }
}

await search(
  {
    query: "loafers",
    merchant_id: "YOUR_MERCHANT_ID",
    locale: "en",
    country: "US",
    page: 1,
    session_id: sessionId,
    search_id: searchId,
  },
  (key, value) => {
    if (key === "keyword") renderProducts(value);
    if (key === "keyword_page_info") setPagination(value);
    if (key === "filter_facets") setAvailableFilters(value);
    if (key === "error") showError(value.error_hint);
  }
);

A default response contains four lines, always in this order:

filter_facets:["colors","material","product_type"]
sorts:[{"field":"_relevance","order":"desc","meta":{"values":["desc"]}},{"field":"price","order":"asc","meta":{"values":["asc","desc"]}}]
keyword:[{"id":"9606764101971","title":"Karlberg – Black Calf","price":399.0, ...}]
keyword_page_info:{"page":1,"has_next_page":true,"has_prev_page":false,"is_fallback":false,"n_hits":33}

keyword is the product array — the field is not called products.
filter_facets lists the filter field names enabled for your account, not values or counts.
sorts lists the sort options your account offers, on every response. Read the sort request field’s allowed values from here rather than hardcoding them.
keyword_page_info carries pagination: has_next_page says whether to request the next page, n_hits is the total. Page size is the request’s limit (default 30, up to 250). See Pagination.
error can appear mid-stream if retrieval fails after headers were sent. The search failed — render an error state. See Retries for why this case is not the same as a failed request.

See the API reference for every field, every stream key, filters and pagination.

search_id identifies one search. Generate a new one when the shopper submits a query, and reuse it for the pages of that search and for every tracking event about its results. Changing a filter is a new search — the modal mints a fresh search_id for it, because the shopper is now looking at a different result set. Reusing the old id there would merge two result sets into one row in your analytics. session_id is one id per browser tab, stable across searches.

2. Query suggestions

GET /autocomplete_v2 returns up to three suggestions for a partial query. Call it as the shopper types.

curl -G https://runway.depict.ai/autocomplete_v2 \
  --data-urlencode 'query=loaf' \
  --data-urlencode 'merchant_id=YOUR_MERCHANT_ID' \
  --data-urlencode 'locale=en' \
  --data-urlencode 'country=US'

const params = new URLSearchParams({
  query: "loaf",
  merchant_id: "YOUR_MERCHANT_ID",
  locale: "en",
  country: "US",
});
const response = await fetch(
  `https://runway.depict.ai/autocomplete_v2?${params}`
);
const { suggestions } = await response.json();

{ "suggestions": ["loaf**ers**", "loaf**ers in dark brown suede**"] }

Suggestions are markdown: **bold** marks the part the shopper has not typed yet. Render the markdown, but search the plain text — strip the markers before passing the suggestion to /search_v2, or the query will not match. Responses are CDN-cached, so late responses for an earlier keystroke can arrive after newer ones. Track which query each response belongs to and ignore stale ones.

3. Empty state

Before the shopper types anything, GET /empty-state-products gives you products to show, starter suggestions, and the localized UI strings for your locale.

curl -G https://runway.depict.ai/empty-state-products \
  --data-urlencode 'merchant_id=YOUR_MERCHANT_ID' \
  --data-urlencode 'locale=en' \
  --data-urlencode 'country=US'

{
  "products": [ /* same product shape as search */ ],
  "total_count": 6,
  "suggestions": ["What shoes should I wear to a wedding?", "..."],
  "localized_strings": { "view_all": "View all", "no_results": "...", "...": "..." }
}

localized_strings holds 46 translated interface strings (button labels, facet labels, sort labels, empty and error messages). Using them keeps a custom UI translated in every locale you already support, and picks up merchant-specific overrides configured in Depict.

4. Send tracking events

Analytics in the Depict portal, and the ranking that feeds on it, come from client-side events. A custom UI must send them itself — nothing is inferred server side from a search request.

curl https://runway.depict.ai/events \
  -H 'Content-Type: text/plain' \
  -d '[{
    "event_type": "product_click",
    "merchant_id": "YOUR_MERCHANT_ID",
    "session_id": "SESSION_ID",
    "device_id": "DEVICE_ID",
    "locale": "en",
    "country": "US",
    "search_id": "SEARCH_ID",
    "product_id": "9606764101971",
    "query": "loafers",
    "position": 0
  }]'

At minimum, send product_impression and product_click for search results, and add_to_cart and purchase with the search_id of the search that led to them. Full event list, required fields and the attribution rules are in Tracking events.

Behaviour worth knowing before you build

Pagination is page-based. Send the same body with page: 2 for the next limit products (default 30, up to 250). has_next_page is true exactly when a page came back full, so a page past the end is empty rather than an error. Keep search_id across the pages of one search; a query, filter or sort change is a new search with a new id and page: 1. Rules and a worked three-request example are under Pagination.
Filters re-run the search. There is no separate filter endpoint: add a filters array to the same /search_v2 request. Debounce rapid filter toggles, and cancel the in-flight request when a new one starts.
Sorting is a request field. Add sort: { "field": "created", "order": "desc" } to the same /search_v2 request to reorder results server-side, with correct ordering across pages. Read the offered options from the response’s sorts: line rather than hardcoding them — an unoffered field/order combination returns 422 naming what is offered, never a silently different ordering. Omit the field for relevance order.
is_fallback: true means no good match was found for the query as typed and a relaxed search answered instead. The Depict modal labels these results as close matches rather than presenting them as exact hits.
Retries. The modal retries a failed request twice — three attempts in total — with a randomised 0.5–2s wait between them. That covers non-200 responses and dropped connections. A mid-stream error line is not retried: the modal stops and shows an error, because the server already decided the search failed. Decide deliberately which of the two your UI does.
Response size. Cap how much you read from a stream. The Depict modal aborts a /search_v2 response after 100 kB.

API reference

Every endpoint, field, stream key and filter.

Filters and suggestions

Building filter controls and rendering suggestions, and the traps in both.

Tracking events

The events to send, and how attribution works.

​What you need

​Base URL

​1. Run a search

​2. Query suggestions

​3. Empty state

​4. Send tracking events

​Behaviour worth knowing before you build

​Next

API reference

Filters and suggestions

Tracking events

What you need

Base URL

1. Run a search

2. Query suggestions

3. Empty state

4. Send tracking events

Behaviour worth knowing before you build

Next