Search products
const url = 'http://localhost:8080/v1/search';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"q":"example","sessionId":"example","currency":"EUR","priceContextToken":"example","page":1,"perPage":24,"sort":"relevance","filters":{"manufacturer":["example"],"categories":["example"],"price":{"min":1,"max":1},"inStock":true},"facets":["example"]}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url http://localhost:8080/v1/search \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "q": "example", "sessionId": "example", "currency": "EUR", "priceContextToken": "example", "page": 1, "perPage": 24, "sort": "relevance", "filters": { "manufacturer": [ "example" ], "categories": [ "example" ], "price": { "min": 1, "max": 1 }, "inStock": true }, "facets": [ "example" ] }'Full search for one channel, shaped for direct rendering. The response contains only the price context the request proved entitlement to; every other context, every other currency and every margin input stay inside the API.
Authorizations
Abschnitt betitelt „Authorizations“Parameters
Abschnitt betitelt „Parameters“Header Parameters
Abschnitt betitelt „Header Parameters“Browser-set origin. Checked against the channel’s allowedOrigins; a mismatch is 403 origin_not_allowed.
Request Bodyrequired
Abschnitt betitelt „Request Bodyrequired“object
The raw query as typed. The API normalises it; the widget must not.
First-party session identifier minted by the widget and kept in sessionStorage. Contains no PII and is not stable across browser sessions; it exists so session-level metrics such as click-through rate can be computed at all.
One of the currencies assigned to the channel. Defaults to the channel’s default currency. A currency the channel does not assign is 422 validation_failed; a product without a price in an assigned currency is dropped from that currency’s results rather than served at zero.
Signed price-context token minted by the storefront for the logged-in customer: apc1.<payload-base64url>.<signature-base64url>, HMAC-SHA-256 over "antares-price-context-v1" || 0x00 || <payload segment>. Carries no PII — its ctx claim is a one-way hash of merchant configuration and identifies a price list, not a person. Without it the default context is served, which is the common case and not an error.
relevance uses the channel’s ranking weights. The price sorts use the resolved price context’s sort field, so a B2B customer sorts by the prices they actually pay.
Neutral filter fields plus properties.<normalized-name> for the shop’s own property axes. Any other key is 422 invalid_filter.
object
Inclusive bounds in the request’s currency, expressed in the resolved price context.
object
Facets to compute for this query, by field name.
Responses
Abschnitt betitelt „Responses“UI-ready search response.
object
Identifies this result set. Every event the widget later reports must carry it.
Explicit allow-list. Response shaping is built from the verified price context as an include-list, so purchasePrice, every other context’s prices and every ranking input fail closed and can never appear here.
object
SEO path relative to the channel domain.
object
Pre-composed srcset over the thumbnails the connector supplied.
The one price this caller is entitled to, already rounded and formatted for the channel’s locale.
object
Strike-through reference price. Absent when the product is not on sale.
Upper-case ISO 4217 code.
gross formatted for the channel’s locale and currency, so the widget never formats money itself.
Rounded percentage below list. Absent when list is absent.
object
The quantity ladder of the resolved price context in the request’s currency, ascending by qty. Present only when the product carries one; this is the data behind the tier_prices badge and the tierPrices translation key. Ladders of other contexts are never included.
One rung of a quantity ladder, already formatted for display.
object
Lowest quantity at which this price applies.
gross formatted for the channel’s locale and currency.
object
Thresholded server-side from the indexed quantity, so the exact stock level of a product is never exposed to a competitor scraping the widget.
The translated label for status, taken from the widget configuration.
Display badges, already decided by the API so the widget does no logic.
object
Number of variants behind this hit. 0 for a product without variants.
Names of the variant axes, for example ["Spannung", "Farbe"].
Short-lived signed proof binding this product to the returned query and channel. An event without it cannot be attributed and is refused.
Returned only for secret-key debug requests.
object
Translated, merchant-facing name of the facet.
object
Whether this value is part of the caller’s current filter selection.
object
Lowest value present in the unfiltered result set.
Highest value present in the unfiltered result set.
The lower bound the caller currently has applied, if any.
The upper bound the caller currently has applied, if any.
object
Spelling corrections, best first. Empty when the query looks correct.
object
Server-side duration, excluding network time.
keyword = lexical only. hybrid = lexical and vector fused. rescue = the lexical pass returned fewer than three matches and a semantic pass answered instead; the widget labels these results as suggestions.
The context that actually answered: default, or the 35-character fingerprint. Echoed so a support engineer can tell which price list produced these numbers.
applied — a token was verified and its context answered. default — no token was supplied, or the token named default. unknown_context — a token verified but names a context the channel registry does not know, which is the normal state between a connector deploying a new price rule and the reindex landing; the default prices answered instead, which can only ever be higher, never another group’s price. This field is the only way to tell “B2B prices are live” from “B2B prices silently fell back”.
Example
{ "hits": [ { "price": { "currency": "EUR" }, "stock": { "status": "in_stock" }, "badges": [ "sale" ] } ], "facets": [ { "type": "terms" } ], "meta": { "mode": "keyword", "priceContext": "default", "priceContextStatus": "applied" }}contract_validation_failed — the OpenAPI request validator rejected the request before the handler ran — or invalid_request when the body is unreadable or is not valid JSON for the declared operation.
RFC 9457 problem details. type is always https://api.antares.commergy.de/problems/{code} and is built in exactly one place. type, code and title are stable and never localised; only detail is localised, and only where the registry marks the audience as merchant.
object
Absolute problem type URI. Stable identifier, never localised.
Stable English summary of the problem type.
The HTTP status code, repeated in the body.
Human-readable explanation of this occurrence. The only localised field; may be German or English depending on Accept-Language.
The request path this occurrence relates to.
The registry code, for example price_context_token_expired. This is what a client branches on; never branch on title or detail.
Present only for per-item validation failures, above all ingest batches.
object
Dotted path of the offending field inside the request body, for example prices.CHF.gross.
What is wrong with it, in English.
0-based index into the request’s products array. Present only for ingest batches, and the only way to map an error back to a product without echoing it.
Examplegenerated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "code": "example", "errors": [ { "field": "example", "message": "example", "productIndex": 1 } ]}unauthorized — the credential is missing, malformed, unknown or revoked. For /v1/admin this also covers an actor JWS that fails signature, exp or kid verification, and a kid that no key in the panel’s JWKS matches.
RFC 9457 problem details. type is always https://api.antares.commergy.de/problems/{code} and is built in exactly one place. type, code and title are stable and never localised; only detail is localised, and only where the registry marks the audience as merchant.
object
Absolute problem type URI. Stable identifier, never localised.
Stable English summary of the problem type.
The HTTP status code, repeated in the body.
Human-readable explanation of this occurrence. The only localised field; may be German or English depending on Accept-Language.
The request path this occurrence relates to.
The registry code, for example price_context_token_expired. This is what a client branches on; never branch on title or detail.
Present only for per-item validation failures, above all ingest batches.
object
Dotted path of the offending field inside the request body, for example prices.CHF.gross.
What is wrong with it, in English.
0-based index into the request’s products array. Present only for ingest batches, and the only way to map an error back to a product without echoing it.
Examplegenerated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "code": "example", "errors": [ { "field": "example", "message": "example", "productIndex": 1 } ]}quota_exceeded — a hard cap was reached (sandbox plan, or a trial past its grace window); paid plans get the soft cap instead, which is 200 plus X-Antares-Quota: exceeded. Or plan_feature_unavailable — the organization’s resolved entitlements do not include the requested feature.
RFC 9457 problem details. type is always https://api.antares.commergy.de/problems/{code} and is built in exactly one place. type, code and title are stable and never localised; only detail is localised, and only where the registry marks the audience as merchant.
object
Absolute problem type URI. Stable identifier, never localised.
Stable English summary of the problem type.
The HTTP status code, repeated in the body.
Human-readable explanation of this occurrence. The only localised field; may be German or English depending on Accept-Language.
The request path this occurrence relates to.
The registry code, for example price_context_token_expired. This is what a client branches on; never branch on title or detail.
Present only for per-item validation failures, above all ingest batches.
object
Dotted path of the offending field inside the request body, for example prices.CHF.gross.
What is wrong with it, in English.
0-based index into the request’s products array. Present only for ingest batches, and the only way to map an error back to a product without echoing it.
Examplegenerated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "code": "example", "errors": [ { "field": "example", "message": "example", "productIndex": 1 } ]}origin_not_allowed — the Origin header is not in the channel’s allowedOrigins.
RFC 9457 problem details. type is always https://api.antares.commergy.de/problems/{code} and is built in exactly one place. type, code and title are stable and never localised; only detail is localised, and only where the registry marks the audience as merchant.
object
Absolute problem type URI. Stable identifier, never localised.
Stable English summary of the problem type.
The HTTP status code, repeated in the body.
Human-readable explanation of this occurrence. The only localised field; may be German or English depending on Accept-Language.
The request path this occurrence relates to.
The registry code, for example price_context_token_expired. This is what a client branches on; never branch on title or detail.
Present only for per-item validation failures, above all ingest batches.
object
Dotted path of the offending field inside the request body, for example prices.CHF.gross.
What is wrong with it, in English.
0-based index into the request’s products array. Present only for ingest batches, and the only way to map an error back to a product without echoing it.
Examplegenerated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "code": "example", "errors": [ { "field": "example", "message": "example", "productIndex": 1 } ]}price_context_not_configured — a price-context token was supplied but the shop has no signing-secret generation yet, which can only happen before connect completed.
RFC 9457 problem details. type is always https://api.antares.commergy.de/problems/{code} and is built in exactly one place. type, code and title are stable and never localised; only detail is localised, and only where the registry marks the audience as merchant.
object
Absolute problem type URI. Stable identifier, never localised.
Stable English summary of the problem type.
The HTTP status code, repeated in the body.
Human-readable explanation of this occurrence. The only localised field; may be German or English depending on Accept-Language.
The request path this occurrence relates to.
The registry code, for example price_context_token_expired. This is what a client branches on; never branch on title or detail.
Present only for per-item validation failures, above all ingest batches.
object
Dotted path of the offending field inside the request body, for example prices.CHF.gross.
What is wrong with it, in English.
0-based index into the request’s products array. Present only for ingest batches, and the only way to map an error back to a product without echoing it.
Examplegenerated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "code": "example", "errors": [ { "field": "example", "message": "example", "productIndex": 1 } ]}request_too_large — the body exceeds this endpoint’s byte limit. Also returned for chunked bodies without Content-Length once the limit is passed mid-stream.
RFC 9457 problem details. type is always https://api.antares.commergy.de/problems/{code} and is built in exactly one place. type, code and title are stable and never localised; only detail is localised, and only where the registry marks the audience as merchant.
object
Absolute problem type URI. Stable identifier, never localised.
Stable English summary of the problem type.
The HTTP status code, repeated in the body.
Human-readable explanation of this occurrence. The only localised field; may be German or English depending on Accept-Language.
The request path this occurrence relates to.
The registry code, for example price_context_token_expired. This is what a client branches on; never branch on title or detail.
Present only for per-item validation failures, above all ingest batches.
object
Dotted path of the offending field inside the request body, for example prices.CHF.gross.
What is wrong with it, in English.
0-based index into the request’s products array. Present only for ingest batches, and the only way to map an error back to a product without echoing it.
Examplegenerated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "code": "example", "errors": [ { "field": "example", "message": "example", "productIndex": 1 } ]}One of validation_failed (q too long, malformed sessionId, page/perPage out of range, malformed event batch), invalid_filter (a filters key that is neither a known neutral field nor properties.*), invalid_event_context (the signed tracking token is invalid, expired, bound to another query, product or channel, or its instant dwell time was not reached), price_context_token_invalid, price_context_token_expired or price_context_channel_mismatch.
A missing token, a token for a context a product does not carry, and a token for a context the channel registry does not know are not errors: they answer 200 with the default context and a meta.priceContextStatus that says so.
RFC 9457 problem details. type is always https://api.antares.commergy.de/problems/{code} and is built in exactly one place. type, code and title are stable and never localised; only detail is localised, and only where the registry marks the audience as merchant.
object
Absolute problem type URI. Stable identifier, never localised.
Stable English summary of the problem type.
The HTTP status code, repeated in the body.
Human-readable explanation of this occurrence. The only localised field; may be German or English depending on Accept-Language.
The request path this occurrence relates to.
The registry code, for example price_context_token_expired. This is what a client branches on; never branch on title or detail.
Present only for per-item validation failures, above all ingest batches.
object
Dotted path of the offending field inside the request body, for example prices.CHF.gross.
What is wrong with it, in English.
0-based index into the request’s products array. Present only for ingest batches, and the only way to map an error back to a product without echoing it.
Examplegenerated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "code": "example", "errors": [ { "field": "example", "message": "example", "productIndex": 1 } ]}rate_limit_exceeded — the per-key or per-IP token bucket is exhausted.
RFC 9457 problem details. type is always https://api.antares.commergy.de/problems/{code} and is built in exactly one place. type, code and title are stable and never localised; only detail is localised, and only where the registry marks the audience as merchant.
object
Absolute problem type URI. Stable identifier, never localised.
Stable English summary of the problem type.
The HTTP status code, repeated in the body.
Human-readable explanation of this occurrence. The only localised field; may be German or English depending on Accept-Language.
The request path this occurrence relates to.
The registry code, for example price_context_token_expired. This is what a client branches on; never branch on title or detail.
Present only for per-item validation failures, above all ingest batches.
object
Dotted path of the offending field inside the request body, for example prices.CHF.gross.
What is wrong with it, in English.
0-based index into the request’s products array. Present only for ingest batches, and the only way to map an error back to a product without echoing it.
Examplegenerated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "code": "example", "errors": [ { "field": "example", "message": "example", "productIndex": 1 } ]}Headers
Abschnitt betitelt „Headers“Seconds until the bucket refills enough for one request.
internal_error — unhandled failure. detail is always generic; the cause goes to the log with a correlation id.
RFC 9457 problem details. type is always https://api.antares.commergy.de/problems/{code} and is built in exactly one place. type, code and title are stable and never localised; only detail is localised, and only where the registry marks the audience as merchant.
object
Absolute problem type URI. Stable identifier, never localised.
Stable English summary of the problem type.
The HTTP status code, repeated in the body.
Human-readable explanation of this occurrence. The only localised field; may be German or English depending on Accept-Language.
The request path this occurrence relates to.
The registry code, for example price_context_token_expired. This is what a client branches on; never branch on title or detail.
Present only for per-item validation failures, above all ingest batches.
object
Dotted path of the offending field inside the request body, for example prices.CHF.gross.
What is wrong with it, in English.
0-based index into the request’s products array. Present only for ingest batches, and the only way to map an error back to a product without echoing it.
Examplegenerated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "code": "example", "errors": [ { "field": "example", "message": "example", "productIndex": 1 } ]}search_unavailable — Typesense failed the query. The widget falls back to the shop’s native search rather than showing an error.
RFC 9457 problem details. type is always https://api.antares.commergy.de/problems/{code} and is built in exactly one place. type, code and title are stable and never localised; only detail is localised, and only where the registry marks the audience as merchant.
object
Absolute problem type URI. Stable identifier, never localised.
Stable English summary of the problem type.
The HTTP status code, repeated in the body.
Human-readable explanation of this occurrence. The only localised field; may be German or English depending on Accept-Language.
The request path this occurrence relates to.
The registry code, for example price_context_token_expired. This is what a client branches on; never branch on title or detail.
Present only for per-item validation failures, above all ingest batches.
object
Dotted path of the offending field inside the request body, for example prices.CHF.gross.
What is wrong with it, in English.
0-based index into the request’s products array. Present only for ingest batches, and the only way to map an error back to a product without echoing it.
Examplegenerated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "code": "example", "errors": [ { "field": "example", "message": "example", "productIndex": 1 } ]}