Search collections

A search collection is an index the platform builds from an app's search.json. Every tenant has its own copy, so a query only ever sees the tenant it is sent for. A storefront reaches it from its server, never from the browser. See The BFF pattern.

The collections

Under the default search_untranslated: hide, a product without its own text in a language other than the tenant's main language has no document in that language. See Languages and locale codes.

Category, manufacturer and page collections are being rolled out (as of 2026-10). Until then, category names reach a product search through the categories and category_labels fields of products.

GET /v1/search/collections lists what a tenant actually has, including collections declared by apps you installed. GET /v1/search/collections/{collection} returns one collection's definition: its fields, its defaults and its document count. An unknown collection answers 404.

What a products document carries

Querying a collection

curl -X POST https://api.revenexx.com/v1/search/query \
  -H "X-Revenexx-Tenant: <TENANT_SLUG>" \
  -H "X-Revenexx-Api-Key: rvxk_..." \
  -H "X-Revenexx-Locale: de-DE" \
  -H "X-Revenexx-Channel: b2b" \
  -H "Content-Type: application/json" \
  -d '{
    "collection": "products",
    "view": "search",
    "q": "e27 led",
    "filters": {
      "categories": ["led", "e27"],
      "manufacturer": ["LEDVANCE"],
      "attrs.lichtstrom": { "min": 400, "max": 1100 }
    },
    "sort": "relevance",
    "page": 1,
    "per_page": 24
  }'

POST /v1/search/multi_search stays available for clients that build the search parameters themselves.

Headers

Without X-Revenexx-Locale the query searches across every locale.

One collection per language

Collections that keep one index per write key are being rolled out (as of 2026-10). For those, the header picks the index: the exact code, else its language (de-AT → de), else an index of the same language (de → de-DE), else the tenant's default locale. Without the header, or with a malformed one, the default locale answers instead of every locale. The response header X-Revenexx-Locale-Served and the body's locale name the write key that answered, so a page can tell that de-AT was served from de. Words are stemmed for the index's language. Existing collections switch over tenant by tenant; until then the header works as described above and X-Revenexx-Locale-Served is absent.

Body

Relevance settings such as the fields searched, their weights, typo tolerance or facet fields are not accepted in the body. They belong to the view and are maintained per tenant. Unknown keys are ignored.

Filters

A filter on a field that does not exist or is not filterable, or a value containing a backtick, is dropped and named in ignored_filters. A sort on a field that is not sortable is dropped and named in ignored_sort. Neither fails the query.

Some filters are always applied and cannot be lifted by a caller: the tenant, enabled is true where the collection has that field, the channel when X-Revenexx-Channel is sent, and the locale when X-Revenexx-Locale is sent.

Views

Without tenant-specific settings, a view behaves like this:

Fields the collection does not have are skipped, and a view name without built-in settings behaves like search. A tenant can tune each view in Cockpit, and the storefront call does not change.

The response

{
  "query_id": "q_8f2c1a",
  "found": 154,
  "page": 1,
  "per_page": 24,
  "search_time_ms": 6,
  "locale": "de-DE",
  "hits": [
    { "document": { "id": "…", "sku": "LV-E27-806", "name": "LED-Lampe E27 806 lm" }, "highlight": { }, "text_match": 578 }
  ],
  "facets": [
    { "field": "manufacturer", "values": [ { "value": "LEDVANCE", "count": 412 } ] },
    { "field": "attrs.lichtstrom", "values": [ { "value": "806", "count": 37 } ], "stats": { "min": 250, "max": 1521 } }
  ],
  "actions": [ { "type": "redirect", "url": "/c/buegeln" } ],
  "ignored_filters": [],
  "ignored_sort": null
}

Errors

See Errors for the error envelope.

Suggestions as you type

POST /v1/search/suggest answers a search box with a few hits from several collections in one call. It takes the same headers as a query.

{ "q": "e27", "collections": ["products", "categories"], "per_page": 5 }

The response carries query_id, locale, actions and one entry per collection in groups, each with collection, found and hits shaped like a query's hits. Each collection uses its suggest view. A collection that fails drops out of groups and the rest still answer.

Reporting what buyers do

Send POST /v1/search/events from your server when a buyer acts on a result, so the tenant's search analytics can show which queries lead somewhere. It takes the same headers as a query, and the locale comes from X-Revenexx-Locale.

It answers 202 with { "accepted": true }. Both endpoints take POST only.

Where to go next

• Search — the storefront composables and blocks on top of these endpoints.
• search.json reference — declaring a collection for your own app.
• Languages and locale codes — which locale a document is stored under.
• Channels — the codes X-Revenexx-Channel takes.