Key format: A 32-character string matching: ^(PROD|DEV_|ROOT)[A-Za-z0-9]{28}$
Prefixes: PROD (production key), DEV_ (individual developer), ROOT (system key with no limits). Learn more
ExamplePRODPGrFxpGEtrOZfuWhnoJohUYBXuOE
slugstringRequired
Exampleexample_slug
localestringOptional
Locale code (e.g. "cs", "en"). Returns translated read model for the given locale with fallback.
Examplecs
propertiesstringOptional
Add extra on demand properties separated by semicolon.
Supported values:
Property
Description
orderStatistics
Extra statistics data like totalQuantitySold and count of orders in states.
galleryItemsCount
Count of public images in product detail.
ExampleorderStatistics;galleryItemsCount
Response schema
1 status code documented
200SuccessFull product detail from the read model.
idstringRequired
Product code identifier.
Exampleburger
codestringRequired
Product code identifier (same as id).
Exampleburger
namestringRequired
Localized product name.
ExampleCheese Burger
slugstringRequired
URL-friendly product identifier.
Examplecheese-burger
shortDescriptionstringRequired
Short HTML description for listings. Returned as sanitized HTML string.
longDescriptionstringRequired
Full HTML description for product detail page. Returned as sanitized HTML string.
mainImageUrlstringOptional
URL of the main product image (original blob). Legacy field — kept for backward compatibility with clients written before issue #80. New integrations should prefer mainImage.originalUrl (identical value) alongside mainImage.lqip / mainImage.thumbUrl / mainImage.cardUrl / mainImage.heroUrl / mainImage.zoomUrl for progressive rendering.
Examplehttps://storage.xhp.cz/...
mainImageobject | nullRequired
One of 2:
Variant 1
Full main-image payload with all pre-rendered variants (issue #80).
Rendering contract for the FE: always paint lqip immediately as a CSS background, then progressively enhance with whichever sharp variant matches the intended display size — thumbUrl (≤ 128 px), cardUrl (≤ 480 px), heroUrl (≤ 1280 px), zoomUrl (≤ 2048 px). Fall back to originalUrl only for lightbox / download-as-image cases where the pre-rendered variants are insufficient.
Nullable slots vs. progressive rendering: every variant slot is present on the wire; null means scout hasn't rendered that particular size yet. The read model is rebuilt automatically the moment all four variants land, so a subsequent fetch will return the URLs — usually within seconds of a fresh upload, longer under scout backlog. Never fall back to originalUrl for a null variant in list UIs — that would defeat the whole point of pre-generating right-sized derivatives.
idstringRequired
External blob token of the source image (stable across variant regenerations). Use this to correlate frontend cache keys and re-request the payload after an update.
Examplea1b2c3d4e5f6g7h8
originalUrlstringRequired
Public CDN URL of the original upload — always present when the product has a main image.
Format: whatever the operator uploaded (typically JPEG or PNG, occasionally WebP or AVIF). Dimensions and byte size are unbounded and depend on the source; expect anywhere from 200 KB to several MB.
Use cases:
Lightbox / zoom UI that needs the highest fidelity available (fallback for zoom variant).
Downloadable "original" link.
Feeds for third parties that expect an unmodified source.
Do not use the original for above-the-fold rendering or list thumbnails — the pipeline exists precisely so those cases can bind to a pre-rendered, right-sized WebP variant instead.
Intended use: paint immediately as a CSS background-image on the wrapper element. Once one of the sharp variants (thumbUrl, cardUrl, heroUrl, zoomUrl) finishes loading, fade it in on top; the LQIP remains behind and covers any transparent pixels.
Edge case: an empty string is possible only if the source blob was unreadable when the LQIP was generated (sharp threw and no fallback was stored). Treat empty as "no LQIP available" and skip the background paint.
Intended use: row-level thumbnails in lists, autocomplete dropdowns, chat message previews, notification cards, mobile grid cells (60–120 px). At this size no other variant is worth requesting.
When null: the source image has been uploaded but the scout worker on the Contabo VPS hasn't finished rendering this variant yet. Fall back to the LQIP blur alone (with an optional "processing" overlay for cells ≥ 80 px). The read model is rebuilt automatically the moment all four variants land, so a subsequent fetch will return a non-null URL — usually within seconds for a fresh upload, longer under scout backlog.
Intended use: medium-sized product previews — product-detail sidebar (240–520 px), category grid tiles on mobile / small desktop, storefront cards, hover popovers, e-mail template thumbnails. The single most-used variant in typical e-shop UI.
When null: same story as thumbUrl — variant not yet rendered by scout. Prefer thumbUrl (if available) as a temporary substitute over the LQIP blur alone.
When null: same story as thumbUrl — variant not yet rendered by scout. If falling back, prefer cardUrl over thumbUrl when the intended display size is > ~480 px.
Intended use: lightbox / product-image zoom UI, retina 2× rendering for hero-sized cells, download-as-image feature. The largest pre-rendered variant — for anything sharper, fall back to originalUrl (unbounded, unmodified source).
When null: same story as thumbUrl — variant not yet rendered by scout. If a lightbox request comes in before zoomUrl is ready, use originalUrl as an interim fallback so the feature still works.
Intended use: row-level thumbnails in lists, autocomplete dropdowns, chat message previews, notification cards, mobile grid cells (60–120 px). At this size no other variant is worth requesting.
When null: the source image has been uploaded but the scout worker on the Contabo VPS hasn't finished rendering this variant yet. Fall back to the LQIP blur alone (with an optional "processing" overlay for cells ≥ 80 px). The read model is rebuilt automatically the moment all four variants land, so a subsequent fetch will return a non-null URL — usually within seconds for a fresh upload, longer under scout backlog.
Intended use: medium-sized product previews — product-detail sidebar (240–520 px), category grid tiles on mobile / small desktop, storefront cards, hover popovers, e-mail template thumbnails. The single most-used variant in typical e-shop UI.
When null: same story as thumbUrl — variant not yet rendered by scout. Prefer thumbUrl (if available) as a temporary substitute over the LQIP blur alone.
