Get one published widget configuration version
const url = 'http://localhost:8080/v1/admin/channels/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/widget-config/versions/1';const options = { method: 'GET', headers: {Authorization: 'Bearer <token>', 'X-Antares-Actor': '<X-Antares-Actor>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url http://localhost:8080/v1/admin/channels/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/widget-config/versions/1 \ --header 'Authorization: Bearer <token>' \ --header 'X-Antares-Actor: <X-Antares-Actor>'The exact payload that was published, for the history screen’s diff view. 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.
Published widget configuration version number, counting from 1.
Responses
Abschnitt betitelt „Responses“The stored payload of that version.
object
The complete published designer surface. Everything the widget renders comes from here; the widget itself ships no merchant-specific defaults.
object
Which shell the widget mounts. overlay opens a full-screen dialog over the shop. dropdown renders under the merchant’s own input and leaves the page visible. command is a centred command palette opened by a hotkey. page replaces the shop’s own search results page in place and paginates with real URLs. A widget build that does not know the configured layout mounts nothing and leaves the shop’s native search working.
Per-layout settings. Only the block matching the configured layout is read; the others are kept so switching layouts in the designer does not lose their settings.
object
object
What opens the overlay. focus opens as soon as the merchant’s input is focused, which is the fastest path for a visitor who is already searching. tap waits for a deliberate pointer or keyboard activation. hotkey opens only on the configured key combination.
Key combination that opens the overlay, in the form mod+k where mod is Command on macOS and Control elsewhere. Read only when openOn is hotkey.
Maximum width of the dialog on wide viewports. Default 1120.
Render the facet rail inside the dialog. Default true.
Clicking the scrim closes the dialog. Default true.
object
Products listed in the dropdown before “show all results”. Default 8.
input matches the merchant’s search field exactly. container widens to the field’s nearest positioned ancestor, which is what a narrow header field needs to show product images at all.
Render the “show all results” footer row. Default true.
object
Key combination that opens the palette. Default mod+k.
Rows in the palette before it scrolls. Default 10.
Show recent searches when the palette opens empty. Default true.
Render the “press ⌘K” hint next to the merchant’s input. Default true.
object
CSS selector of the element on the shop’s search results page that the widget replaces. The widget mounts nothing if it does not match, leaving the shop’s own results in place.
Products per page. Default 24.
Render the facet rail as a sidebar rather than a collapsible bar above the grid. Default true.
pages renders numbered links with real ?p= URLs, which is the only mode a crawler and the browser’s back button both handle. load_more appends on click. infinite appends on scroll.
The widget bundle version this configuration was authored against. Part of the /v1/widget/config ETag, so publishing a configuration invalidates the cache.
The published version number this payload was served from. Absent in a draft. Reported back on events so an A/B result can be attributed to a concrete publish.
When this version was published. Absent in a draft.
Formatting locale for prices, numbers and dates. It does not select the interface strings — those always come from translations, so a merchant can ship any wording they like in any of these locales.
Baseline the theme tokens are merged onto. system follows the visitor’s prefers-color-scheme. contrast is the WCAG AAA baseline. custom starts from the light baseline and expects themeTokens to define the palette.
The designer’s typed token vocabulary. Every entry compiles into the CSS custom property named in its description, and unset entries fall back to the preset. Colour values accept any CSS colour notation; length values accept any CSS length.
object
--antares-color-background — the widget surface behind everything.
--antares-color-surface — raised areas such as the facet rail.
--antares-color-text — primary body text.
--antares-color-muted — secondary text, counts and hints.
--antares-color-primary — the single accent: buttons, focus rings, active chips.
--antares-color-primary-contrast — text drawn on top of the accent.
--antares-color-border — hairlines and input outlines.
--antares-color-backdrop — the scrim behind the overlay and command layouts.
--antares-color-sale — the sale badge and the strike-through price.
--antares-color-success — the in-stock indicator.
--antares-color-danger — the out-of-stock indicator and error text.
--antares-font — the body font stack.
--antares-font-heading — headings; falls back to font when unset.
--antares-font-size — the base size the type scale is derived from.
--antares-radius — the corner radius of cards and the shell.
--antares-spacing — the base spacing unit of the layout grid.
--antares-shadow — the elevation shadow of the shell.
--antares-z-index — stacking order of the widget’s shell. Raise it when a shop’s sticky header paints over the overlay.
The compiled CSS custom properties the widget sets on its shadow host, for example {"--antares-color-primary": "#3157d5"}. Publishing materialises themePreset and themeTokens into this map; the widget applies it verbatim and needs no knowledge of the designer’s vocabulary. Keys that do not match --antares-[a-z0-9-]+ are ignored by the widget.
object
Merchant CSS injected into the widget’s shadow root after the layout’s own sheet. Parsed by a CSP-safe parser at publish time: @import, url() to a foreign origin, expression() and anything that can issue a network request are rejected with widget_config_invalid. Available on Pro and above; sending it on a lower plan is 402 plan_feature_unavailable.
Every string the widget can paint. All keys are required: a missing key is a blank button in a shopper’s face, so publishing an incomplete set is 422 widget_config_invalid rather than a runtime fallback to English.
object
Accessible name of the search input.
Placeholder inside the search input.
Shown when a query returned nothing and no rescue was possible.
Status text while a request is in flight, announced to screen readers.
Shown when the API failed and the shop’s native search takes over.
Accessible name of the close control.
Heading above the full result list.
Heading above the instant suggestions.
Label of the “show all results” action.
Heading of the facet rail.
Label of the apply-filters action.
Label of the reset-filters action.
Label of the lower bound of the price range facet.
Label of the upper bound of the price range facet.
Label for stock status in_stock.
Label for stock status low.
Label for stock status out.
Label of the sale badge.
Label of the new badge.
Label of the topseller badge.
Label of the tier_prices badge and the heading of the quantity ladder.
Variant count line. {count} is substituted.
Heading above the popular searches.
Heading above the curated shortcuts.
Heading above the visitor’s recent searches.
Heading above the query suggestions.
Result count line. {count} is substituted.
Label of the add-to-cart action.
Label of the load-more action.
Feature switches. Every one defaults to the value documented below, so an older configuration keeps working when a new switch is added.
object
Query /v1/instant while the visitor types. Off means results appear only on submit. Default true.
Render an add-to-cart control on each result. Requires the storefront to expose a cart endpoint the loader can call. Default false.
Render the facet rail at all. Default true.
Offer the sort presets from the ranking configuration. Default true.
Show spelling corrections above the results. Default true.
Show semantically related products when the lexical pass found fewer than three matches, labelled as suggestions. Requires hybrid search on the plan. Default true.
Keep the visitor’s last queries in localStorage and offer them on an empty input. Default true.
Offer the channel’s most searched queries on an empty input. Default true.
Offer the merchant’s curated shortcuts on an empty input. Default true.
Offer matching categories alongside product suggestions. Default true.
Offer matching manufacturers alongside product suggestions. Default true.
Show the variant count on results that have variants. Default true.
Show the tier_prices badge and the quantity ladder on results that carry one. Default true.
Report interaction events to /v1/events. Turning it off blinds every panel metric for this channel and is meant for merchants whose consent banner has not been answered yet. Default true.
The facets the widget requests and renders, in display order. An empty array hides the facet rail entirely.
One facet in the rail, in the order the array lists it.
object
The facet field. properties.* addresses one of the shop’s own property axes by its normalised name.
Merchant override for the displayed name. Without it the API’s translated label is used.
Render this facet. Default true. A disabled facet is still not requested.
Render collapsed on first paint. Default false.
How the facet is painted. list is checkboxes, chips is inline toggles, slider is a two-handle numeric range (the only valid choice for price), swatch renders the value as a colour or image swatch, rating renders stars.
How many values to show before “show more”. Ignored for slider. Default 8.
Running experiments. A session is bucketed once, by a stable hash of its sessionId, and the bucket is reported back on every event as variant. The unlisted remainder of traffic gets the base configuration. An empty or absent array means no experiment is running.
object
Stable identifier reported back on every event as variant. Reusing an id for a different experiment mixes two experiments’ numbers and must not be done.
Merchant-facing name shown in the panel. Never reaches the widget.
Share of sessions bucketed into this variant. The sum across all variants must not exceed 100; the remainder receives the base configuration.
What this variant changes about the base configuration. Anything absent is inherited. Deliberately a subset: an experiment that changes the translations or the feature set is a different configuration, not a variant of one.
object
Which shell the widget mounts. overlay opens a full-screen dialog over the shop. dropdown renders under the merchant’s own input and leaves the page visible. command is a centred command palette opened by a hotkey. page replaces the shop’s own search results page in place and paginates with real URLs. A widget build that does not know the configured layout mounts nothing and leaves the shop’s native search working.
Per-layout settings. Only the block matching the configured layout is read; the others are kept so switching layouts in the designer does not lose their settings.
object
object
What opens the overlay. focus opens as soon as the merchant’s input is focused, which is the fastest path for a visitor who is already searching. tap waits for a deliberate pointer or keyboard activation. hotkey opens only on the configured key combination.
Key combination that opens the overlay, in the form mod+k where mod is Command on macOS and Control elsewhere. Read only when openOn is hotkey.
Maximum width of the dialog on wide viewports. Default 1120.
Render the facet rail inside the dialog. Default true.
Clicking the scrim closes the dialog. Default true.
object
Products listed in the dropdown before “show all results”. Default 8.
input matches the merchant’s search field exactly. container widens to the field’s nearest positioned ancestor, which is what a narrow header field needs to show product images at all.
Render the “show all results” footer row. Default true.
object
Key combination that opens the palette. Default mod+k.
Rows in the palette before it scrolls. Default 10.
Show recent searches when the palette opens empty. Default true.
Render the “press ⌘K” hint next to the merchant’s input. Default true.
object
CSS selector of the element on the shop’s search results page that the widget replaces. The widget mounts nothing if it does not match, leaving the shop’s own results in place.
Products per page. Default 24.
Render the facet rail as a sidebar rather than a collapsible bar above the grid. Default true.
pages renders numbered links with real ?p= URLs, which is the only mode a crawler and the browser’s back button both handle. load_more appends on click. infinite appends on scroll.
Baseline the theme tokens are merged onto. system follows the visitor’s prefers-color-scheme. contrast is the WCAG AAA baseline. custom starts from the light baseline and expects themeTokens to define the palette.
The designer’s typed token vocabulary. Every entry compiles into the CSS custom property named in its description, and unset entries fall back to the preset. Colour values accept any CSS colour notation; length values accept any CSS length.
object
--antares-color-background — the widget surface behind everything.
--antares-color-surface — raised areas such as the facet rail.
--antares-color-text — primary body text.
--antares-color-muted — secondary text, counts and hints.
--antares-color-primary — the single accent: buttons, focus rings, active chips.
--antares-color-primary-contrast — text drawn on top of the accent.
--antares-color-border — hairlines and input outlines.
--antares-color-backdrop — the scrim behind the overlay and command layouts.
--antares-color-sale — the sale badge and the strike-through price.
--antares-color-success — the in-stock indicator.
--antares-color-danger — the out-of-stock indicator and error text.
--antares-font — the body font stack.
--antares-font-heading — headings; falls back to font when unset.
--antares-font-size — the base size the type scale is derived from.
--antares-radius — the corner radius of cards and the shell.
--antares-spacing — the base spacing unit of the layout grid.
--antares-shadow — the elevation shadow of the shell.
--antares-z-index — stacking order of the widget’s shell. Raise it when a shop’s sticky header paints over the overlay.
One facet in the rail, in the order the array lists it.
object
The facet field. properties.* addresses one of the shop’s own property axes by its normalised name.
Merchant override for the displayed name. Without it the API’s translated label is used.
Render this facet. Default true. A disabled facet is still not requested.
Render collapsed on first paint. Default false.
How the facet is painted. list is checkboxes, chips is inline toggles, slider is a two-handle numeric range (the only valid choice for price), swatch renders the value as a colour or image swatch, rating renders stars.
How many values to show before “show more”. Ignored for slider. Default 8.
Example
{ "config": { "layout": "overlay", "layoutOptions": { "overlay": { "openOn": "focus" }, "dropdown": { "widthMode": "input" }, "page": { "paginationMode": "pages" } }, "locale": "de-DE", "themePreset": "light", "facets": [ { "display": "list" } ], "abVariants": [ { "overrides": { "layout": "overlay", "layoutOptions": { "overlay": { "openOn": "focus" }, "dropdown": { "widthMode": "input" }, "page": { "paginationMode": "pages" } }, "themePreset": "light", "facets": [ { "display": "list" } ] } } ] }}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 } ]}widget_config_version_not_found — no such published version for this channel.
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.
invalid_widget_config — the stored configuration for this channel cannot be decoded. Data corruption on our side, not a caller error. Or internal_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 } ]}