<molin-shop-ai-search>, and you can call it directly when you want to build your own search or category UI.
All three endpoints are public, read-only, and need no API key: the widget ID identifies the catalog, and shoppers call them straight from the browser.
Call
widget.molin.ai, never molin.ai. Keeping every widget request on one origin means you don’t have to add another origin to your Content Security
Policy.GET /v1/search
string
required
Your widget ID, which selects the catalog to search.
string
The search text. Omit it to list the catalog, which is what a category page needs.
JSON array
default:"[]"
Up to 10 product-attribute filters. Each filter has a
key and value, and the whole array is JSON-encoded. Use the stable keys returned by /v1/search/facets: brand, category, color,
size, material, or gender. Existing integrations can continue to send a raw feed attribute key.number
Lowest price to include.
number
Highest price to include.
string
Three-letter currency code for the price filters.
'newest' | 'oldest' | 'cheapest' | 'priciest'
Sort order. Omit it to sort by relevance.
number
default:"20"
Products per page, from 1 through 60.
number
default:"0"
Products to skip, up to 500. The ranker scores
limit + offset candidates, so deep paging is bounded deliberately.Response
array
Matching products in ranked order.
originalPrice is empty when the source didn’t provide a price before the discount. priceAmount and stockQuantity are null when the source data didn’t
provide them.number
For a text query, the number of ranked candidates. For a filter-only listing, the full number of matches before
limit and offset.boolean
true when this page reached the end of the matches, so there is no next page to request.GET /v1/search/facets
Returns the stable filters available for one catalog. Molin groups equivalent source fields such as Color, Colour, and Szín under color without renaming or changing the feed data. Values stay exactly as the feed supplied them.
string
required
Your widget ID.
Response
array
Available
brand, category, color, size, material, and gender filters. Each entry contains the most common values from the catalog. Store-specific fields outside this reviewed list are
not exposed here.GET /v1/search/suggest
Returns the whole suggestion set for a widget in one response. Fetch it once, then filter it in the browser as the shopper types, rather than requesting per keystroke.
string
required
Your widget ID.
Response
string[]
Searches other shoppers on your store ran and got results for. Searches that always came back empty are excluded, so a suggestion never leads to a dead end. A search only appears once at least two
different shoppers ran it.
array
Newest products with their image and prices, as a starting point for a store with no search history yet.
originalPrice is empty when no discount price was supplied.Caching and limits
Search responses are cacheable for 60 seconds and revalidate in the background for a further 5 minutes. Facets and suggestions are cached for 5 minutes and can still be served for a week while they refresh in the background, because they move slowly and slightly stale data is harmless. Search is rate limited per IP. Repeated identical searches are usually served from the edge cache without reaching our worker at all.Errors
All three endpoints answer400 for a missing or unknown widget ID and for any parameter outside the ranges described earlier, with no body. Treat a rejection as a bug in the request rather than something to retry.