POST /products/more-like-this returns products similar to a source product. The API resolves the source by URL or UUID within your catalog grants, builds the similarity query from indexed product enrichment, excludes the source product from results, and returns a standard product list page. The source can also be an image — see Image sources.
Use this endpoint for related product rails, substitutions, recommendation modules, and agent workflows that start from a known product. To see the strategies side by side with live results, open the interactive demo or the strategy recipes guide. For the image input, open the image input demo.
Request
Body parameters
Source image to derive the similarity query from. Provide exactly one of
source.image.b64 or source.image.url. Slower than product sources — see Image sources for behavior, guards, and latency.Base64-encoded image bytes. Decoded size is capped at 8 MB (
413 beyond it). Downscale client-side before sending (~1024px JPEG) — the pipeline downscales internally, so larger uploads only add transfer time.HTTPS image URL fetched server-side — any public host, so retailer product-image URLs can be passed directly. Redirects are not followed, the fetch validates that both DNS resolution and the connected peer are public addresses, and the same 8 MB cap applies while streaming.
Optional catalog allowlist (1–100 keys) restricting results to these catalogs. Retrieval-only: the source product may live outside the allowlist and still resolves. Keys are not validated — an unknown or inaccessible key simply matches nothing. When omitted, search runs across all active crawled catalogs. With
debug: true, the applied allowlist is echoed as effectiveQuery.catalogs. Replaces the former single-valued catalog field, which is now rejected with a 422.Filters a product must match: every facet, and any value within a facet. A facet you send replaces every generated facet of the same name. A
color or color_family facet replaces generated facets on both color axes. Values are never unioned, and the other generated facets stay. Never relaxed. Each name may appear at most once, up to 50 facets. Replaces include_facets, which is now rejected with a 422 naming facets.Filters a product must not match: products with any listed value of any listed facet are removed. Each name may appear at most once, up to 50 facets.
Names of server-generated facets to drop before search and relaxation. Use it for a generated filter you can see is wrong in
effectiveQuery and have no value of your own for. A same-name facets entry replaces it instead. Unknown names are ignored. facets and exclude_facets are never affected.Inclusive minimum price, at least 0. Combined with the
price_preference bound by keeping the higher one. Never relaxed.Inclusive maximum price, at least 0. Combined with the
price_preference bound by keeping the lower one. Never relaxed.Retry a short page 1 with generated facets dropped in stages, least trusted first, and return the first stage that fills it.
- For a
urloruuidsource, page 1 (nocursor) is short when it has fewer thanmin(5, limit)results and nonextCursor. A stage is adopted only if it reaches that floor, or returns anything for an empty page. - For an
imagesource, only an empty page 1 is relaxed.
relax defaults to true. Search defaults to false because its generated facets come from your q.A relaxed page’s cursor continues the same relaxed results. Sending it with relax: false returns 400.Relative price preference compared with the source product’s
currentPrice. Use lower for less expensive alternatives, higher for premium alternatives, or any for no relative price filter. Image sources require any (400 otherwise) — there is no source product to be price-relative to.Embedding columns used to retrieve candidate products. Overrides the server-selected default:
["style_embedding", "tags_embedding"] when the source product has styles or tags, otherwise ["embedding"]. Accepted values: embedding, style_embedding, tags_embedding, attributes_embedding. Must contain at least one value.Embedding columns used to re-score and rank the retrieved candidates. When omitted, ranking uses the base
embedding. Accepts the same values as retrieval_embedding_columns; must contain at least one value. Combine the two to retrieve one way and rank another — see Strategy recipes.Opaque pagination cursor from a previous response’s
nextCursor field. Pass it unmodified with the same request fields to retrieve the next page. Supported for image sources: the cursor embeds the relaxation round that produced the page, so continuations re-run the exact converged query. Deterministic within the 24h generation-cache window.When
true, the response includes a curated camelCase effectiveQuery object showing the server-derived retrieval query.Example
Embedding columns
Every indexed product carries several embeddings. Retrieval columns decide which products come back as candidates; ranking columns decide how those candidates are ordered.Strategy recipes
Send
debug: true with any combination and the response’s effectiveQuery shows the exact query the server executed. For worked examples of each strategy with live results, see the strategy recipes guide.
Image sources
Send a photo — a product shot, a look to match — and the API generates the similarity query from the image: a multimodal parse reads it, the query processors derive facets (category, gender, color, attributes), and the search runs with zero-result facet relaxation. See it live in the image input demo.- Latency: the first sight of an image runs generation — expect p50 ≤ 8s, ~11s when relaxation rounds run. Repeat images are served from a generation cache (24h) in ~0.25s, and the response’s
resolutionfield says which happened:image_query_generation(pipeline ran) orcached_image_query(cached). - Facet relaxation: every image-derived facet is an inference, including a
brand_nameread off a visible logo. Withrelax: true(the default), a zero-result search retries with the least-trusted facet tiers dropped. Withdebug: truethe response reports it ineffectiveQuery.relaxation. Facets you pass infacetsare never dropped. - Response shape: image responses return
sourceImage.hashandresolutioninstead of the resolved-productsourcestanza.nextCursoris a normal opaque cursor — pass it back with the same request body to page through the result set. facets/exclude_facets/ bounds / embedding-column overrides work exactly as for product sources.
Response
Public identity of the source product that powered the similarity query. Present for
url/uuid sources; image sources return sourceImage instead.Present for image sources only:
{ "hash": string } — the content hash of the submitted image bytes.Present for image sources only. How the source was resolved:
"image_query_generation" (the generation pipeline ran) or "cached_image_query" (served from the 24h generation cache — a repeat of an image seen before).Similar products for the current page. See the Product model for the full field reference.
Cursor for the next page of similar products.
null means no more results are available.Present only when
debug is true. Contains the public server-derived query fields:text,retrievalEmbeddingColumns,rankingEmbeddingColumns,facets,exclusionFacets,limit;priceMin,priceMax,brandQualityMin,brandQualityMax;catalogs, the normalized allowlist as applied, when you sent one;relaxation, withrelax: true, in the same shape search uses:rounds(stages applied,0if none),declinedRounds(stages tried that did not fill the page) anddroppedFacets(the generated facets dropped).
generationStages (per-stage generation timings) and degradedToTextFallback. relaxation replaces the former relaxationRounds, relaxationDroppedFacets, and relaxationDeclinedRounds fields.