Management API
The control plane's API for catalogs, imports, releases, rules, synonyms and index runs, called with the management key.
Base URL in the compose stack: http://127.0.0.1:8000. Every call sends the management key as Authorization: Bearer <key> (Authentication). Conventions covers what both APIs share.
| Endpoint | What it does |
|---|---|
PUT /api/v1/catalog | Replace the catalog |
GET /api/v1/catalog-source | Show the feed the catalog is fetched from, with its latest fetches |
PUT /api/v1/catalog-source | Fetch the catalog from a feed URL on a schedule |
DELETE /api/v1/catalog-source | Stop fetching the catalog from its feed URL |
POST /api/v1/catalog-source/fetch | Fetch the catalog source now |
GET /api/v1/imports | List the imports, newest first |
POST /api/v1/imports | Start an import: keep an export without making it live |
GET /api/v1/imports/{import} | Show an import with its files and its run |
PATCH /api/v1/imports/{import} | Change the release files an import is read with |
DELETE /api/v1/imports/{import} | Discard an import that has not gone live |
GET /api/v1/imports/{import}/inspection | Show what the import makes of its export |
GET /api/v1/imports/{import}/suggestions | Show where a decision model would send the export's columns |
GET /api/v1/imports/{import}/changes | Show what making an import live changes |
POST /api/v1/imports/{import}/publish | Make an import live, or go back to an earlier one |
GET /api/v1/imports/{import}/publication | Show how publishing the import would go live, before it does |
GET /api/v1/rules | List the live rules in order, each with its state and its conflicts |
GET /api/v1/imports/{import}/rules | List a draft's rules in order, each with its state and its conflicts |
POST /api/v1/imports/{import}/rules | Add a rule to a draft |
PATCH /api/v1/imports/{import}/rules/{rule} | Change one rule of a draft |
DELETE /api/v1/imports/{import}/rules/{rule} | Remove one rule from a draft |
PUT /api/v1/imports/{import}/rules/{rule}/position | Move one rule of a draft to another place in the order |
GET /api/v1/synonyms | List the live synonyms of every language |
GET /api/v1/imports/{import}/synonyms | List a draft's synonyms of every language |
POST /api/v1/imports/{import}/synonyms | Add synonym entries to a draft, one or many at once |
PATCH /api/v1/imports/{import}/synonyms/{synonym} | Change one synonym entry of a draft |
DELETE /api/v1/imports/{import}/synonyms/{synonym} | Remove one synonym entry from a draft |
POST /api/v1/imports/{import}/synonyms/check | Say what an entry's words find today and what adding it to a draft would clash with |
GET /api/v1/search-settings | Show how each type is searched now: its fields, typo settings and exempt attributes |
GET /api/v1/imports/{import}/search-settings | Show how each type of a draft is searched |
PATCH /api/v1/imports/{import}/search-settings/{type} | Change how one type of a draft is searched |
GET /api/v1/releases | List the releases, newest first |
POST /api/v1/releases | Store a release |
GET /api/v1/releases/{release} | Show a release with its files |
POST /api/v1/releases/{release}/publish | Publish a release, or roll back to an earlier one |
GET /api/v1/releases/{release}/publication | Show how publishing the release would go live, before it does |
GET /api/v1/index-runs | List the index runs, newest first |
POST /api/v1/index-runs | Index the current catalog with the published release again |
GET /api/v1/index-runs/{index_run} | Show an index run with its report |
GET /api/v1/live | Show what searches read now |
PUT /api/v1/offers | Change prices and stock without sending the catalog |
GET /api/v1/storage | Show what the storage keeps and the disk it takes |
PATCH /api/v1/storage | Change how many earlier catalogs are kept |
GET /api/v1/insights | Show what shoppers searched and clicked, what found nothing and the filters they chose |
GET /api/v1/insights/campaigns | Show the views and clicks of each sponsored products' campaign |
GET /api/v1/categories | Show the category tree of what is live |
POST /api/v1/pages/settings | Show what a page shows and where each setting comes from |
POST /api/v1/preview/search | Search as a shopper would, in any context and at any time, with the trace |
POST /api/v1/preview/page | Open one of the shop's URLs as a shopper would, in any context and at any time |
POST /api/v1/preview/compare | Say why one hit of a preview sits above another |
POST /api/v1/preview/find | Say why a product is not on a preview's page, or where it is |
Replace the catalog
PUT/api/v1/catalog
The body is the whole catalog as the shop exported it, in any of the media types listed. It is kept byte for byte as a snapshot named by its content; the published release's feed.json says how its columns map, and a later release reads the same snapshot again. With a release published, an index run makes it searchable, and next says what happens.
Body
fileRequired
Sent as application/x-ndjson, text/csv, text/tab-separated-values, application/xml, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/json, application/gzip, application/octet-stream.
Answers
Show the feed the catalog is fetched from, with its latest fetches
GET/api/v1/catalog-source
The feed URL, how it signs in without its secret, its schedule, when it is fetched next, and its last ten fetches, newest first, each with how it ended and why. needs_attention is set while the latest changed feed is held back or the last three fetches failed.
Answers
The catalog source.
8 fields
How the fetch signs in, without its secret; left out when it does not.
How a catalog source signs in, as it is shown: its secret never is.
How often the feed is fetched.
When the schedule fetches next: at once after a fetch was asked for, otherwise one interval after the last one started.
When a fetch was asked for that has not started yet.
The latest changed feed is held back, or the last three fetches failed; Overview lists the source then. Left out otherwise.
The last ten fetches, newest first.
Fetch the catalog from a feed URL on a schedule
PUT/api/v1/catalog-source
The control plane fetches the feed every interval_minutes, asking whether it changed since the last fetch. A feed that changed becomes an import and goes live as publishing it would, or waits as a draft when on_change is draft; one that would remove half the live products or more is held back as a draft to confirm. The same bytes again queue nothing. A new URL or new credentials are fetched at once. The credentials are kept encrypted and never answered; left out, the kept ones stay, and null removes them. A URL in a private, loopback or link-local network is refused at fetch time unless the stack allows it.
Body
The feed to fetch the catalog from, and how.
An http or https URL, without a user or password in it.
How often to fetch it. Default: 60.
How to sign in, kept encrypted and sent only to the feed's own host. Left out, the kept credentials stay; null removes them.
Answers
The catalog source is changed.
8 fields
How the fetch signs in, without its secret; left out when it does not.
How a catalog source signs in, as it is shown: its secret never is.
How often the feed is fetched.
When the schedule fetches next: at once after a fetch was asked for, otherwise one interval after the last one started.
When a fetch was asked for that has not started yet.
The latest changed feed is held back, or the last three fetches failed; Overview lists the source then. Left out otherwise.
The last ten fetches, newest first.
The catalog source is set.
8 fields
How the fetch signs in, without its secret; left out when it does not.
How a catalog source signs in, as it is shown: its secret never is.
How often the feed is fetched.
When the schedule fetches next: at once after a fetch was asked for, otherwise one interval after the last one started.
When a fetch was asked for that has not started yet.
The latest changed feed is held back, or the last three fetches failed; Overview lists the source then. Left out otherwise.
The last ten fetches, newest first.
Stop fetching the catalog from its feed URL
DELETE/api/v1/catalog-source
The source and its fetches go; the imports its fetches made stay in the history.
Answers
The source is removed, as it was.
8 fields
How the fetch signs in, without its secret; left out when it does not.
How a catalog source signs in, as it is shown: its secret never is.
How often the feed is fetched.
When the schedule fetches next: at once after a fetch was asked for, otherwise one interval after the last one started.
When a fetch was asked for that has not started yet.
The latest changed feed is held back, or the last three fetches failed; Overview lists the source then. Left out otherwise.
The last ten fetches, newest first.
Fetch the catalog source now
POST/api/v1/catalog-source/fetch
The schedule starts the fetch within seconds; showCatalogSource lists it once it has started, and how it ended once it has.
Answers
The fetch is asked for.
8 fields
How the fetch signs in, without its secret; left out when it does not.
How a catalog source signs in, as it is shown: its secret never is.
How often the feed is fetched.
When the schedule fetches next: at once after a fetch was asked for, otherwise one interval after the last one started.
When a fetch was asked for that has not started yet.
The latest changed feed is held back, or the last three fetches failed; Overview lists the source then. Left out otherwise.
The last ten fetches, newest first.
List the imports, newest first
GET/api/v1/imports
A page of imports; links and meta lead to the others. Every import keeps the release it went live with, so any one of them can go live again while its export is kept.
Parameters
The page, counted from 1. Default: 1.
How many to a page. Default: 15.
Answers
Start an import: keep an export without making it live
POST/api/v1/imports
The body is the export as the shop wrote it, in any of the media types listed, kept byte for byte as a snapshot. Nothing goes live: inspect it, correct the files it is read with, then publish it. PUT /api/v1/catalog is the one-step path for automation that needs no look first.
Parameters
The file's name, such as export.csv, so the panel and the history can tell imports apart.
Body
fileRequired
Sent as application/x-ndjson, text/csv, text/tab-separated-values, application/xml, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/json, application/gzip, application/octet-stream.
Answers
The export is kept as a draft import.
2 fields
An export on its way to live: the file as the shop wrote it, the release files it is read with, and once published, the release and the index run that make it live. Imports are never deleted, so every export that went live can go live again while its file is kept.
What to do next, as a sentence.
Show an import with its files and its run
Change the release files an import is read with
PATCH/api/v1/imports/{import}
Each named file replaces the import's own version of it, as its JSON object or as text; null drops it, so the published release's file applies again. The Query API checks the release they make together. Only an import that has not been published can change. version is the import's version you read: a draft changed since, by a person or an agent, refuses the write with 409 and the draft as it is now, so nobody overwrites another silently.
Parameters
Body
Release files to read an import with, such as { "files": { "feed.json": { "columns": { "Preis": "price" } } } }. A file given as null is dropped, so the base release's applies again.
The import's version as read; a draft that changed since refuses the write.
Answers
The draft changed since version was read, and draft is the draft as it is now; or it was published or discarded, and draft is left out.
Discard an import that has not gone live
DELETE/api/v1/imports/{import}
The import leaves the list of drafts and stays in the history; the indexer's clean-up removes its export.
Parameters
Answers
Show what the import makes of its export
GET/api/v1/imports/{import}/inspection
What the import makes of the export with its files: the format, every column with samples, where it goes and why, the products it becomes, the first of them as they would be indexed, and the rows that would be left out, grouped by cause. With sample, the products and problems cover the first rows only, which answers a large export faster.
Parameters
Map only the first rows, which answers faster for a large export; the columns and the mapping still describe the whole file. Default: every row.
Answers
The inspection.
16 fields
How the file was read and who placed its columns, with the columns whose values go nowhere.
Rows in the file, the header and blank rows not counted.
When the products, rejections and values cover the first rows only: how many it mapped. Left out when they cover the whole file. The columns and the mapping always describe the whole file.
Every column of the file, in the file's order; empty for OrbSearch's own JSON Lines.
One column of an export: what it holds and where its values go.
6 fields
The column's name as the header writes it.
Rows with a value in it.
Its first different values as written, up to five.
Where its values go; left out when they go nowhere.
Why a column goes where it goes.
14 fields
feed.json names it, by its name or by a pattern such as Attribut_*.
1 field
feed.json does not name it, so its values are left out.
Its name is one Merchant Center or a common shop export gives the field, such as artikelnummer for id.
1 field
Its name is the code, a label or a source name of an attribute in attributes.json.
1 field
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.
A German shop's price pair: struck through beside the shop's price, this column is the regular price.
1 field
A German shop's price pair: beside a struck-through price, the column a shop calls its price is the reduced one.
1 field
It holds attribute values whose names stand in a sibling column, as WooCommerce and Shopify write them.
1 field
It holds the attribute names for the values of another column.
1 field
Its attribute names should stand in a column the file does not have, so its values are left out.
1 field
Its cells hold several attributes as name and value pairs, such as "Farbe: Rot | Breite: 218 cm".
No alias knows it, so it is an attribute under a code made from its name.
Shipping, tax or ads data, or another column search does not use, such as product_detail's section names.
No row fills it.
Where feed.json placed the column: where the import itself would send it, and why. Beside a merchant's change, it says what going back to the proposal means.
The import's own proposal for a column: where it would go without feed.json, and why.
2 fields
Left out when the import would leave its values out.
Why a column goes where it goes.
14 fields
feed.json names it, by its name or by a pattern such as Attribut_*.
1 field
feed.json does not name it, so its values are left out.
Its name is one Merchant Center or a common shop export gives the field, such as artikelnummer for id.
1 field
Its name is the code, a label or a source name of an attribute in attributes.json.
1 field
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.
A German shop's price pair: struck through beside the shop's price, this column is the regular price.
1 field
A German shop's price pair: beside a struck-through price, the column a shop calls its price is the reduced one.
1 field
It holds attribute values whose names stand in a sibling column, as WooCommerce and Shopify write them.
1 field
It holds the attribute names for the values of another column.
1 field
Its attribute names should stand in a column the file does not have, so its values are left out.
1 field
Its cells hold several attributes as name and value pairs, such as "Farbe: Rot | Breite: 218 cm".
No alias knows it, so it is an attribute under a code made from its name.
Shipping, tax or ads data, or another column search does not use, such as product_detail's section names.
No row fills it.
The mapping as feed.json holds it: the release's own, or the derived one, ready to be saved and corrected.
The release files the release leaves out, derived from the export, each setting with its reason. Attribute definitions, types and channels describe the whole file, except an attribute a correction changed after the export's first look, which the rows mapped describe; facets, sorting and ranking describe the rows mapped.
Products the rows become.
Their variants; a product without variants counts none.
Categories made from the category paths.
The first products as they would be indexed, their values read as their definitions say.
The same products as a search answers them in the first channel and its first locale: the hits a storefront draws as tiles. Empty while the release has no channel.
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.
Every product detail shoppers could meet: the attributes the products carry and the fields every shop filters by, each a filter, found by search or not used, as the release completed with the derived files makes it. The filters come first, in the order pages show them; their values cover the sample, as the products do.
A product detail as shoppers meet it: what it is for, what else it could be, and why the import chose as it did.
13 fields
An attribute's code, or one of the fields every shop has: category, brand, price, availability, delivery_days, on_sale and rating.
Its name in the shop's first language, as shoppers read it: an attribute's label, a field every shop has by the built-in words such as "Preis". The panel names the fields every shop has in the merchant's own language.
The column it comes from, as the header writes it.
Products that carry it, on themselves or on a variant.
An attribute's values, read as its definition says.
4 fields
Values a shopper ticks, the most common first, each with how many products carry it. An attribute with color groups shows its groups with their swatches; values no group took follow in ungrouped.
2 fields
Numbers, quantities or ranges a shopper narrows: the lowest and highest, in the attribute's unit.
3 fields
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
27 values
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
The facet categories.json lists for it as a filter, in the shape the import gives it, such as the price's buckets or the color groups as swatches. Left out when it can be no filter.
Why the import would not make it a filter of search pages by itself, though it can be one.
Why the import would not make a detail a filter of search pages by itself. A merchant may still choose it; the reason says what shoppers who use it meet.
6 fields
One value only, so there is nothing to choose.
A number without a unit that is no short list of whole values, such as a sales count or a score.
A number that differs between variants, which only buckets count exactly.
The decision model judged it no filter, though the import's own test would make it one.
A filter only of this many category pages, where most products carry it, and not of search pages.
How shoppers read the filter's ranges in the shop's first language, in the facet's order, such as "bis 10 €"; empty where the filter lists values.
What the release, completed with what this export derives, does not hold, such as a filter categories.json names over a column this export no longer has. The index run would fail with the same sentences.
One thing that is wrong with the input, and where.
Rows that would be left out.
Those rows grouped by what is wrong, the most common first.
What the import would make of the attribute values.
Show where a decision model would send the export's columns
GET/api/v1/imports/{import}/suggestions
For each column that holds values, the field, attribute or signal a decision model behind the AI gateway chose for it, with its probability. The model is asked once per import and the answer is kept, so asking again costs nothing. A suggestion changes nothing until it is chosen: send the column's new place in feed.json with changeImport. Off while the Query API has no AI gateway key.
Parameters
Answers
The suggestions.
3 fields
The model that answered, as the AI gateway names it, such as typesafe-ai/jev.
One per column that holds values, in the file's order.
Where the model would send one column, and how probable it finds that.
4 fields
The column's name as the header writes it.
The model's choice among the fields, the release's attributes and signals, an attribute of the column's own, and ignore.
The model's probability for its choice.
Taken into the mapping without asking: the model is nearly certain, and the import could only guess the column, placed it by a shared prefix or left it out, or only a column's name chose the field. A column whose field another column took is taken to the model's choice for it, so no field is filled twice.
Show what making an import live changes
GET/api/v1/imports/{import}/changes
The import's export and files against what searches read now: the products added and removed, as each export names them, and the attributes and filters new and gone. Both exports are read whole, so a large one takes a few seconds per gigabyte. When the draft removes half the live products or more, products.needs_confirmation is set and publishing it needs removing.
Parameters
Answers
The changes.
3 fields
Products as the exports name them: an export's product is its group, or the row's id where it has none. A row left out by a problem still names its product, so the problems are counted apart.
7 fields
Products the import's export names.
Products the live export names; 0 when nothing is live.
In the draft, not live.
Live, not in the draft.
The first ids added, up to LISTED_CHANGES.
The first ids removed, up to LISTED_CHANGES.
The draft removes so large a share of the live products that publishing it needs the number confirmed: a broken export must not empty a shop.
Make an import live, or go back to an earlier one
POST/api/v1/imports/{import}/publish
Stores the release its files make, publishes it and queues an index run with its export; run says how it goes. Publishing an import that was live before is how a merchant goes back to it. An import that would remove half the live products or more is published only with removing set to the number showImportChanges names, because a broken export must not empty a shop.
Parameters
How many live products the export leaves out, as showImportChanges counts them: the confirmation that an import removing half the live products or more is meant to.
The draft's version as reviewed, so what goes live is what was looked at: a draft that changed since is refused. Default: the draft as it is.
Answers
The import is published.
2 fields
An export on its way to live: the file as the shop wrote it, the release files it is read with, and once published, the release and the index run that make it live. Imports are never deleted, so every export that went live can go live again while its file is kept.
What happens next, as a sentence.
The draft changed since version was read, or while its release was built, and draft is the draft as it is now; or the import was discarded, is going live already, its export was removed, or it removes half the live products or more and removing does not name how many, and draft is left out.
Show how publishing the import would go live, before it does
GET/api/v1/imports/{import}/publication
What publishing the import would do, decided by the decision the indexer takes: course says whether it goes live at once (a switch), after settings the engine applies without reindexing, or by a rebuild of the indexes, and why, as data and as a sentence. For a rebuild, estimate_seconds is about how long it takes, from the last rebuild; the shop keeps answering with the live release meanwhile. Nothing is published.
Parameters
Answers
How publishing would go live.
2 fields
For a rebuild: about how many seconds it takes, from the time of the last rebuild. It grows with the catalog, so a much larger catalog takes longer. Left out for any other way, and before a first rebuild.
The draft files make a release with violations; each names its file, a JSON pointer and what is wrong.
List the live rules in order, each with its state and its conflicts
GET/api/v1/rules
Every rule of the release searches read, in rule order. Each has what it does in one line, its state at time (active, scheduled, expired, disabled, or dormant because everything it acts on left the catalog), the conflicts with the rules above it, the entities it names that the catalog no longer holds, and the fields an editor sets. A rule the fields cannot express yet comes with its JSON, read only. States and conflicts are data with parameters, and a sentence that says the same, written once by the Query API.
Parameters
The channel the catalog is read in. Default: the release's first channel.
The locale the products are named in. Default: the channel's first locale.
The time the states are as at, so a scheduled rule can be seen on the day it starts. Default: now.
Answers
List a draft's rules in order, each with its state and its conflicts
GET/api/v1/imports/{import}/rules
The same answer for the rules a draft makes, with the draft's version to write on. A draft that changes no rules lists the live ones.
Parameters
The channel the catalog is read in. Default: the release's first channel.
The locale the products are named in. Default: the channel's first locale.
The time the states are as at, so a scheduled rule can be seen on the day it starts. Default: now.
Answers
The draft's rules.
The draft files make a release with violations; each names its file, a JSON pointer and what is wrong.
Add a rule to a draft
POST/api/v1/imports/{import}/rules
Adds one rule through its fields; the first place in the order unless position says another. The Query API makes the rule, writes rules.json and checks the release as for changeImport, so violations come back with their JSON pointers. The answer is the draft's rules after the write.
Parameters
Body
A rule to add and the draft version it is written on.
The version of a draft: it changes with every change of the draft's release files, and with the release the draft builds on. A write names the version it read, and is refused when the draft has moved on. Treat it as opaque.
The rule's id. Default: made from the name, and made unique.
The rule's name, one line up to 200 characters. Default: what the rule does, in a sentence.
Default: on.
Its place in the order, counted from 1; a number past the end puts it last. Default: first, since a merchant's new rule outranks the older ones.
The fields of a rule an editor sets.
Answers
The rule is added.
The draft changed since version was read, and draft is the draft as it is now; or it was published or discarded, and draft is left out.
The write has violations, or the release it makes does; each names a JSON pointer and what is wrong. A change of fields to a rule they cannot express is refused here.
Change one rule of a draft
PATCH/api/v1/imports/{import}/rules/{rule}
Changes the name, whether it is on, or its fields, all of them at once. A rule the fields cannot express yet keeps its name and switch changeable, and its fields are changed through the draft's files with changeImport. A rule id may hold slashes, which are sent as they are: /api/v1/imports/3/rules/home/out-of-stock-last.
Parameters
Body
A change of one rule and the draft version it is written on.
The version of a draft: it changes with every change of the draft's release files, and with the release the draft builds on. A write names the version it read, and is refused when the draft has moved on. Treat it as opaque.
The new fields, all of them: the rule's condition, effects and window are replaced. Refused for a rule the fields cannot express, since the change would drop what they leave out.
Answers
The draft's rules after the write.
The draft changed since version was read, and draft is the draft as it is now; or it was published or discarded, and draft is left out.
The write has violations, or the release it makes does; each names a JSON pointer and what is wrong. A change of fields to a rule they cannot express is refused here.
Remove one rule from a draft
DELETE/api/v1/imports/{import}/rules/{rule}
Removes the rule from the draft. Publishing the draft removes it from searches; an earlier release still holds it.
Parameters
Answers
The draft's rules after the write.
The draft changed since version was read, and draft is the draft as it is now; or it was published or discarded, and draft is left out.
The write has violations, or the release it makes does; each names a JSON pointer and what is wrong. A change of fields to a rule they cannot express is refused here.
Move one rule of a draft to another place in the order
PUT/api/v1/imports/{import}/rules/{rule}/position
Puts the rule at position in the order; the rules between shift by one. Where two effects exclude each other, the higher rule wins, so the order is precedence.
Parameters
Body
A move of one rule and the draft version it is written on.
The version of a draft: it changes with every change of the draft's release files, and with the release the draft builds on. A write names the version it read, and is refused when the draft has moved on. Treat it as opaque.
Its new place, counted from 1; a number past the end puts it last.
Answers
The draft's rules after the write.
The draft changed since version was read, and draft is the draft as it is now; or it was published or discarded, and draft is left out.
The write has violations, or the release it makes does; each names a JSON pointer and what is wrong. A change of fields to a rule they cannot express is refused here.
List the live synonyms of every language
GET/api/v1/synonyms
Every synonym entry of the release searches read, by language: groups of words that mean the same, one-way entries, and words never merged. Each has its id, its words as the engine reads them, what it does in one line, and what it clashes with, as data and a sentence written once by the Query API. locales lists the languages the channels serve, the shop's first.
Answers
List a draft's synonyms of every language
GET/api/v1/imports/{import}/synonyms
The same answer for the synonyms a draft holds, with the draft's version to write on. A draft that changes no synonyms lists the live ones.
Parameters
Answers
Add synonym entries to a draft, one or many at once
POST/api/v1/imports/{import}/synonyms
Adds entries to one language, such as { "kind": "group", "words": ["couch", "sofa"] }, one or up to synonyms_per_call at once, as pasting lines does. Words are trimmed, lowercased and kept once. An entry that would put a word in a second group, start a second one-way entry from the same word, or merge words a never entry keeps apart is refused, naming the entry it clashes with so the word can be added there; despite_never writes the last kind anyway. The others are written, and the answer lists both. Synonyms go live as settings, without a rebuild.
Parameters
Body
Synonym entries to add to one language of a draft, and the version they are written on.
The version of a draft: it changes with every change of the draft's release files, and with the release the draft builds on. A write names the version it read, and is refused when the draft has moved on. Treat it as opaque.
The language, such as de: the first of the list's locales is the shop's.
Writes an entry that merges words a never entry keeps apart, which is refused otherwise.
Answers
Entries are added; refused lists those that clash.
4 fields
The draft's version this answer is of; the next write names it.
Every language's synonyms.
After a write: the entries added or changed, in the order sent.
After an add: the entries that clash and were not written, each with why.
The draft changed since version was read, and draft is the draft as it is now; or it was published or discarded, and draft is left out.
Nothing is written: every entry clashes, and refused says why for each; or the release the write makes has violations, each with a JSON pointer.
Change one synonym entry of a draft
PATCH/api/v1/imports/{import}/synonyms/{synonym}
Replaces the entry's words, checked as an add checks them. An entry id holds slashes, which are sent as they are: /api/v1/imports/3/synonyms/de/groups/0. An entry that changes its kind moves after the entries of its new kind, and the answer names its new id.
Parameters
Body
An entry's new words and the draft version they are written on.
The version of a draft: it changes with every change of the draft's release files, and with the release the draft builds on. A write names the version it read, and is refused when the draft has moved on. Treat it as opaque.
Writes an entry that merges words a never entry keeps apart, which is refused otherwise.
Answers
The draft's synonyms after the write.
4 fields
The draft's version this answer is of; the next write names it.
Every language's synonyms.
After a write: the entries added or changed, in the order sent.
After an add: the entries that clash and were not written, each with why.
The draft changed since version was read, and draft is the draft as it is now; or it was published or discarded, and draft is left out.
Nothing is written: every entry clashes, and refused says why for each; or the release the write makes has violations, each with a JSON pointer.
Remove one synonym entry from a draft
DELETE/api/v1/imports/{import}/synonyms/{synonym}
Removes the entry from the draft; the entries after it of its kind move up one place, so their ids change and the next write reads the list again.
Parameters
Answers
The draft's synonyms after the write.
4 fields
The draft's version this answer is of; the next write names it.
Every language's synonyms.
After a write: the entries added or changed, in the order sent.
After an add: the entries that clash and were not written, each with why.
The draft changed since version was read, and draft is the draft as it is now; or it was published or discarded, and draft is left out.
Nothing is written: every entry clashes, and refused says why for each; or the release the write makes has violations, each with a JSON pointer.
Say what an entry's words find today and what adding it to a draft would clash with
POST/api/v1/imports/{import}/synonyms/check
For an entry being typed: how many results the search page lists for each word now, searched with the live release in one engine call, and what adding it to the draft would clash with, such as the group a word is in already. Nothing is written, and the draft is not indexed, so the counts are those of the live synonyms.
Parameters
Body
An entry being typed, to check before it is written.
A BCP 47 language tag such as de, de-CH or en. A locale falls back along its tag: de-CH to de.
The channel the words are searched in. Default: the first channel that serves a locale reading this language's synonyms, such as de-CH for de.
The entry being changed, whose own words clash with nothing.
Answers
The words' counts and the clashes.
5 fields
A channel's id, such as de or ch: a market or storefront.
The locale the words were searched in.
Why writing it would be refused, as an add says; none when it can be written.
A clash as data and as one sentence, such as "“sofa” is in the group couch, sofa, settee already."
3 fields
It names fewer than two different words; a one-way entry names a word and at least one other it finds.
The word is in another group already, or starts another one-way entry: entry is the one to add to instead, with its words.
It merges two words the never entry entry keeps apart; for a never entry, entry is the one that merges them.
The draft's synonyms.json cannot be read, or the entry has more than words_per_check words.
Show how each type is searched now: its fields, typo settings and exempt attributes
GET/api/v1/search-settings
How each type searches read is searched: its fields in priority order, where a word found in an earlier field ranks a hit higher, the fields it could search besides, whether and from how many letters on its words find with a typo, and the attributes exempt from typos, whose words are found only as written or by their start. Each setting says whether types.json sets it, the index run derived it from the catalog, or it is OrbSearch's default. Exempt attributes are derived from the catalog: the identifiers a type searches whose values nearly always belong to one product alone; open lists the identifiers left open to typos, each with why.
Parameters
Default: the first channel's first locale.
Answers
Show how each type of a draft is searched
GET/api/v1/imports/{import}/search-settings
The same answer for the release a draft makes, with the draft's version to write on, its derived settings as the draft's run would derive them from the live catalog.
Parameters
Answers
The draft's search settings.
2 fields
The draft's version this answer is of; the next write names it.
How every type of the release is searched.
Change how one type of a draft is searched
PATCH/api/v1/imports/{import}/search-settings/{type}
Changes the type's searched fields, its typo settings or its exempt attributes, each named setting replaced whole; a setting left out stays, and null sets it back to its default, the import's or OrbSearch's. The Query API writes types.json and the draft checks the release as for changeImport. A draft without its own types.json starts from the types the live run derived. How it goes live, showImportPublication says: the order of the fields and the typo settings as settings within moments, the fields searched and the exempt attributes by a rebuild, since the engine reads every document again for them.
Parameters
Body
A change of how one type is searched and the draft version it is written on.
The version of a draft: it changes with every change of the draft's release files, and with the release the draft builds on. A write names the version it read, and is refused when the draft has moved on. Treat it as opaque.
The searched fields in priority order, all of them, at least one.
Whether and from how many letters on words find with a typo.
3 fields
Off, a word finds only what holds it as written or starts with it. Default: on.
The fewest letters a word needs to find with one typo. Default: 5.
The fewest letters a word needs to find with two typos; at least one_typo. Default: 9.
The attributes exempt from typos, all of them; [] exempts none.
Answers
The draft's search settings after the write.
2 fields
The draft's version this answer is of; the next write names it.
How every type of the release is searched.
The draft changed since version was read, and draft is the draft as it is now; or it was published or discarded, and draft is left out.
The write has violations, or the release it makes does; each names a JSON pointer and what is wrong. A change of fields to a rule they cannot express is refused here.
List the releases, newest first
GET/api/v1/releases
A page of releases, newest first, each marked as the live one, the previous one a rollback goes back to, or the one going live; links and meta lead to the others.
Parameters
The page, counted from 1. Default: 1.
How many to a page. Default: 15.
Answers
Store a release
POST/api/v1/releases
Each file as its JSON object, or as text. The Query API checks the release and writes its files canonically; the same content is the same release. Storing does not publish.
Body
A release to store: its files by name, each as its JSON object or as text, such as { "files": { "channels.json": { "channels": [...] } } }.
Answers
The same release was stored before.
The release is stored.
Show a release with its files
GET/api/v1/releases/{release}
Its files are the canonical text the Query API wrote, so the panel and Git hold the same bytes.
Parameters
Answers
Publish a release, or roll back to an earlier one
POST/api/v1/releases/{release}/publish
An index run takes it live with the current catalog, the one uploaded last that the indexer did not reject, the way showReleasePublication says: switched in at once, after settings, or by a rebuild. Searches read it once the run goes live, and the run's report says how it went. Publishing an earlier release again is a rollback.
Parameters
Answers
The release is published.
3 fields
A release as the control plane stores it, with when it was published. Storing does not publish it.
What happens next, as a sentence.
Show how publishing the release would go live, before it does
GET/api/v1/releases/{release}/publication
What publishing the release would do with the catalog an index run would use now, decided by the decision the indexer takes: course says whether it goes live at once (a switch), after settings the engine applies without reindexing, or by a rebuild of the indexes, and why, as data and as a sentence. For a rebuild, estimate_seconds is about how long it takes, from the last rebuild; the shop keeps answering with the live release meanwhile. Publishing an earlier release again, a rollback, is decided the same way. Nothing is published.
Parameters
Answers
How publishing would go live.
2 fields
For a rebuild: about how many seconds it takes, from the time of the last rebuild. It grows with the catalog, so a much larger catalog takes longer. Left out for any other way, and before a first rebuild.
The draft files make a release with violations; each names its file, a JSON pointer and what is wrong.
List the index runs, newest first
GET/api/v1/index-runs
A page of index runs, newest first; links and meta lead to the others.
Parameters
The page, counted from 1. Default: 1.
How many to a page. Default: 15.
Answers
Index the current catalog with the published release again
Show an index run with its report
Show what searches read now
Change prices and stock without sending the catalog
PUT/api/v1/offers
A batch of offer changes, each a product's price, sale, stock, availability or delivery days in one channel; the fields a change leaves out stay as they are. Each change is answered on its own: kept, or left out with a code and a sentence, such as for a product the live catalog lacks. The changes kept make one revision. Within seconds, the indexer compiles the changed products again and replaces their documents in the live indexes; batches sent close together are written together, and no index run is queued. Once searches read them, GET /api/v1/live and every trace name the revision. The same catalog sent again keeps the changes, another catalog supersedes them, and a rebuild never undoes a change that came after its catalog. Until the next run, what the run derived from the whole catalog stays as it was: the dictionary's counts, derived price buckets and the values each facet counts. A product an overlay hides because of its new offer leaves search at once, and a sale window that opens or closes builds the search again at that moment.
Body
A batch of offer changes, such as { "offers": [{ "product": "SOFA-MALMO", "variant": "SOFA-MALMO-GREY", "channel": "de", "price": 899, "availability": "in_stock" }] }, each answered on its own.
At most offers_per_call.
A change of one product's offer in one channel. The fields given replace the offer's, the fields left out stay as they are. A product without variants is changed as itself; a product with variants names the variant. A channel the product has no offer in yet gets one.
10 fields
The product's id in the catalog.
The merchant's id of an entity, unique per type, such as SOFA-LUND-3. It travels unchanged; OrbSearch never rewrites it.
A channel's id, such as de or ch: a market or storefront.
In the channel's currency, in its major unit.
The reduced price, valid within sale_window if one is given.
Ends the sale: the sale price and its window go, and the price holds.
One of in_stock, out_of_stock, preorder or backorder.
Answers
Each change is answered.
3 fields
The revision the kept changes make; left out when none was kept.
One verdict per change, in the order sent.
What became of one change.
2 fields
Kept; it reaches search with the revision.
Left out, and why; the other changes of the batch are kept.
2 fields
Why a change was left out. Codes are stable; the sentence beside them may change.
7 values
The change is not an object of the fields above, such as a price written as text.
The live catalog has no product with this id; a new product arrives with the catalog.
The product has no variant with this id, or no variants at all.
The product has variants, so the change names the one it changes.
The channel is not one of the live release.
A value no offer can hold, such as a negative price, a sale window that ends before it starts, delivery days whose min is above their max, or a sale price beside end_sale.
The change names no field to change.
What happens next, as a sentence.
The body holds no list of offers, or more than offers_per_call.
Show what the storage keeps and the disk it takes
GET/api/v1/storage
The indexer cleans up once it starts and after every run that goes live. It keeps the snapshot of the live run, of every run still queued or running, of every draft and of an import that failed since the live run went live, the current catalog, and the newest kept_snapshots others that went live. Every other file goes; its row stays with removed_at, and so do its runs. It also drops the dictionaries of runs that are not live and the engine indexes no run uses, then measures the engine.
Answers
The storage.
3 fields
How many snapshots that went live are kept beside the live one, newest first. Default: 5.
The engine's indexes on disk, as the indexer measured them after it last cleaned up; left out before it did.
The engine's size on disk, when it was measured.
2 fields
A point in time as RFC 3339 with an offset, such as 2026-11-27T00:00:00+01:00.
Change how many earlier catalogs are kept
PATCH/api/v1/storage
Takes effect at the indexer's next clean-up, after the next run that goes live or when it starts. Keeping fewer removes files; keeping more brings none back.
Body
A change of what the storage keeps.
How many snapshots that went live to keep beside the live one, newest first.
Answers
The storage, with the new setting.
3 fields
How many snapshots that went live are kept beside the live one, newest first. Default: 5.
The engine's indexes on disk, as the indexer measured them after it last cleaned up; left out before it did.
The engine's size on disk, when it was measured.
2 fields
A point in time as RFC 3339 with an offset, such as 2026-11-27T00:00:00+01:00.
Show what shoppers searched and clicked, what found nothing and the filters they chose
GET/api/v1/insights
From the search log's daily rollups, for UTC days from to to: the searches, those that found nothing, those with a click and those with results but no click, each with its denominator, per day too with the Query API's latency, where clicked hits stood, the queries searched most, those that found nothing and those that drew no click most often, the filters chosen per page, and the releases that answered. The Query API logs what it answers on /v1/search and on /v1/resolve with results, never a preview, and the clicks and views storefronts send to /v1/events; the control plane rolls the log up about once a minute and joins each click to its search by query ID for event_hours, so a search or a click shows within a minute or two, and late or unmatched events are counted. One kind of traffic is counted, shoppers by default; left_out says how many answers to tests, benchmarks and bots that left out, and how many searches each rule kept out of the queries: a query reaches them once two page views typed it that day, never with an email address or a phone number in it. Raw searches are kept 60 days; the rollups stay.
Parameters
The first UTC day counted. Default: 29 days before to.
The last UTC day counted. Default: today.
The kind of traffic counted. 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.
Rows in each list. Default: 20.
Answers
The report.
19 fields
A UTC day, such as 2026-10-09.
A UTC day, such as 2026-10-09.
Whose searches these are. A report counts one kind and says how many answers to the others it left out.
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.
When the log was last rolled up, about once a minute; a search shows at the next roll-up. Left out until the first.
The releases that answered the searches counted, the latest first.
Where the clicked hits of the listed section stood, on average, counted from 1 across the pages; left out without such a click.
First pages of category listings.
Answers to a search box while the shopper typed.
The queries counted in queries, over every day.
Every day of the range, one without searches included.
7 fields
A UTC day, such as 2026-10-09.
Of searches.
Of searches, those with a click.
The queries searched most, by their words as the engine reads them. A query is counted on a day once two page views typed it that day.
The queries that found nothing most often, the same way counted.
The queries whose searches had results and drew no click most often, the same way counted.
The pages searched most, the search page among them, each with the filters chosen on it.
4 fields
The category page's category; left out for the search page.
First pages of its results.
Of searches, those with a filter chosen.
How many each rule of the log left out of this report.
5 fields
The first pages answered to every other kind of traffic, on every surface.
Searches whose query fewer than two page views typed that day, or that is longer than 200 characters: counted in searches, never shown as a query.
Searches whose query held an email address or a phone number, which the log masked: counted in searches, never shown as a query.
Searches of any traffic the Query API answered but could not log, since its buffer was full or Postgres did not take them.
The clicks and views no search of the report counts.
3 fields
Events of any traffic that arrived on one of the days more than event_hours after their answer, which the Query API refused.
Events of this traffic for an answer on one of the days that the log holds nothing of this traffic for: a preview's, one the log could not record, another traffic's, or a made-up query ID.
Events of any traffic the Query API took on one of the days but could not log, since its buffer was full or Postgres did not take them.
Show the views and clicks of each sponsored products' campaign
GET/api/v1/insights/campaigns
From the daily rollups, for UTC days from to to: per campaign of the sponsored pins, the answers that served its products, the views of them and the share clicked, per day too. A view counts once per query ID and product, once a storefront reported half of the tile visible for a second or a click on it; an event counts only where an answer of its page, of its traffic, placed the product with the campaign it names, and for that answer's day, within event_hours. One kind of traffic is counted, shoppers by default. With Accept: text/csv the same report comes as a CSV to send to the brand, one row per campaign. The rollups outlive the 60 days of raw searches and events, so a campaign's report reaches back as far as the shop has run it.
Parameters
The first UTC day counted. Default: 29 days before to.
The last UTC day counted. Default: today.
The kind of traffic counted. 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 report.
5 fields
A UTC day, such as 2026-10-09.
A UTC day, such as 2026-10-09.
Whose searches these are. A report counts one kind and says how many answers to the others it left out.
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.
When the log was last rolled up, about once a minute. Left out until the first.
Every campaign served or seen in the range, the most viewed first.
5 fields
A sponsored placement's campaign, the merchant's name for it, such as Michelin spring: one line of up to 200 characters, which reports and their CSV group views and clicks by.
The answers that placed one of its products, every page counted.
Its products seen: each once per query ID, once half of its tile was visible for a second or it was clicked.
Show the category tree of what is live
GET/api/v1/categories
Every category of the live catalog with its parent, titles, paths and channels, and the type its page lists with how many entities that is, named by the release and the catalog snapshot that answered. The nodes name their parents, so the caller arranges the tree.
Answers
The categories.
3 fields
The configuration that is live.
The catalog the categories are read from.
Every category, by id. Each names its parent, so a client arranges the tree itself; a parent does not necessarily come before its children.
One category node of the live catalog.
7 fields
The id of a category node, such as wohnen/sofas: the merchant's id of a category entity.
The parent node; left out for a root.
What the node is called per locale; left out where the catalog gives no title.
The page's path in the merchant's shop per locale, such as /wohnen/sofas; left out where the catalog gives none.
The channels the node exists in; left out where it exists in every channel.
The type its page lists: the type with offers most of the entities in it or below it are, product where it holds nothing.
How many entities of that type sit in it or below it.
Show what a page shows and where each setting comes from
POST/api/v1/pages/settings
A category page, or the search page without category, as a search on it reads it: its facets in display order with their groups, the order it starts in and the orders it offers, and every order a page can offer. Each setting names where it comes from: the page itself, the nearest category above it that sets it (Sort: price, from Wohnen), the default layout, or nothing; and whether the merchant wrote it or the index run derived it from the catalog, with the run's reason. Labels are in the locale, and url is the page's address. With files, such as a draft's categories.json, the settings are read from them over the live release, so a draft's page is seen before it is published; what the live index run derived stays as it derived it until then.
Body
The page whose settings to show.
The category whose page it is, such as wohnen/sofas. Default: the search page.
The channel. Default: the release's first channel.
The locale the labels and the address are in. Default: the channel's first locale.
Release files by name in place of the live release's own, such as a draft's categories.json: the settings are read from them, completed with what the live index run derived, so a draft's page is seen before it is published. What the run derived stays as it derived it until the draft is published, also where the draft changes what it was derived from, such as the default facets the categories follow.
Answers
The page's settings.
10 fields
The configuration that decided: the live release, or the draft the files make.
The catalog the categories are read from.
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 whose page it is; left out for the search page.
The category's title in the locale; left out for the search page.
Where the shop shows the page in the locale: the category's path, or the search page's. Left out where the category has no page in the channel.
The facets a page shows, in display order, a group's facets together.
2 fields
The list is taken whole from one place.
Where a setting of a page comes from. A page takes each setting from the nearest category up the tree that sets it, else from the default layout of categories.json.
4 fields
The page's own category sets it.
1 field
The release leaves it out, so the index run derived it from the catalog.
The nearest category above the page that sets it, which the page inherits it from.
The default layout, which every page that sets none inherits.
1 field
The release leaves it out, so the index run derived it from the catalog.
Nothing sets it, so the page has none, or starts by relevance.
One facet of a page.
7 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 field's name in the locale.
How the list writes it, or for a field code alone, how the default layout shows the field.
The list names the field alone, so shown is how the default layout shows it.
The group the page draws it in.
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.
Why the index run chose it, where the list is derived.
What in the catalog decided a derived setting. Codes are stable, so the panel translates them.
18 fields
The catalog holds entities of this built-in type, or the export makes them, such as categories from paths.
1 field
Most words that tell languages apart are this language's, in this share of them, in percent.
2 fields
A BCP 47 language tag such as de, de-CH or en. A locale falls back along its tag: de-CH to de.
This share of the values, in percent, reads as this type; a quantity also names the unit most of them use.
5 fields
8 values
Free text: searchable, never a filter.
GTIN, MPN, ISBN and similar: exact match after normalization.
Enumerated values with labels, aliases, order, groups and swatches.
A number without a unit.
A number with a unit of one dimension.
A minimum and a maximum with a unit, such as age 3 to 6.
A date or a point in time.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
27 values
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
Values read, and how many of them differ, up to a cap.
The variants carry the value in this many products, so it is the variants': an export puts there what differs inside a group, JSON Lines what the merchant wrote on the variants.
1 field
This many values arrive as lists, which only an attribute that takes several values reads.
1 field
This share of the values, in percent, are color words, so the import places them in color groups.
1 field
This share of the values, in percent, are machine codes such as HOME_FURNITURE_AND_DECOR: data for rules, not words a shopper filters by, so the attribute is no filter.
1 field
The search pages filter by this option, so a query that names one of its values or groups is read as that filter (detect_in_query), within the token dimensions its facet already spends.
Every shop offers it: relevance and price sorting, the price and category facets.
Offers carry what it reads, such as delivery days or sale prices, in this many items.
1 field
This share of an identifier's values, in percent, of this many, belong to one product alone: a typo in one names another product, so the attribute is exempt from typos.
2 fields
The groups of facets a page draws under one heading.
2 fields
Where a setting of a page comes from. A page takes each setting from the nearest category up the tree that sets it, else from the default layout of categories.json.
4 fields
The page's own category sets it.
1 field
The release leaves it out, so the index run derived it from the catalog.
The nearest category above the page that sets it, which the page inherits it from.
The default layout, which every page that sets none inherits.
1 field
The release leaves it out, so the index run derived it from the catalog.
Nothing sets it, so the page has none, or starts by relevance.
Every group the page's layout sets; one whose page lists fewer than two of its facets is drawn apart.
A group of facets as the layout sets it.
4 fields
The code of a group of facets on a page, such as tyre_size.
The heading, in the locale.
The order a page starts in and the orders it offers.
3 fields
The order the page starts in while the shopper chooses none and types no words.
The order a page starts in.
4 fields
An order a page offers.
Where a setting of a page comes from. A page takes each setting from the nearest category up the tree that sets it, else from the default layout of categories.json.
4 fields
The page's own category sets it.
1 field
The release leaves it out, so the index run derived it from the catalog.
The nearest category above the page that sets it, which the page inherits it from.
The default layout, which every page that sets none inherits.
1 field
The release leaves it out, so the index run derived it from the catalog.
Nothing sets it, so the page has none, or starts by relevance.
Why the index run chose it, where it is derived.
What in the catalog decided a derived setting. Codes are stable, so the panel translates them.
18 fields
The catalog holds entities of this built-in type, or the export makes them, such as categories from paths.
1 field
Most words that tell languages apart are this language's, in this share of them, in percent.
2 fields
A BCP 47 language tag such as de, de-CH or en. A locale falls back along its tag: de-CH to de.
This share of the values, in percent, reads as this type; a quantity also names the unit most of them use.
5 fields
8 values
Free text: searchable, never a filter.
GTIN, MPN, ISBN and similar: exact match after normalization.
Enumerated values with labels, aliases, order, groups and swatches.
A number without a unit.
A number with a unit of one dimension.
A minimum and a maximum with a unit, such as age 3 to 6.
A date or a point in time.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
27 values
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
Values read, and how many of them differ, up to a cap.
The variants carry the value in this many products, so it is the variants': an export puts there what differs inside a group, JSON Lines what the merchant wrote on the variants.
1 field
This many values arrive as lists, which only an attribute that takes several values reads.
1 field
This share of the values, in percent, are color words, so the import places them in color groups.
1 field
This share of the values, in percent, are machine codes such as HOME_FURNITURE_AND_DECOR: data for rules, not words a shopper filters by, so the attribute is no filter.
1 field
The search pages filter by this option, so a query that names one of its values or groups is read as that filter (detect_in_query), within the token dimensions its facet already spends.
Every shop offers it: relevance and price sorting, the price and category facets.
Offers carry what it reads, such as delivery days or sale prices, in this many items.
1 field
This share of an identifier's values, in percent, of this many, belong to one product alone: a typo in one names another product, so the attribute is exempt from typos.
2 fields
Why the page starts in another order than the layout names, such as a sort ranking.json no longer defines.
The orders the page offers, as its answers list them.
The orders a page offers.
3 fields
The list is taken whole from one place.
Where a setting of a page comes from. A page takes each setting from the nearest category up the tree that sets it, else from the default layout of categories.json.
4 fields
The page's own category sets it.
1 field
The release leaves it out, so the index run derived it from the catalog.
The nearest category above the page that sets it, which the page inherits it from.
The default layout, which every page that sets none inherits.
1 field
The release leaves it out, so the index run derived it from the catalog.
Nothing sets it, so the page has none, or starts by relevance.
Why the index run chose them, where they are derived.
What in the catalog decided a derived setting. Codes are stable, so the panel translates them.
18 fields
The catalog holds entities of this built-in type, or the export makes them, such as categories from paths.
1 field
Most words that tell languages apart are this language's, in this share of them, in percent.
2 fields
A BCP 47 language tag such as de, de-CH or en. A locale falls back along its tag: de-CH to de.
This share of the values, in percent, reads as this type; a quantity also names the unit most of them use.
5 fields
8 values
Free text: searchable, never a filter.
GTIN, MPN, ISBN and similar: exact match after normalization.
Enumerated values with labels, aliases, order, groups and swatches.
A number without a unit.
A number with a unit of one dimension.
A minimum and a maximum with a unit, such as age 3 to 6.
A date or a point in time.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
27 values
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
Values read, and how many of them differ, up to a cap.
The variants carry the value in this many products, so it is the variants': an export puts there what differs inside a group, JSON Lines what the merchant wrote on the variants.
1 field
This many values arrive as lists, which only an attribute that takes several values reads.
1 field
This share of the values, in percent, are color words, so the import places them in color groups.
1 field
This share of the values, in percent, are machine codes such as HOME_FURNITURE_AND_DECOR: data for rules, not words a shopper filters by, so the attribute is no filter.
1 field
The search pages filter by this option, so a query that names one of its values or groups is read as that filter (detect_in_query), within the token dimensions its facet already spends.
Every shop offers it: relevance and price sorting, the price and category facets.
Offers carry what it reads, such as delivery days or sale prices, in this many items.
1 field
This share of an identifier's values, in percent, of this many, belong to one product alone: a typo in one names another product, so the attribute is exempt from typos.
2 fields
In display order. A page that lists any offers the order it starts in too, marked default.
Every order a page can offer, relevance first, in the locale.
The body names a category the live catalog lacks, or a channel or locale the release lacks.
The draft files make a release with violations; each names its file, a JSON pointer and what is wrong.
Search as a shopper would, in any context and at any time, with the trace
POST/api/v1/preview/search
The request as POST /v1/search takes it, answered against what searches read now, except that it may fix time: a scheduled rule or sale is checked on the day it starts. Without time it is answered now. The response always carries the trace, which names the rule behind every pin, boost and bury of each hit; the panel's playground shows the same answer.
Body
objectRequired
One search, category page or autocomplete request.
Answers
Open one of the shop's URLs as a shopper would, in any context and at any time
POST/api/v1/preview/page
A URL of the shop, such as a category page with its filters, answered as GET /v1/resolve answers it, with its results, in the channel, locale and context and at the time the body names. The page and its results always carry their traces; the panel's playground shows the same answer. With files, such as a draft's categories.json, the page is planned with them in place of the live release's own, so a draft's facets, sorting and URLs are seen before it is published.
Body
A URL to preview as a shopper would meet it in a context and at a time, such as { "url": "/reifen?saison=winter", "channel": "de", "time": "2026-11-27T00:00:00+01:00" }. The page always comes with its results and traces.
The URL as resolve reads it: a path with its query string, 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.
Declared context keys and their values, as a search request carries them, such as { "customer_group": "b2b" }.
The time the page is answered at. Default: now.
Release files by name that replace the live release's own for this preview alone, such as a draft's categories.json: the page is planned with them over the live catalog and index, so a draft's facets, sorting and URLs can be seen before it is published. What a file changes in the compiled index (a new attribute, a rule's pins) is not in the index until it is published, so such a preview shows the page as the live index can answer it.
Answers
The request cannot be answered as sent, such as a channel or context key the release lacks.
The draft files make a release with violations; each names its file, a JSON pointer and what is wrong.
Say why one hit of a preview sits above another
POST/api/v1/preview/compare
The trace a preview answered with, sent back whole, the section and two places on its page. The answer names what put the higher hit above the other, from the trace alone and in the order the engine decides: a pin, boosts and buries that outweighed the text, or the first criterion they differ in, with each hit's value. Every hit of a preview also carries why, its own reasons, in the rank step.
Body
Two hits of a trace's rank step to compare: which sits above the other, and why. The trace is the one a debug or preview response carried, sent back whole, so the answer is about exactly what was shown.
The section both hits are in.
Their places on the page, counted from 1, in either order.
Answers
Why one sits above the other.
4 fields
The first thing that separated them, in a sentence.
What put one hit above the other, in the order the engine decides: pins, then boosts and buries against the text, then the first criterion they differ in.
5 fields
A rule pinned one of them.
4 fields
A rule's id, unique per release, such as home/out-of-stock-last. It appears in traces, tests, diffs and filter chips, so it is visible to storefronts and holds no secrets.
One of above or below.
Boosts and buries weighed them apart: they count before every criterion but a better match of the query's words, and the lower one matches those as well or better.
The first criterion they differ in, with each one's value.
2 fields
One criterion the engine compared hits by, with this hit's value. Hits are compared criterion by criterion in the order the engine ranks by, and the first criterion two hits differ in decides which comes first.
7 fields
How many typos it took to find those words; fewer come first.
1 field
The sort the request chose, and the hit's value in it; a hit without a value comes last.
4 fields
The code of a sort option, such as price_asc. relevance is built in.
A field of an entity as search and result settings name it: a core field such as title, or an attribute as attributes.<code>; sort options also read signals.<code>.
One of asc or desc.
Its business score from 0 to 1; higher comes first.
1 field
How close together the query's words stand in it, from 0 to 1; closer comes first.
1 field
How early among the type's searched fields, and how early in a field, the words were found, from 0 to 1.
1 field
One criterion the engine compared hits by, with this hit's value. Hits are compared criterion by criterion in the order the engine ranks by, and the first criterion two hits differ in decides which comes first.
7 fields
How many typos it took to find those words; fewer come first.
1 field
The sort the request chose, and the hit's value in it; a hit without a value comes last.
4 fields
The code of a sort option, such as price_asc. relevance is built in.
A field of an entity as search and result settings name it: a core field such as title, or an attribute as attributes.<code>; sort options also read signals.<code>.
One of asc or desc.
Its business score from 0 to 1; higher comes first.
1 field
How close together the query's words stand in it, from 0 to 1; closer comes first.
1 field
How early among the type's searched fields, and how early in a field, the words were found, from 0 to 1.
1 field
They are equal in everything the engine compares, so it keeps the order of its index.
By everything the trace records, the lower one comes first; what put the other above is not recorded.
Say why a product is not on a preview's page, or where it is
POST/api/v1/preview/find
The request a preview's trace holds, its time included, and the entity to find, such as { "request": { "query": "ecksofa" }, "entity": "product:SOFA-MALMO" }. The answer walks the stages a search passes it through and names the first that drops it: not in the live index, not searched on the page, not sold in the channel, outside the channel's assortment, outside the category, a rule's filter or hide, a filter the shopper chose or the query named, the query's words, which words match in which fields and which do not, or ranked after the page, with its place and why the page's last hit sits above it. Every answer ends in what to do: open the rule, remove the filter, add a synonym, pin it. The panel's playground shows the same answer.
Body
An entity to find on the page a request answers, such as { "request": { "query": "ecksofa" }, "entity": "product:SOFA-MALMO" }.
The request of the page, as a preview's trace holds it with its time, so the answer is about the page shown.
An entity named with its type, type:id, such as product:SOFA-LUND-3.
Answers
Where it is, or the stage that kept it off the page.
8 fields
The configuration that answered.
The catalog that was searched.
An entity named with its type, type:id, such as product:SOFA-LUND-3.
The stages it passed, in the order a search runs them.
A stage the entity passed, in a sentence.
2 fields
The stages a search passes an entity through on its way onto a page, in order.
9 values
The live index holds it.
The page searches its type.
It is sold in the channel.
It is in the channel's assortment.
It is in the page's category, or the one the query named.
No rule's filter or hide removes it.
It matches the filters the shopper chose and the query named.
The query's words find it.
Its place among the hits.
Such as "It is sold in the channel de."
The first stage that kept the entity off the page, with what it found, or the entity's place on it.
14 fields
The live index holds no entity of this type and id: the catalog snapshot lacks it, or a hide overlay removes it from every search. overlays are the release's hide overlays of its type that name it or may match it.
1 field
The page searches no section of its type: a category page and a search without words list one type alone.
A rule's redirect sends the shopper elsewhere, so the page searches nothing.
3 fields
A rule's id, unique per release, such as home/out-of-stock-last. It appears in traces, tests, diffs and filter chips, so it is visible to storefronts and holds no secrets.
It is not sold in the channel: no offer of it is there.
1 field
A channel's id, such as de or ch: a market or storefront.
It has an offer in the channel, but the channel's assortment leaves it out: it does not match the selector.
2 fields
A channel's id, such as de or ch: a market or storefront.
A rule's filter narrows the section to what it is not.
3 fields
A rule's id, unique per release, such as home/out-of-stock-last. It appears in traces, tests, diffs and filter chips, so it is visible to storefronts and holds no secrets.
A filter the shopper chose, or the query's words named, keeps what it is not.
It has each chosen value in some variant, but no variant has them all.
The query's words do not find it.
4 fields
The text the section searched, after rules and what the query named took their words.
The words that find it alone, with the fields they are in and the synonym that found them.
A word of the query and how the hit was found by it.
5 fields
The word as the engine reads the query.
The synonym it was found through, when the hit holds the synonym and not the word itself.
The entry of synonyms.json that leads the word to its synonym, such as de/groups/0; with synonym only.
The word of the hit it was found by with a typo, as its field writes it, such as Bremsbelag for bremsbelg.
The searched fields it was found in, in the type's order, such as title; words holds what the index adds, such as the titles of its categories.
The words no field of it holds, as typed, through a synonym or with a typo.
Missing words a field of it holds where the search does not look for them: a field its type does not search, or an attribute exempt from typos that holds the word with a typo.
A word of the query that a field of the entity holds where the search does not look for it.
4 fields
The word as the engine reads the query.
The field, such as attributes.mpn or brand.
The field's word, as it writes it, such as 1K0615301.
Why the search does not find a word a field holds.
2 values
The type does not search the field; it holds the word as typed.
The attribute is exempt from typos, and holds the word with as many typos as its length would allow elsewhere.
It is found, and ranks on another page: after this one, or before it on a later page.
4 fields
Its place among the hits, counted from 1.
The page it is on, at the request's page size.
Why it sits there, as a hit on its page would say.
One reason a hit sits where it does, in a sentence and as data.
2 fields
The reason in a sentence, such as "Pinned to position 1 by the rule “Sommer-Sale”."
7 fields
A rule pinned it to its place, which comes before everything else; a paid pin names its campaign, and the sentence calls it a sponsored placement of that campaign.
4 fields
A rule's id, unique per release, such as home/out-of-stock-last. It appears in traces, tests, diffs and filter chips, so it is visible to storefronts and holds no secrets.
A rule's boost or bury weighed it against the hits beside it.
4 fields
A rule's id, unique per release, such as home/out-of-stock-last. It appears in traces, tests, diffs and filter chips, so it is visible to storefronts and holds no secrets.
One of resolve, rewrite, redirect, filter, hide, pin, boost, bury, sections or place.
Words of the query named something it is or has, which narrowed the results to it.
6 fields
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" } }
Where the meaning comes from, such as "the alias "graues" of the color group Grau".
A rule's id, unique per release, such as home/out-of-stock-last. It appears in traces, tests, diffs and filter chips, so it is visible to storefronts and holds no secrets.
The entry of synonyms.json that let the words name it, such as de/groups/0, when a synonym did.
A word of the query found it only through a synonym, which the entry of synonyms.json holds.
The sort the request chose orders the page.
4 fields
The code of a sort option, such as price_asc. relevance is built in.
A field of an entity as search and result settings name it: a core field such as title, or an attribute as attributes.<code>; sort options also read signals.<code>.
One of asc or desc.
Its business score orders it among the hits that match as well as it does; signal adds the most to it.
2 fields
Why the last hit of the asked page sits above it, when it ranks after the page.
Why one hit sits above another of the same section.
4 fields
The first thing that separated them, in a sentence.
What put one hit above the other, in the order the engine decides: pins, then boosts and buries against the text, then the first criterion they differ in.
5 fields
A rule pinned one of them.
4 fields
A rule's id, unique per release, such as home/out-of-stock-last. It appears in traces, tests, diffs and filter chips, so it is visible to storefronts and holds no secrets.
One of above or below.
Boosts and buries weighed them apart: they count before every criterion but a better match of the query's words, and the lower one matches those as well or better.
The first criterion they differ in, with each one's value.
2 fields
One criterion the engine compared hits by, with this hit's value. Hits are compared criterion by criterion in the order the engine ranks by, and the first criterion two hits differ in decides which comes first.
7 fields
How many typos it took to find those words; fewer come first.
1 field
The sort the request chose, and the hit's value in it; a hit without a value comes last.
4 fields
The code of a sort option, such as price_asc. relevance is built in.
A field of an entity as search and result settings name it: a core field such as title, or an attribute as attributes.<code>; sort options also read signals.<code>.
One of asc or desc.
Its business score from 0 to 1; higher comes first.
1 field
How close together the query's words stand in it, from 0 to 1; closer comes first.
1 field
How early among the type's searched fields, and how early in a field, the words were found, from 0 to 1.
1 field
One criterion the engine compared hits by, with this hit's value. Hits are compared criterion by criterion in the order the engine ranks by, and the first criterion two hits differ in decides which comes first.
7 fields
How many typos it took to find those words; fewer come first.
1 field
The sort the request chose, and the hit's value in it; a hit without a value comes last.
4 fields
The code of a sort option, such as price_asc. relevance is built in.
A field of an entity as search and result settings name it: a core field such as title, or an attribute as attributes.<code>; sort options also read signals.<code>.
One of asc or desc.
Its business score from 0 to 1; higher comes first.
1 field
How close together the query's words stand in it, from 0 to 1; closer comes first.
1 field
How early among the type's searched fields, and how early in a field, the words were found, from 0 to 1.
1 field
They are equal in everything the engine compares, so it keeps the order of its index.
By everything the trace records, the lower one comes first; what put the other above is not recorded.
The verdict in a sentence, ending in what to do.
What the merchant can do to show it on the page, the likeliest first; none when it is there.
One thing the merchant can do to show the entity on the page.
12 fields
Check the entity in the shop's export: the snapshot was read from it.
Open the overlay that may hide it.
1 field
An id unique within its file, such as a search test's, an overlay's or a pattern's.
Search with words: other types show in sections of their own beside the listed one only then.
Give it an offer in the channel, in the shop's export.
1 field
A channel's id, such as de or ch: a market or storefront.
Change the channel's assortment in channels.json, or the product's data it reads in the shop's export.
1 field
A channel's id, such as de or ch: a market or storefront.
Assign it to the category, in the shop's export.
1 field
The id of a category node, such as wohnen/sofas: the merchant's id of a category entity.
Open the rule, to change its condition or what it keeps.
2 fields
A rule's id, unique per release, such as home/out-of-stock-last. It appears in traces, tests, diffs and filter chips, so it is visible to storefronts and holds no secrets.
Remove the filter, as the shopper's chip does.
2 fields
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" } }
Add a synonym, so these words find what it holds.
1 field
Add these words to its search words with an overlay.
1 field
Pin it with a rule at this place, so it shows on the page whatever ranks above it.
1 field
Open how the type is searched: its fields in order, its typo settings and the attributes exempt from typos.
1 field
The code of an entity type, such as product, category or a merchant's own store.
The engine call that walked the stages, beside the page's own search: from sending it to reading its answer, in milliseconds. Debug only; no shopper's search makes it.
Guide: Importing and mapping · Releases
AppliedOffers
The offer changes a run's indexes hold.
The latest batch the indexes hold, which every trace names.
When that batch arrived: the prices and stock searches show are at least as new.
The products of the catalog whose offers the changes reach.
Banner
What a placement shows: a campaign's banner or a teaser to a page, with its words in every locale the release serves.
2 values
The headline, up to 200 characters.
A line or two under the title.
Where it leads, written as a redirect's target: an entity's page, such as { "to": "category:wohnen/sofas" } or { "to": "content:sofa-ratgeber" }, or a fixed URL, { "url": "/sale" }. Without one it only informs.
Where a redirect goes: an entity's page, whose URL follows the merchant's catalog, or a fixed URL.
BannerPlacement
A banner at a place of the page: { "slot": "top", "banner": { ... } }, or among the tiles, { "slot": "grid", "position": 5, "banner": { ... } }.
Where on a page a banner sits.
3 values
With grid, and only there: the tile it sits before, counted from 1 across the pages of the listed section, whose tiles are the page's products, or its services on a workshop's page. Positions are unique within a rule; on a tie between rules the higher one takes the position and the other moves to the next free one, as pins do. A position past the last tile the pages reach shows nowhere, and the trace says why.
Bucket
A bucket from from (inclusive) to to (exclusive); either end may be open. Without from, a bucket counts everything up to its to, as in "up to 2 weeks"; without to, everything from its from on, as in "4 stars and more". Such open buckets may overlap.
A plain value, or a map from locale to value such as { "de": "Farbe", "en": "Color" }.
CatalogFetch
One fetch of the catalog source and how it ended.
Someone asked for it; the schedule made the others. Left out for those.
A point in time as RFC 3339 with an offset, such as 2026-11-27T00:00:00+01:00.
Left out while it runs.
Left out while it runs.
5 values
The feed is the one fetched before, by the server's 304 or by its bytes, so nothing was queued.
The feed changed and its import is on its way live.
The feed changed and waits as a draft import.
The feed would remove half the live products or more, so it waits as a draft import, to be published with the number confirmed.
Nothing changed for searches; failure says why.
Why it failed.
11 values
The host is in a private, loopback or link-local network, which the stack does not fetch from.
The host is unknown, or did not answer.
The feed did not arrive in time.
The server answered with another error status, in status.
The URL redirects more than five times.
The feed is larger than the largest upload, 2 GB.
The server sent nothing.
The Query API cannot read the file.
The feed arrived, but publishing it was refused; the next fetch tries again.
The fetch stopped halfway, such as when the control plane restarted.
The feed server's HTTP status, where it answered with an error.
What a failed or held-back fetch means for the merchant, as a sentence.
The size of the feed, where it arrived.
ColumnRead
A column's target with the options that say how its cells are read. The list is closed on purpose: no templates, expressions or combined columns until a real feed needs one.
Where a column's values go: a field such as title or price, attributes.<code>, attributes.* (the code made from what the column name's * matched), attributes (with name or pairs), signals.<code>, or ignore.
Lists: the text between the values of one cell, such as , in "bild1.jpg,bild2.jpg" or | in "Holz|Metall"; or several, any of which separates them, such as ["|", ";"] in "Blau;Schwarz|Grau".
Categories: the text between the levels of one path, such as > in "Wohnen > Sofas".
Availability: the shop's words for each state, such as { "sofort lieferbar": "in_stock" }. One of in_stock, out_of_stock, preorder or backorder.
Attributes: the unit of plain numbers in the column, such as cm for a column "Breite" holding "218".
27 values
Attributes: the unit of plain numbers in the column, such as cm for a column "Breite" holding "218".
Attributes: the unit of plain numbers in the column, such as cm for a column "Breite" holding "218".
Attributes: the unit of plain numbers in the column, such as cm for a column "Breite" holding "218".
Attributes: the unit of plain numbers in the column, such as cm for a column "Breite" holding "218".
Attributes: the unit of plain numbers in the column, such as cm for a column "Breite" holding "218".
Attributes: the unit of plain numbers in the column, such as cm for a column "Breite" holding "218".
Attributes: the unit of plain numbers in the column, such as cm for a column "Breite" holding "218".
Attributes: the unit of plain numbers in the column, such as cm for a column "Breite" holding "218".
Attributes: the unit of plain numbers in the column, such as cm for a column "Breite" holding "218".
Attributes: the unit of plain numbers in the column, such as cm for a column "Breite" holding "218".
Attributes: the unit of plain numbers in the column, such as cm for a column "Breite" holding "218".
Attributes: the unit of plain numbers in the column, such as cm for a column "Breite" holding "218".
Attributes: the unit of plain numbers in the column, such as cm for a column "Breite" holding "218".
Attributes: the unit of plain numbers in the column, such as cm for a column "Breite" holding "218".
Attributes: the unit of plain numbers in the column, such as cm for a column "Breite" holding "218".
Attributes: the unit of plain numbers in the column, such as cm for a column "Breite" holding "218".
Attributes: the unit of plain numbers in the column, such as cm for a column "Breite" holding "218".
Attributes: the unit of plain numbers in the column, such as cm for a column "Breite" holding "218".
Attributes: the unit of plain numbers in the column, such as cm for a column "Breite" holding "218".
Attributes: the unit of plain numbers in the column, such as cm for a column "Breite" holding "218".
Attributes: the unit of plain numbers in the column, such as cm for a column "Breite" holding "218".
Attributes: the unit of plain numbers in the column, such as cm for a column "Breite" holding "218".
Attributes: the unit of plain numbers in the column, such as cm for a column "Breite" holding "218".
Attributes: the unit of plain numbers in the column, such as cm for a column "Breite" holding "218".
Attributes: the unit of plain numbers in the column, such as cm for a column "Breite" holding "218".
Attributes: the unit of plain numbers in the column, such as cm for a column "Breite" holding "218".
Attributes: the unit of plain numbers in the column, such as cm for a column "Breite" holding "218".
Texts, categories and localized attributes: the locale the column is written in. Default: the source locale, the first channel's first locale.
Offer fields: the channel the column's prices or stock belong to. Default: the first channel in channels.json.
Attributes written as name and value in two columns: the column holding each value's attribute name, with the same * as this column's name, such as "Attribute * name" beside "Attribute * value(s)".
Attributes written as pairs in one cell, such as "Farbe: Rot | Breite: 218 cm": the text between the pairs.
With pairs: the text between an attribute's name and its value. Default: :.
Condition
A predicate over the request (when). Without a condition, a rule always matches.
{ "on": "search", "query": { "contains": ["bremsen", "bremse"] } }
The query as typed, after normalization. Matching is literal: no typos, synonyms or plurals.
How the query must look. A list of phrases means any of them.
4 fields
One value, or a list meaning any of them.
One value, or a list meaning any of them.
One value, or a list meaning any of them.
True: nothing was typed. False: something was.
The surface the request comes from.
3 values
The search page's results.
A category's listing.
A search box's suggestions while the shopper types.
What the query named. Rules that resolve or rewrite run before resolution and cannot read it.
One value, or a list meaning any of them.
One value, or a list meaning any of them.
Declared context keys and the values they must have, such as { "customer_group": "b2b" }.
Course
The way a release goes live and why, as data and as a sentence.
How a release goes live, from the cheapest to the dearest.
3 values
The live indexes and the catalog dictionary stay, and the Query API loads the new release. It goes live at once.
Settings the engine applies without reindexing, such as synonyms, are written to the live indexes, then the release is switched in. It goes live within moments.
New indexes are built from the catalog beside the live ones and swapped in. The shop keeps answering with the live release meanwhile, and the time grows with the catalog.
What decided the way. A file is named as the release writes it, such as rules.json, and a derived file by the name it would have.
10 fields
Rebuild: no index run is live yet.
Rebuild: the catalog is not the live one's, so its documents are new.
Rebuild: the merchant asked for one, such as after the engine lost its data.
Rebuild: a sale window opened or closed, or an overlay ended, at since, after the live run built its documents.
1 field
A point in time as RFC 3339 with an offset, such as 2026-11-27T00:00:00+01:00.
Rebuild: the engine no longer holds these live indexes.
1 field
Rebuild: these files change what the engine's documents are built from or the shape of its indexes: types, channels, attributes, overlays, the feed mapping, the business score, the sort options or the facets pages count.
1 field
Settings: these files change only settings the engine applies without reindexing.
1 field
Switch: these files change only what the Query API reads: rules, the layout of pages, routes and redirects.
1 field
Switch: the live run already has this release and this catalog, so nothing changes.
The same in a sentence, such as "Goes live at once: only rules.json and categories.json changed what the Query API reads."
Defaults
The release files derived from a catalog, each with why every setting in it is what it is. Only files the release leaves out are derived; a file left empty here was not derived.
types.json: the entity types a release searches, and how each is listed, searched and returned.
channels.json: the channels a merchant sells in, and the context keys requests may carry.
attributes.json: what each attribute value means.
categories.json: the facets and sort options of search and category pages.
ranking.json: signals and weights, boost and bury strengths, sort options and section order.
Why each derived setting is what it is, in the order of the files above.
Derived
One derived setting and what in the catalog decided it.
The release file the setting is written in, such as attributes.json.
The setting within it, as a person names it: an attribute's code such as width, a channel's id, a type's code, a sort option's or signal's code, weights.<type>.<signal>, default.sort, a rule's id, a facet as default.facets.<field> or <category id>.facets.<field>, and an identifier a type searches as <type>.no_typos.<attribute>.
What in the catalog decided a derived setting. Codes are stable, so the panel translates them.
18 fields
The catalog holds entities of this built-in type, or the export makes them, such as categories from paths.
1 field
Most words that tell languages apart are this language's, in this share of them, in percent.
2 fields
A BCP 47 language tag such as de, de-CH or en. A locale falls back along its tag: de-CH to de.
This share of the values, in percent, reads as this type; a quantity also names the unit most of them use.
5 fields
8 values
Free text: searchable, never a filter.
GTIN, MPN, ISBN and similar: exact match after normalization.
Enumerated values with labels, aliases, order, groups and swatches.
A number without a unit.
A number with a unit of one dimension.
A minimum and a maximum with a unit, such as age 3 to 6.
A date or a point in time.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
27 values
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
Values read, and how many of them differ, up to a cap.
The variants carry the value in this many products, so it is the variants': an export puts there what differs inside a group, JSON Lines what the merchant wrote on the variants.
1 field
This many values arrive as lists, which only an attribute that takes several values reads.
1 field
This share of the values, in percent, are color words, so the import places them in color groups.
1 field
This share of the values, in percent, are machine codes such as HOME_FURNITURE_AND_DECOR: data for rules, not words a shopper filters by, so the attribute is no filter.
1 field
The search pages filter by this option, so a query that names one of its values or groups is read as that filter (detect_in_query), within the token dimensions its facet already spends.
Every shop offers it: relevance and price sorting, the price and category facets.
Offers carry what it reads, such as delivery days or sale prices, in this many items.
1 field
This share of an identifier's values, in percent, of this many, belong to one product alone: a typo in one names another product, so the attribute is exempt from typos.
2 fields
DerivedValue
An option value whose meaning the import derived instead of reading it from attributes.json: a value the feed brought, or a color group the built-in colors gave a value.
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 code of an option value or option group, such as grey or 160x230.
The feed's spelling as first seen, which shoppers see for a value attributes.json does not list.
attributes.json lists the value without a group, and the built-in colors gave it one.
Entities and variants that carry the value.
The groups it shows under; a value between two colors, such as petrol, may have two.
How the built-in colors chose the group, for attributes with color groups.
The stage of the built-in colors that placed a value in a group, or that none did.
4 fields
The whole name is a color the built-in table knows, such as "Anthrazit".
The color word inside the name that decides, such as "basalt" in "Basaltgrau".
1 field
No stage placed it: the name holds no color word, or words of two groups, and the value has no swatch.
Effects
What a rule does. Understand-phase effects (resolve, rewrite) run before the query is resolved; redirect ends planning; the rest shape the results, and place puts banners beside them.
Decides what an ambiguous term means. Per term, the higher rule decides.
What one term means: values such as { "term": "puma", "as": { "brand": "puma" } }, a category such as "as": { "category": "parts/brakes" }, or "as": "text" to keep it as text.
Removes words from the query before it is resolved and searched. Removals of all rules are united.
1 field
Sends the shopper elsewhere. The highest redirect wins and ends planning.
Where a redirect goes: an entity's page, whose URL follows the merchant's catalog, or a fixed URL.
Narrows the results. Shoppers see it as a chip they can remove.
A filter a rule adds, optionally only for one type's section.
2 fields
The code of an entity type, such as product, category or a merchant's own store.
Removes entities from the results. Hide beats pin.
Puts entities at fixed positions, within every filter.
Moves entities up, within relevance.
Moves entities down, within relevance.
The order of sections. Types not listed follow in the release's order.
Puts banners and teasers above, among or below the results. A placement is not a hit: it changes no total, facet, page size or order of hits.
ExemptAttribute
An attribute, exempt from typos or left open to them.
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.
Its name in the locale.
Why the run decided so, where the list is derived.
What in the catalog decided a derived setting. Codes are stable, so the panel translates them.
18 fields
The catalog holds entities of this built-in type, or the export makes them, such as categories from paths.
1 field
Most words that tell languages apart are this language's, in this share of them, in percent.
2 fields
A BCP 47 language tag such as de, de-CH or en. A locale falls back along its tag: de-CH to de.
This share of the values, in percent, reads as this type; a quantity also names the unit most of them use.
5 fields
8 values
Free text: searchable, never a filter.
GTIN, MPN, ISBN and similar: exact match after normalization.
Enumerated values with labels, aliases, order, groups and swatches.
A number without a unit.
A number with a unit of one dimension.
A minimum and a maximum with a unit, such as age 3 to 6.
A date or a point in time.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
27 values
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
A unit OrbSearch converts between. The registry is built in: conversion factors are physics, not configuration.
Values read, and how many of them differ, up to a cap.
The variants carry the value in this many products, so it is the variants': an export puts there what differs inside a group, JSON Lines what the merchant wrote on the variants.
1 field
This many values arrive as lists, which only an attribute that takes several values reads.
1 field
This share of the values, in percent, are color words, so the import places them in color groups.
1 field
This share of the values, in percent, are machine codes such as HOME_FURNITURE_AND_DECOR: data for rules, not words a shopper filters by, so the attribute is no filter.
1 field
The search pages filter by this option, so a query that names one of its values or groups is read as that filter (detect_in_query), within the token dimensions its facet already spends.
Every shop offers it: relevance and price sorting, the price and category facets.
Offers carry what it reads, such as delivery days or sale prices, in this many items.
1 field
This share of an identifier's values, in percent, of this many, belong to one product alone: a typo in one names another product, so the attribute is exempt from typos.
2 fields
ExemptAttributes
The attributes a type's words find only as written or by their start.
The identifier attributes the type searches that the run left open to typos, each with why: what the catalog does not tell stays open. Only where the list is derived.
FacetValue
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.
FeedReport
How an export was read and mapped: what the import recognized, whether feed.json or the derived mapping placed the columns, and the columns whose values went nowhere.
The file as the import read it: its kind and, for text and spreadsheets, its encoding, delimiter, sheet and header row.
Columns feed.json does not name; their values were left out.
Columns left out on purpose: mapped to ignore, or by the derived mapping as shipping, tax and ads data, or because no row fills them.
Format
How a file is read: its kind, and for text and spreadsheets the details a guess can get wrong. The import recognizes each from the bytes; a value here pins it.
The kinds of files the import reads. Any of them may arrive gzipped.
5 values
OrbSearch's own catalog: one entity per line as JSON. It needs no mapping.
Delimited text: CSV, TSV and TXT, Merchant Center's TSV included.
An Excel workbook.
A Merchant Center feed: RSS 2.0 or Atom with the g: namespace.
JSON records of a shape of their own, as an array or one object per line: nested objects are read as columns such as dimensions.width, arrays of plain values as lists.
Text: the character encoding.
4 values
What Excel on Windows writes for German text; ISO 8859-1 reads the same.
The decimal mark of numbers written as text, such as , in "1.099,00". Without it, each column's numbers tell.
Spreadsheets: the sheet to read by its name. Default: the first.
Text and spreadsheets: the row holding the column names, counted from 1. Without it, the first row that looks like a header is taken, so title rows above it are skipped.
Hide
The entities an effect is about: one entity, several, or all that match a selector, optionally of one type.
An entity named with its type, type:id, such as product:SOFA-LUND-3.
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" } }
With where: only entities of this type.
HitAt
A hit of a section and its place on the page.
An entity named with its type, type:id, such as product:SOFA-LUND-3.
The merchant's id of an entity, unique per type, such as SOFA-LUND-3. It travels unchanged; OrbSearch never rewrites it.
Import
An export on its way to live: the file as the shop wrote it, the release files it is read with, and once published, the release and the index run that make it live. Imports are never deleted, so every export that went live can go live again while its file is kept.
Where an import stands.
6 values
Kept, not published: it can be inspected, corrected, published or discarded.
Published; its index run is queued or running.
Searches read it.
It was live, or on its way, until a later publish took its place; publishing it again goes back to it.
Its index run failed, and run.error says why. What was live before stays live.
Put aside without going live.
The version a write to this draft names. It changes with every change of the files and with the release the draft builds on.
The export of an import: the file's name as it arrived and the snapshot that keeps its bytes.
The release the import was built on: for a draft, the one published when its export arrived, though a draft always builds on the release published now, so publishing it never undoes a release published since; once published, the one it went live on. Left out before any release was published.
The release files the import reads its export with instead of the base release's, by name, in the canonical form the Query API wrote; left out when it changes none.
Once published: the release its files made.
Once published: the index run that makes it live, the latest if it was published more than once.
A point in time as RFC 3339 with an offset, such as 2026-11-27T00:00:00+01:00.
When it was last published.
A point in time as RFC 3339 with an offset, such as 2026-11-27T00:00:00+01:00.
ImportExport
The export of an import: the file's name as it arrived and the snapshot that keeps its bytes.
The file's name, as the panel or the name parameter gave it.
The id of a catalog snapshot. A snapshot is named by its content and never changes.
When the indexer's clean-up removed the file. The import can no longer be inspected or published again until the same export is sent again.
IndexRun
A snapshot and a release compiled into the engine; the latest that succeeded is live.
Where an index run stands.
5 values
Waiting for an indexer.
An indexer is building the indexes.
The indexes are live: searches read this run's snapshot and release.
The run stopped; error says why. Nothing it built went live.
A newer run replaced it: one was queued while it waited, or went live before it finished. Its indexes, if any, were dropped.
What queued the run; left out for runs queued before triggers were recorded. Its report's course.cause says something else: why the run took the way it took live.
6 values
A catalog sent to PUT /api/v1/catalog.
An import published.
A release published, or published again to roll back.
A rebuild asked for with POST /api/v1/index-runs.
The indexer itself: a sale window opened or closed, an overlay ended, or another version of it built the live indexes.
A fetch of the catalog source found its feed changed.
The id of a catalog snapshot. A snapshot is named by its content and never changes.
The id of a release. A release is named by its content and never changes.
How often an indexer took it up; a run whose indexer died is taken up again, three times at most.
How far it got: while it runs, and for a failed run the step it failed in. Left out for any other run.
Why it failed, as a sentence.
A point in time as RFC 3339 with an offset, such as 2026-11-27T00:00:00+01:00.
A point in time as RFC 3339 with an offset, such as 2026-11-27T00:00:00+01:00.
A point in time as RFC 3339 with an offset, such as 2026-11-27T00:00:00+01:00.
When its indexes became the ones searches read.
Searches read this run now, the latest that succeeded. Left out for any other run. A run that changed nothing says so in its report: its course is unchanged.
On the live run: its release.
ListedDictionary
The entries of one language: its groups, then its one-way entries, then the words never merged, each in file order.
A BCP 47 language tag such as de, de-CH or en. A locale falls back along its tag: de-CH to de.
No channel serves the language, so its synonyms wait until one does. A language a channel serves as de-CH reads the de dictionary when it has none of its own.
ListedRule
One rule with what a merchant wants to know of it.
A rule's id, unique per release, such as home/out-of-stock-last. It appears in traces, tests, diffs and filter chips, so it is visible to storefronts and holds no secrets.
Its place in the order, counted from 1. The higher rule wins where two effects exclude each other.
The rule's name, one line.
What it does and when, in one line, such as Pins Vidar Ecksofa to 1 for "sofa". Products are named by their title where the catalog holds them, else by their id.
A disabled rule is not evaluated.
Where it can act, from its condition: the surfaces it names, else the category page if it names a category, else every surface.
3 values
The search page's results.
A category's listing.
A search box's suggestions while the shopper types.
A rule's state at the list's time, as data and as a sentence.
5 fields
It applies to the requests its condition matches.
1 field
When its window closes; left out for a rule without an end.
Its window has closed.
1 field
A point in time as RFC 3339 with an offset, such as 2026-11-27T00:00:00+01:00.
It is switched off.
It acts on entities alone, and every one of them is gone from the catalog, so it does nothing until one comes back.
What other rules take from it, in rule order; none when nothing does. They come from higher rules, but for a hide, which counts wherever it stands.
What another rule takes from a rule where their effects exclude each other, as data and as a sentence. It holds where both rules can match one request: conditions that cannot meet, such as two different query phrases, never conflict.
8 fields
The highest redirect wins and ends planning, so this redirect never sends a shopper that the higher one does not.
1 field
A rule's id, unique per release, such as home/out-of-stock-last. It appears in traces, tests, diffs and filter chips, so it is visible to storefronts and holds no secrets.
The higher rule pins the same entity, and its pin counts.
The higher rule pins a position this pin asks for, so this pin moves to the next free one.
3 fields
The higher rule places a banner at a grid position this placement asks for, so this one moves to the next free one.
The higher rule boosts or buries the same target, and its strength counts. target is the target as a trace says it, such as brand is "bosch".
The entities it names, with what the catalog says of each, so an editor shows a pinned product or a banner's page by its title and photo. One the catalog no longer holds is marked gone: its effects do nothing, and the rule stays as the merchant wrote it.
What an editor sets with fields, when the fields express the whole rule.
The category page whose grid this rule is, which that page arranges: the highest rule that is enabled, acts on that page alone in every channel and at every time, only while nothing is typed, and does nothing but pin within the first GRID_SIZE positions. Left out for every other rule, a lower one of the same shape included.
ListedSynonym
One entry with what a merchant wants to know of it.
Words that mean the same, each way round, such as ["couch", "sofa"]. A word or phrase is in one group at most.
1 field
NamedEntity
An entity a rule names, as the catalog holds it in the list's channel and locale.
An entity named with its type, type:id, such as product:SOFA-LUND-3.
Its title; left out where the catalog holds none, or no longer holds the entity.
Its first photo's URL, as the catalog gives it; left out where there is none.
The catalog no longer holds it, or does not sell it in the channel.
PageLinks
The pages around this one, as URLs to fetch.
PageMeta
Where this page stands in the whole list.
Pin
An entity named with its type, type:id, such as product:SOFA-LUND-3.
The slot, counted from 1. Positions are unique within a rule; on a tie between rules the higher one takes the slot and the other moves to the next free one.
A paid placement: the hit names its campaign, so a storefront marks it as an ad and reports its views and clicks for the campaign. It is placed as any pin is, only where the product meets the page's category and filters.
The campaign a paid placement belongs to: { "campaign": "Michelin spring" }.
1 field
The merchant's name for it, which the campaign report counts by.
QueryInsight
The query's words as the engine reads them, such as sofa grau.
Of searches.
Of searches, those with a click.
Of searches, those with results.
Of with_results, those without a click.
Where its clicked hits of the listed section stood, on average, counted from 1 across the pages; left out without such a click.
The page views that searched it, summed over the days.
What its latest search listed.
RefusedSynonym
An entry that was not written, and why.
Its place among the entries sent, counted from 0.
A clash as data and as one sentence, such as "“sofa” is in the group couch, sofa, settee already."
3 fields
It names fewer than two different words; a one-way entry names a word and at least one other it finds.
The word is in another group already, or starts another one-way entry: entry is the one to add to instead, with its words.
It merges two words the never entry entry keeps apart; for a never entry, entry is the one that merges them.
Rejection
A row of the feed, or one value in a row, that was left out, and why.
The row as the merchant finds it in their file, counted from 1: the line of JSON Lines or delimited text (the header is row 1), the row of a sheet, the item of an XML feed. An entity made of several rows is named by its first.
The entity's id, when the row names one.
The export's column that holds what is wrong, as the header names it; left out for JSON Lines and for the row as a whole.
A JSON pointer to the field within the entity the row became, such as /variants/0/price; empty for the row as a whole.
What is wrong, as a code the panel translates.
18 values
The file cannot be read as the kind it seems to be, such as an XML feed that breaks off; nothing after the place it names was read.
The row is not UTF-8 text.
The row is not valid JSON.
The row is JSON, but not one entity as an object.
The row has a field no entity, variant or offer has.
A field's value has the wrong shape, such as a price written as text.
The row's type is not a type of the release.
The row sets a field its type does not have, such as variants on a category.
Offer fields sit on a product that has variants, or both on an entity and in its offers.
An offer names a channel the release does not have, or offer fields need a channel to be named.
An offer's currency is not its channel's.
Two offers of one entity or variant name the same channel.
Two variants of one product have the same id.
An earlier row has the same type and id.
The row has no id: the column that id maps is empty, or nothing maps it.
A value is not one of the attribute's type, such as a list where the attribute takes one value.
A number or quantity cannot be read, such as "about two metres".
A quantity's unit measures something else than the attribute, such as kilograms for a width.
What is wrong, as a sentence.
The value that is wrong, as the file writes it, such as "ab 249 €"; left out when the row as a whole is.
RejectionGroup
Rejections with one cause: the same code, and in a mapped export the same column.
What is wrong with a rejected row or value. Codes are stable; the sentence beside them may change.
18 values
The file cannot be read as the kind it seems to be, such as an XML feed that breaks off; nothing after the place it names was read.
The row is not UTF-8 text.
The row is not valid JSON.
The row is JSON, but not one entity as an object.
The row has a field no entity, variant or offer has.
A field's value has the wrong shape, such as a price written as text.
The row's type is not a type of the release.
The row sets a field its type does not have, such as variants on a category.
Offer fields sit on a product that has variants, or both on an entity and in its offers.
An offer names a channel the release does not have, or offer fields need a channel to be named.
An offer's currency is not its channel's.
Two offers of one entity or variant name the same channel.
Two variants of one product have the same id.
An earlier row has the same type and id.
The row has no id: the column that id maps is empty, or nothing maps it.
A value is not one of the attribute's type, such as a list where the attribute takes one value.
A number or quantity cannot be read, such as "about two metres".
A quantity's unit measures something else than the attribute, such as kilograms for a width.
The export's column, when the cause sits in one.
How many rows, or values, it left out.
The first of them, up to LISTED_EXAMPLES.
ResolvedCondition
What the query named: its category, its detected filters, and whether any text is left.
Rule
A rule's id, unique per release, such as home/out-of-stock-last. It appears in traces, tests, diffs and filter chips, so it is visible to storefronts and holds no secrets.
One line, up to 200 characters, shown in the panel, the trace and diffs.
A disabled rule is not evaluated. Default: true.
When the rule is active, checked against the time in the request, never the engine's clock.
A window in time: from from (inclusive) until until (exclusive). Either end may be open.
RuleFields
The fields of a rule an editor sets.
When a rule applies.
2 fields
What sets a rule off.
3 fields
Every search and category page.
A category page.
3 fields
The id of a category node, such as wohnen/sofas: the merchant's id of a category entity.
The pages below it too. Default: only this page.
Only while no words are typed on the page, as a grid of its top positions is.
Only in this channel. Left out for every channel.
What a rule does. At least one effect.
When the rule is active, checked against the time in the request. Left out for a rule without a window.
A window in time: from from (inclusive) until until (exclusive). Either end may be open.
RuleList
The rules of a release in precedence order: the first rule is the highest.
The configuration that answered: the live release, or the draft the files make.
The catalog the products were looked up in.
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 time the states are as at.
RunProgress
How far an index run got, written by the indexer while it works, so a merchant watches it go through. A failed run keeps the last it wrote, so its report says the step it failed in.
What a running index run does now, in the order it does it.
4 values
Learning the file: its columns, its mapping and where each product ends.
Mapping every row and reading its values against the release; counts entities.
Compiling the entities and writing them to new indexes beside the live ones; counts compiled and indexed.
Swapping the new indexes in for the live ones.
Entities read and checked so far; from indexing on, all the run indexes.
Entities compiled and handed to the engine so far.
Documents the engine has indexed so far.
RunReport
What an index run did with its snapshot: how much it indexed, and every row it left out and why.
Rows read from the feed, blank lines not counted.
How the export was read and mapped; left out for OrbSearch's own JSON Lines, which need no mapping.
Entities indexed.
Engine documents written, over every index.
The engine indexes the run made live, one per entity type and locale, such as product-de.
Rows left out because something in them is wrong; the rest of the feed was indexed.
The rejected rows grouped by what is wrong, the most common first, each with its first rows as examples.
What the import made of the attribute values: those it left out, and those whose meaning it derived.
The release files the release leaves out, derived from this run's catalog, each setting with its reason. The Query API reads them with the release while the run is live.
The next moment a sale window opens or closes, or an overlay ends. The indexes hold the prices and corrections of the run's time, so the indexer builds the same snapshot and release again then.
How the run took its release live and why; left out for a run that failed or has not gone live yet. A run that switched or only wrote settings carries the counts of the live run it followed, since its catalog is the same.
The offer changes the run's indexes hold: those received since its snapshot first arrived, applied on top of it when the run built its indexes, and every batch the indexer wrote into them while the run was live. Left out when they hold none. A run that switched or only wrote settings carries the live run's, since its indexes are the same.
SearchSettings
How every type of the release is searched.
The configuration that decided: the live release, or the draft the files make.
The catalog the derived settings come from.
A BCP 47 language tag such as de, de-CH or en. A locale falls back along its tag: de-CH to de.
In the order of types.json.
Shift
A boost or bury.
An entity named with its type, type:id, such as product:SOFA-LUND-3.
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" } }
With where: only entities of this type.
One of slight, medium or strong.
ShownFacet
A facet and how it is shown.
An attribute code, or one of category, brand, price, on_sale, availability and delivery_days, which reads the latest day of delivery.
The bounds of buckets and relative facets, in ascending order.
The order of a facet's values. Default: most results first; buckets keep their own order; grades, buttons and a select keep the order the values are listed in.
3 values
One value at most, chosen from a radio group with "Any" first, such as a delivery time whose buckets overlap.
Text shown under the facet's name and read with it, such as what a delivery time counts from. Never a tooltip.
Parts of the list under headings of their own, such as "Wood" above oak and walnut, in order. Values no heading names follow the last one.
A heading inside a facet and the values it stands above.
A search box above the values, for long lists such as brands.
The most values a list or swatch carries with the page before more says there are others: the most frequent ones, and every chosen one. Default: the limit facet_values. A select or a scale that shows every value raises it.
How the values look beyond their kind. Default: the kind's own look; a rating shows stars.
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.
A storefront display of the shop's own, by the name the shop registered it under, such as color_tiles. A storefront without it draws display, or the kind's own look, so display keeps what it means for the data.
Snapshot
A catalog as it was uploaded, named by its content.
The id of a catalog snapshot. A snapshot is named by its content and never changes.
The last time these bytes were sent. A publish or rebuild indexes the current catalog: the snapshot uploaded last that is kept and that the indexer did not reject.
When the indexer's clean-up removed its file because nothing needed it any more; its runs stay. Sending the same bytes again brings it back.
SortOption
An order a page offers.
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.
StoredRelease
A release as the control plane stores it, with when it was published. Storing does not publish it.
The id of a release. A release is named by its content and never changes.
A point in time as RFC 3339 with an offset, such as 2026-11-27T00:00:00+01:00.
When it was last published; the release published last is the one index runs compile.
On a single release: its files by name, in the canonical form the Query API wrote.
Where it stands among the releases index runs took live; left out for any other release, so the panel needs to work nothing out.
3 values
Searches read it now.
The release the live one replaced, which publishing it again, a rollback, brings back.
It is published and an index run is queued or running; it is not live yet.
SynonymList
Every language's synonyms.
The languages the channels serve, in channel order: the first is the shop's, and a shop with one needs no choice of language.
For each locale the channels serve, the dictionary it reads: its own, else the one of the nearest shorter tag, such as de for de-CH. A locale with no dictionary along its tag reads one under its own name once it has entries. A client opens the dictionary a shopper's locale reads from here, never by matching tags itself.
One dictionary per language the channels serve, then those for a language none serves yet.
ThenFields
What a rule does. At least one effect.
Chosen entities at fixed positions, counted from 1.
Takes entities out of the results. Hide beats pin.
What an effect is about.
3 fields
Moves entities up, within relevance.
A boost or bury with its named strength.
2 fields
What an effect is about.
3 fields
One of slight, medium or strong.
Moves entities down, within relevance.
A boost or bury with its named strength.
2 fields
What an effect is about.
3 fields
One of slight, medium or strong.
Sends the shopper elsewhere.
Where a redirect sends the shopper.
2 fields
A page of the shop: a category, a brand, a product or another entity. Its address follows the catalog.
1 field
An entity named with its type, type:id, such as product:SOFA-LUND-3.
Banners and teasers above, among or below the results, each with its words in every locale the release serves.
TypeSearch
How one type is searched.
The code of an entity type, such as product, category or a merchant's own store.
The type's name in the locale.
The fields a type searches, in priority order: a word found in an earlier field ranks a hit higher.
2 fields
The fields it could search beside those: the built-in text fields, then every text, identifier and option attribute, in the order of attributes.json.
A field a type can search.
Whether and from how many letters on a type's words find with a typo.
The attributes a type's words find only as written or by their start.
TypoSettings
Whether and from how many letters on a type's words find with a typo.
The fewest letters a word needs to find with one typo.
The fewest letters a word needs to find with two typos.
UnstoredSlug
A listed value or group whose slug the run made from its label, because attributes.json stores none.
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 value's or group's code.
A plain value, or a map from locale to value such as { "de": "Farbe", "en": "Color" }.
ValuesReport
What the import made of the feed's attribute values beyond reading them as their definitions say.
Values left out because they do not fit their attribute; their entity was indexed without them.
The values left out grouped by what is wrong, the most common first, each with its first values as examples.
Option values attributes.json does not list; each became a value of its own.
Values of attributes with color groups that no stage of the built-in colors could place in a group.
The values whose meaning the import derived, the most common first.
Values and groups attributes.json lists without a slug in a locale: the run made it from the label, so a new label would move the URLs that hold it. A write through the management API stores it.
The first of them, in the order of attributes.json, with the slugs the run made.
Weight
A boost or bury that weighed a hit.
A rule's id, unique per release, such as home/out-of-stock-last. It appears in traces, tests, diffs and filter chips, so it is visible to storefronts and holds no secrets.
One of resolve, rewrite, redirect, filter, hide, pin, boost, bury, sections or place.