Query API
The public, read-only API storefronts, browsers and agents ask: searches, product pages, URLs and robots.txt.
Base URL in the compose stack: http://127.0.0.1:7800. It takes no key and allows every origin. Conventions covers what both APIs share: JSON, ids, times and problems.
| Endpoint | What it does |
|---|---|
GET /health | Whether the Query API is up |
POST /v1/search | Search, browse a category or complete a query |
GET /v1/search | Search with the request in the URL |
GET /v1/product | One product as its page shows it |
GET /v1/resolve | What page one of the merchant's URLs is |
GET /v1/robots | The robots.txt lines that keep crawlers off filter states |
Whether the Query API is up
Search, browse a category or complete a query
POST/v1/search
Answers one request: sections of results or a redirect, named by the release and the catalog snapshot that answered it. The time is set when the request arrives; a request that brings its own time is refused. With debug, the response carries the trace: one entry per step.
Body
One search, category page or autocomplete request.
What the shopper typed. Empty on a category page they only browse.
Where the request comes from. Default: search.
3 values
The search page's results.
A category's listing.
A search box's suggestions while the shopper types.
The channel. Default: the release's first channel.
The locale. Default: the channel's first locale.
The category page being browsed.
The shopper's choices in the page's facets, by field: value or group codes { "color": ["grey", "green"] }, bucket codes { "price": ["100-300"] }, a range { "width": { "gte": 160, "lte": 220 } }, a toggle { "on_sale": true }, and the category facet's choice { "category": { "within": "wohnen/sofas" } }. Values of one field are alternatives; fields narrow each other.
What the shopper took back of what the query named: those words stay text, however often the query is sent again. A value, such as { "field": "color", "value": "black" } or { "field": "category", "value": "wohnen/sofas" }, or every detection of a field, such as { "field": "width" } for a width a pattern read.
A detection the shopper removed.
Lets the response send the shopper elsewhere: to the category page a query names completely, or where a rule redirects. false answers with the results instead, as the way back from such a page does. Default: true.
A sort option. Default: the page's default sort.
The page, counted from 1.
Hits per page, up to the limit per_page. Default: 24, which fills rows of two, three, four and six tiles.
Facets to count in full, besides those the page counts first (the limit counted_facets of its layout, and every one with a choice): a facet the response lists as deferred or with more comes with every value when it is named here, as a shopper opening it needs. Each must be a facet of some page of the release; one the page does not show is left out.
Answers with each section's total alone: no hits, and no facets but those facets names, as a filter sheet's "Show 128 results" needs.
Declared context keys and their values, such as { "customer_group": "b2b" }.
The time the request is answered at. The Query API stamps it on arrival; only search tests and the preview (previewSearch) may fix it, which makes scheduled rules testable.
Adds the trace to the response.
The page the shopper loaded, which the storefront names anew on every page load. The search log counts a query in the reports once two page views typed it on a day.
Whose search this is: tests and benchmarks say so, and the reports leave them out. Default: shopper.
4 values
Everyone a storefront serves that none of the below is.
End-to-end tests, which mark their requests so.
A latency benchmark, which marks its requests so.
A crawler or another bot, as uap-core's maintained user agent rules name it; the Query API decides this from the User-Agent header of a request that says it is a shopper's.
Answers
The answer.
14 fields
Names this answer for clicks and purchases.
The configuration that answered.
The catalog that was searched.
Where to send the shopper when they submit the query: the category or brand page it names completely, or where a rule redirects. A client that does not follow it, such as a search box suggesting as the shopper types, shows the sections, which hold what that page shows; a rule's redirect to a fixed URL has none.
What the query named.
The categories, brands and values a query named, and the text that is left.
5 fields
The id of a category node, such as wohnen/sofas: the merchant's id of a category entity.
Nothing is left as text.
What a relaxed search left out of what the query named, each as the filter it would have been, with its labels, so a storefront can say what the results leave out. Empty unless the response is relaxed.
Nothing matched the resolved search, so it was repeated without what the query named; the resolution says what that was, and filters no longer holds it.
Every filter that narrowed the results the page lists, each removable by the shopper.
The type the page lists: its section pages through the results and carries the facets, and filters narrow it. Products, unless the category page, or the category the query named, holds another type with offers, such as the services of a workshop's category.
The orders the page offers, in display order, one of them marked as the one the page starts in. A storefront draws its sort control from them and puts sort in a URL only where the shopper chose another order than the start. None where the release lays out no options: the page offers no choice.
An order a page offers.
3 fields
What a request's sort names to choose it; relevance is built in.
In the request's locale.
The page starts in this order while the shopper chooses none: the sort its category or the layout's default sets, or relevance where the request has words, which rank by it.
The results, one section per entity type, in order.
The results of one entity type.
6 fields
The code of an entity type, such as product, category or a merchant's own store.
How many entities match in all, counted exactly however many they are.
How many of them pages reach: for the listed section the total, or the limit reachable_hits when more match; for a section beside it, which does not page, the hits it shows. A storefront links and loads no page past them and says why when the total is larger.
The total is an upper bound: a free range over a value that differs between a tile's variants narrows it beside another variant-level choice, and one variant may meet the range while another meets the choice. The trace says which range.
This page's tiles; none when the request asked for the totals alone.
One result tile.
4 fields
An entity named with its type, type:id, such as product:SOFA-LUND-3.
The variant the tile shows, when the listing grain is finer than the product or the shopper's choices on variant-level values pick one, such as the grey variant of a sofa under a grey filter.
The type's result fields, in the request's locale and channel.
A rule's paid pin placed it here: a storefront labels the tile as an ad and names the campaign in the tile's clicks and views.
The campaign a paid placement belongs to: { "campaign": "Michelin spring" }.
1 field
The merchant's name for it, which the campaign report counts by.
The page's facets in display order, each counted under every filter but its own, so choosing a value never makes its siblings vanish. A facet without values to show is left out.
A facet with its values and counts.
19 fields
A field a selector, filter or facet reads: an attribute code, or one of the built-in fields category, brand, price, on_sale, availability, delivery_days and rating.
The group the page draws it in, such as a tyre's width under "Tyre size". The facets of a group follow one another in the group's order, so a storefront without a part for the group draws them one under the other.
The group a facet stands in, as every facet of it says.
3 fields
The code of a group of facets on a page, such as tyre_size.
The heading, in the request's locale.
The values that have results, and every chosen value even without, so it can always be unchosen. A list or swatch carries the most frequent ones up to its cap, and more says how many it leaves out. A range has none; its min and max bound it. A deferred facet has none yet.
9 fields
What a request's filters name to choose it: a value or group code, a number, true, a category id, or a bucket's code written as its bounds, such as 100-300, -4 or 4-.
A bucket's bounds, such as { "gte": 100, "lt": 300 }; selecting the bucket filters the field by them.
In a hierarchical facet, the value one level up.
A swatch image or pattern, or a brand's logo where the facet shows images; its URL.
What the value means, read with it.
How many more values with results the facet has than values holds: the cap left them out, which is the limit facet_values or the layout's limit. Naming the facet in a request's facets returns them all.
The page did not count this facet (the limit counted_facets), so it has no values yet and may have none to show. Naming it in a request's facets counts it.
The counts are upper bounds. That happens only under multi-select across two variant axes inside one tile, and under a free range over a variant-level value that differs inside a tile; the trace says which.
One value at most: a radio group with "Any" first.
Text under the facet's name, read with its group.
A search box belongs above the values.
How a facet's values look beyond what its kind says.
7 values
A range: a two-thumb slider above the two inputs, which stay.
A range over the price: a slider with the distribution of the prices drawn behind it, in the bins of a fixed ladder of preferred numbers (histogram of the response). Prices that fall in a single bin get the plain slider.
A rating: stars beside each bucket; its words carry the meaning.
An option's values on badges in their own swatch colors, such as the energy label's A to G, in the order the values are listed. Every listed value needs a swatch.
One value at most, chosen from one native select with "Any" first, for a long ordered list such as a tyre width.
Each value's image beside its name: a brand's logo, or the image an option's value carries, such as an icon.
The shop's own storefront display, as the release names it; a storefront without it draws display.
A range: the lowest value among the results without the range's own choice, such as the cheapest price.
A range: the highest value among the results without the range's own choice.
A histogram: the bins in ascending order from the one the cheapest tile falls in to the one the dearest does, empty ones included so the bars keep their places, each with the tiles counted in it under every filter but the facet's own. The bins are a fixed ladder of preferred numbers, 24 to the decade and each 8 to 15 percent above the one before, the same under every filter, so a bar says where products sit, not exactly how many: a tile with several prices (one per variant) counts in every bin one of them falls in, and the chosen range may cut a bin in two. The range's min and max still bound the slider. None where the prices fall in a single bin, and while the facet is deferred; naming it in a request's facets counts it, with the same bins.
One bar of a histogram: the tiles with a price from gte up to below lt.
The unit of a quantity's values and bounds, such as cm.
27 values
The unit of a quantity's values and bounds, such as cm.
The unit of a quantity's values and bounds, such as cm.
The unit of a quantity's values and bounds, such as cm.
The unit of a quantity's values and bounds, such as cm.
The unit of a quantity's values and bounds, such as cm.
The unit of a quantity's values and bounds, such as cm.
The unit of a quantity's values and bounds, such as cm.
The unit of a quantity's values and bounds, such as cm.
The unit of a quantity's values and bounds, such as cm.
The unit of a quantity's values and bounds, such as cm.
The unit of a quantity's values and bounds, such as cm.
The unit of a quantity's values and bounds, such as cm.
The unit of a quantity's values and bounds, such as cm.
The unit of a quantity's values and bounds, such as cm.
The unit of a quantity's values and bounds, such as cm.
The unit of a quantity's values and bounds, such as cm.
The unit of a quantity's values and bounds, such as cm.
The unit of a quantity's values and bounds, such as cm.
The unit of a quantity's values and bounds, such as cm.
The unit of a quantity's values and bounds, such as cm.
The unit of a quantity's values and bounds, such as cm.
The unit of a quantity's values and bounds, such as cm.
The unit of a quantity's values and bounds, such as cm.
The unit of a quantity's values and bounds, such as cm.
The unit of a quantity's values and bounds, such as cm.
The unit of a quantity's values and bounds, such as cm.
The unit of a quantity's values and bounds, such as cm.
The currency of a price's values and bounds, the channel's.
The banners and teasers rules place on this page, in the order it draws them: the top ones, those among the tiles by position, the bottom ones. None on the autocomplete surface and for a request for totals alone.
A banner a rule placed on this page, in the request's locale. It is not a hit: the sections' totals, facets and hits are the same without it.
8 fields
Where on a page a banner sits.
3 values
With grid: the tile of the listed section it sits before, counted from 1 across the pages, so on page p it stands before hit position - (p - 1) * per_page. A higher rule's banner at the position asked for moves it to the next free one.
2 values
Where it leads; left out for a banner that only informs, and for one whose page the catalog no longer holds, which the trace names.
A URL a response leads to, written by the merchant's routes where it is an entity's page.
The rule that placed it.
On the autocomplete surface, the queries the shopper may mean, in the order a search box lists them: the text suggestions, then the scoped ones.
A query the shopper may mean while typing. A text suggestion completes what was typed with the catalog's own words, such as "Ecksofa" for "ecks"; a scoped one searches such a completion within a category, "Ecksofa in Sofas".
2 fields
The query it suggests, as the catalog writes it.
Search with the request in the URL
GET/v1/search
The same search with the request's plain fields as URL parameters, so a link or curl is enough: /v1/search?query=sofa&debug=1. Filters and context need the request body of POST /v1/search.
Parameters
What the shopper typed.
Where the request comes from. Default: search.
3 values
The search page's results.
A category's listing.
A search box's suggestions while the shopper types.
A channel's id, such as de or ch: a market or storefront.
A BCP 47 language tag such as de, de-CH or en. A locale falls back along its tag: de-CH to de.
The category page being browsed.
The code of a sort option, such as price_asc. relevance is built in.
The page, counted from 1.
1 or true answers with the totals alone.
0 or false answers with results where the response would send the shopper elsewhere.
1 or true adds the trace to the response.
The page the shopper loaded, as in the request body.
Whose search this is. Default: shopper.
4 values
Everyone a storefront serves that none of the below is.
End-to-end tests, which mark their requests so.
A latency benchmark, which marks its requests so.
A crawler or another bot, as uap-core's maintained user agent rules name it; the Query API decides this from the User-Agent header of a request that says it is a shopper's.
Answers
One product as its page shows it
GET/v1/product
Answers one product by its id or by its URL in the locale: its text, photos and categories, the details the type lists with their labels and units, its variants, and its offer as its tile shows it, all in the request's channel and locale and named by the release and the catalog snapshot that answered. With debug, the response carries the trace.
Parameters
The merchant's id of the product.
The product's URL in the locale as the catalog writes it, such as /p/aska-2-sitzer-sofa, instead of its id.
The channel. Default: the release's first channel.
The locale. Default: the channel's first locale.
1 or true adds the trace to the response.
Answers
The product.
The request names no product, or both an id and a URL, or a channel or locale the release lacks.
What page one of the merchant's URLs is
GET/v1/resolve
Answers what one of the merchant's URLs is, in the order normalize, legacy table, search page, category and brand paths, product URL: a listing with its search and results in one call, a product, a redirect to the final URL, a URL gone on purpose, or not found. The page carries the status, canonical and robots a storefront answers with; the call itself answers 200 for every page. With debug, the response carries the trace: each step of the order and what it found.
Parameters
The URL the shopper or crawler asked for: a path with its query string, such as /wohnen/sofas?farbe=grau, or a whole URL, whose scheme and host are ignored.
The channel. Default: the release's first channel.
The locale. Default: the channel's first locale.
0 or false answers with the decision alone, without the listing's results or the product, as URL tests and agents need. Default: 1.
1 or true adds the trace to the response.
The page the shopper loaded, which the storefront names anew on every page load, as in a search request.
Whose request this is. Default: shopper.
4 values
Everyone a storefront serves that none of the below is.
End-to-end tests, which mark their requests so.
A latency benchmark, which marks its requests so.
A crawler or another bot, as uap-core's maintained user agent rules name it; the Query API decides this from the User-Agent header of a request that says it is a shopper's.
Answers
The page, whatever its own status.
15 fields
The configuration that decided.
The catalog the paths were read from.
The HTTP status the storefront answers with: 200, a redirect's 301, 302, 307 or 308, 404 or 410.
The search page's path in this locale, as routes.json names it, where the page's search box submits to.
Where a redirect leads: always the final URL, never a chain.
The URL a search engine should keep for this page; none where the page is noindex or not found.
What search engines may do with the page; none for a redirect, a page that is gone or not found.
2 values
One of the pages the merchant declared indexable.
A page the merchant did not choose, such as a filter state or the search page; its links are still followed.
The category, brand or product the page is the page of.
The text a search typed that led to this category page, so the page can say what it shows and lead back.
The listing's results, as POST /v1/search answers its request; left out with results=0. With debug, a redirect the listing's search decided keeps them too, so its trace says which rule or resolution sent it on.
The robots.txt lines that keep crawlers off filter states
GET/v1/robots
The Disallow lines the merchant serves in their own robots.txt, written from routes.json: one for every parameter no indexable page uses, one for any URL with a second parameter, and one for the search page.
Answers
Guide: Search and browse · Product pages · URLs and redirects
AppliedFilter
A filter as the storefront shows it: a chip the shopper can remove. Removing it means taking where out of the request's filters, or for a filter the query named, sending its field and value in dismissed, which keeps its words as text.
What the filter keeps, with exactly one field or category, such as { "category": { "within": "wohnen" } }.
The rule that added it, when source is rule.
The field's name in the request's locale, as its facet is labeled, such as "Farbe" or "Kategorie"; none for a rule's filter of several fields.
What the values and categories it names read as in the request's locale, by code or id: an option's or group's label, a brand's or a category's title, such as { "grey": "Grau" } or { "textilien/teppiche": "Teppiche" }. A number, a range and a value nothing labels have none.
Comparison
Compares a field's value. Several operators in one object combine with AND: { "gte": 10, "lt": 20 }.
A single value in a selector, filter or test: text, a number or a boolean. Dates are text, such as 2026-10-01.
A single value in a selector, filter or test: text, a number or a boolean. Dates are text, such as 2026-10-01.
A single value in a selector, filter or test: text, a number or a boolean. Dates are text, such as 2026-10-01.
A single value in a selector, filter or test: text, a number or a boolean. Dates are text, such as 2026-10-01.
From the first value to the second, both included.
True: the field has a value. False: it has none.
Product
A product as its page shows it, in the request's channel and locale.
The merchant's id of an entity, unique per type, such as SOFA-LUND-3. It travels unchanged; OrbSearch never rewrites it.
The merchant's URL of the product in the locale.
The product's URL in each other locale of the channel, for a language switch and hreflang.
The badges the release's overlays give the product, in the locale, such as "Bestseller".
The signals the type returns as result fields, such as its rating and review count: those its tile shows.
Every photo of the product, its own first, then those of its variants.
The categories the product is assigned to, the primary one first.
What a shopper can buy best, as the product's tile shows it when one tile stands for the whole product: the variants with the best availability, and among them the lowest price paid and the soonest delivery.
What holds for the whole product, in the order the type's details list them: its own values and those every variant shares.
The variants sold in the channel, in the catalog's order; none for a product the catalog sends without.
ProductDetail
One detail of a product or variant, as the shopper's locale reads it.
The code of an attribute definition, such as color or seat_height. The reserved words any, all, not, category, brand, price, on_sale, availability, delivery_days and rating cannot be attribute codes.
The attribute's label in the locale.
The unit of a quantity's or a range's numbers, such as cm.
27 values
The unit of a quantity's or a range's numbers, such as cm.
The unit of a quantity's or a range's numbers, such as cm.
The unit of a quantity's or a range's numbers, such as cm.
The unit of a quantity's or a range's numbers, such as cm.
The unit of a quantity's or a range's numbers, such as cm.
The unit of a quantity's or a range's numbers, such as cm.
The unit of a quantity's or a range's numbers, such as cm.
The unit of a quantity's or a range's numbers, such as cm.
The unit of a quantity's or a range's numbers, such as cm.
The unit of a quantity's or a range's numbers, such as cm.
The unit of a quantity's or a range's numbers, such as cm.
The unit of a quantity's or a range's numbers, such as cm.
The unit of a quantity's or a range's numbers, such as cm.
The unit of a quantity's or a range's numbers, such as cm.
The unit of a quantity's or a range's numbers, such as cm.
The unit of a quantity's or a range's numbers, such as cm.
The unit of a quantity's or a range's numbers, such as cm.
The unit of a quantity's or a range's numbers, such as cm.
The unit of a quantity's or a range's numbers, such as cm.
The unit of a quantity's or a range's numbers, such as cm.
The unit of a quantity's or a range's numbers, such as cm.
The unit of a quantity's or a range's numbers, such as cm.
The unit of a quantity's or a range's numbers, such as cm.
The unit of a quantity's or a range's numbers, such as cm.
The unit of a quantity's or a range's numbers, such as cm.
The unit of a quantity's or a range's numbers, such as cm.
The unit of a quantity's or a range's numbers, such as cm.
The swatch color of an option's one value, or of the group it shows under, as its facet draws it; none for a detail of several values.
A swatch image of an option's one value, such as a pattern no single color shows; its URL.
ProductOffer
An offer in the request's channel, with the sale price that holds at the time the live index run was built; the indexer builds again when a sale window opens or closes.
The reduced price, while a sale is on.
An ISO 4217 currency code, such as EUR.
One of in_stock, out_of_stock, preorder or backorder.
How many are in stock, where the catalog says.
ProductVariant
A buyable variation of a product.
The merchant's id of an entity, unique per type, such as SOFA-LUND-3. It travels unchanged; OrbSearch never rewrites it.
The variant's own title, where the catalog gives it one.
The variant's own URL in the locale, where the catalog gives it one.
The variant's own photos.
What sets the variant apart: its values that differ between the product's variants, such as its color and size, in the order of the product's details.
An offer in the request's channel, with the sale price that holds at the time the live index run was built; the indexer builds again when a sale window opens or closes.
Selector
Picks entities (where). Attribute codes and the built-in fields brand, price, on_sale, availability and delivery_days are keys of the same object; category takes is or within.
{ "any": [{ "brand": "bosch" }, { "quality": "oe" }], "not": { "availability": "out_of_stock" } }