Preview a ranking change
const url = 'http://localhost:8080/v1/admin/channels/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/ranking/preview';const options = { method: 'POST', headers: { Authorization: 'Bearer <token>', 'X-Antares-Actor': '<X-Antares-Actor>', 'Content-Type': 'application/json' }, body: '{"weights":{"relevance":1,"margin":1,"stock":1,"conversion":1,"sales":1,"novelty":1},"queries":["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/admin/channels/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/ranking/preview \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --header 'X-Antares-Actor: <X-Antares-Actor>' \ --data '{ "weights": { "relevance": 1, "margin": 1, "stock": 1, "conversion": 1, "sales": 1, "novelty": 1 }, "queries": [ "example" ] }'Runs a set of queries twice — once with the stored weights, once with the proposed ones — and returns the top five of each side by side so the merchant sees what the slider actually did. Nothing is persisted.
queries defaults to the channel’s ten highest-volume queries of the last seven days, which is the set a weight change is most likely to damage. Previews always run in the channel’s default price context: staff must never be able to read a negotiated price through a preview. Role: viewer.
Authorizations
Abschnitt betitelt „Authorizations“Parameters
Abschnitt betitelt „Parameters“Path Parameters
Abschnitt betitelt „Path Parameters“Channel UUID — never the human-readable channelKey. Validated against the actor’s organization first.
Request Bodyrequired
Abschnitt betitelt „Request Bodyrequired“object
The six ranking signals, each 0–100. They are relative shares, not percentages: they do not have to sum to anything. For relevance searches, Typesense retrieves a bounded candidate window and the API applies all six weights in Go before pagination, which is why changing them takes effect on the next query and never needs a reindex.
object
Textual match quality. Setting it to 0 makes the result order independent of what the visitor typed and is almost never right.
The normalised margin derived from purchasePrice. Products without a purchase price score neutrally rather than last.
Availability. Pushes out-of-stock products down instead of hiding them, which keeps a searched-for article findable.
The product’s click-to-purchase rate from search, normalised across the catalogue.
Recent sales volume, normalised across the catalogue and seeded from the order backfill so a fresh tenant does not rank from a cold start.
Recency of releasedAt, decaying over 90 days.
Queries to compare. Defaults to the channel’s ten highest-volume queries of the last seven days, which is the set a weight change is most likely to damage.
Examplegenerated
{ "weights": { "relevance": 1, "margin": 1, "stock": 1, "conversion": 1, "sales": 1, "novelty": 1 }, "queries": [ "example" ]}Responses
Abschnitt betitelt „Responses“Before/after top five per query.
object
object
The current top five, with the stored weights.
A result reduced to what a preview row needs. Shaped by the same rules as /v1/search and always in the channel’s default price context: staff must not be able to read a negotiated price through a preview endpoint.
object
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.
1-based position in the list this stub belongs to.
The top five the proposed weights would produce.
A result reduced to what a preview row needs. Shaped by the same rules as /v1/search and always in the channel’s default price context: staff must not be able to read a negotiated price through a preview endpoint.
object
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.
1-based position in the list this stub belongs to.
How many of the five changed position or membership. The single number the merchant scans the list by.
Example
{ "items": [ { "before": [ { "price": { "currency": "EUR" } } ], "after": [ { "price": { "currency": "EUR" } } ] } ]}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 } ]}forbidden — authenticated, but the actor’s role does not carry the permission this route needs, or the operation is one of the three that refuse an impersonated actor (billing checkout, portal link, key rotation).
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 } ]}not_found — the addressed shop, channel, synonym, curation, index run, key or organization does not exist inside the caller’s organization. Deliberately indistinguishable from “exists but belongs to somebody else”.
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 } ]}validation_failed — the payload failed field validation. errors[] names the offending fields.
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 } ]}