AdScaled Shop API

Read-only public API of the AdScaled Shop marketplace: search products, read product and shop details.

AdScaled Shop (https://e-shop.adscaled.media) is a Czech online marketplace where independent shops and makers sell electronics, fashion, home goods, sport equipment, beauty products, books, toys and garden supplies. This API is the same one the website uses. The operations documented here are public, read-only and need no authentication.

Money is always an integer number of hellers (1/100 of a Czech koruna, CZK): price: 19900 means 199 Kč. Image paths such as /api/images/<file>.webp are relative to the server URL. inStock tells whether a listing is shown as in stock; whether an item can really be ordered is confirmed only in the checkout of the website.

Buying, reservations, reviews and questions need a personal account with a verified e-mail and are done by the person in a browser on the website (cross-site requests and requests without a browser Origin are refused for every write). Send people to the product URL on the website instead of trying to order for them.

Rate limits: all /api paths share 300 requests per 60 seconds per client IP (policy flood). Responses carry the IETF RateLimit-Policy and RateLimit headers (draft-ietf-httpapi-ratelimit-headers); a 429 response also carries Retry-After in seconds. Every error response (4xx and 5xx) has the same JSON shape, the Error schema: { "error": { "code", "message" } }, where code is a stable machine-readable string.

Versioning: the path carries the major version (/api/v1/). Backwards-compatible additions (new fields, operations or optional parameters) keep v1; a breaking change gets a new path (/api/v2/). A deprecated operation is marked deprecated: true, answers with Deprecation (RFC 9745) and Sunset (RFC 8594) headers and stays available for at least 90 days after the deprecation is announced. The same operations without the version segment (/api/catalog and so on) are what the website itself calls; they behave identically and stay available, but integrations should use /api/v1/.

OpenAPI 3.1 specification: https://e-shop.adscaled.media/api/openapi.json
API catalog (RFC 9727): https://e-shop.adscaled.media/.well-known/api-catalog
Base URL: https://e-shop.adscaled.media
Website: https://e-shop.adscaled.media/en/ (guide for agents: https://e-shop.adscaled.media/llms.txt)

Endpoints

GET /api/v1/health (`getHealth`)

Check API availability. Returns ok: true when the server is running, whether e-mail delivery works and whether card payments are enabled.

Example:

curl 'https://e-shop.adscaled.media/api/v1/health'

Responses:

200: The API is running.
403: A browser request from another website (its Origin is not the shop itself). Server-side clients send no Origin and are not affected.
429: Rate limit exceeded. Wait Retry-After seconds.
500: Unexpected server error. Retry later.

GET /api/v1/checkout-options (`getCheckoutOptions`)

List shipping and payment options. Shipping methods with prices, payment methods with fees (card only when enabled) and the per-shop free shipping threshold, all in hellers.

Example:

curl 'https://e-shop.adscaled.media/api/v1/checkout-options'

Responses:

200: Current checkout options.
403: A browser request from another website (its Origin is not the shop itself). Server-side clients send no Origin and are not affected.
429: Rate limit exceeded. Wait Retry-After seconds.
500: Unexpected server error. Retry later.

GET /api/v1/catalog (`searchCatalog`)

Search and filter products. Full-text search (every word must match the product name, category, shop or description) with filters, sorting and pagination. When nothing matches, didYouMean may suggest a corrected query.

Parameter	In	Required	Type and constraints	Description
`q`	query	no	string, max length 80	Search words, e.g. `ceramic mug`. Czech product names match best.
`category`	query	no	string, one of `elektronika`, `moda`, `domacnost`, `sport`, `krasa`, `knihy`, `hracky`, `zahrada`	Category id.
`shop`	query	no	string, max length 80	Shop slug, e.g. `adscaled-merch`.
`sort`	query	no	string, one of `recommended`, `newest`, `price_asc`, `price_desc`, `rating`, `discount`, default `recommended`	Sort order.
`page`	query	no	integer, min 1, max 1000, default `1`	Page number.
`size`	query	no	integer, min 1, max 48, default `24`	Products per page.
`min`	query	no	number, min 0	Minimum price in CZK (whole koruna, not hellers).
`max`	query	no	number, min 0	Maximum price in CZK (whole koruna, not hellers).
`sale`	query	no	string, one of `1`	`1` = only discounted products.
`rating`	query	no	integer, min 1, max 5	Minimum average rating.
`stock`	query	no	string, one of `1`	`1` = only products shown as in stock.

Example:

curl 'https://e-shop.adscaled.media/api/v1/catalog?q=hrnek&sort=price_asc'

Responses:

200: One page of matching products.
403: A browser request from another website (its Origin is not the shop itself). Server-side clients send no Origin and are not affected.
429: Rate limit exceeded. Wait Retry-After seconds.
500: Unexpected server error. Retry later.

GET /api/v1/search/suggest (`suggestSearch`)

Autocomplete a search query. Up to 6 products, 3 shops and the matching category ids for a query of at least 2 characters, plus didYouMean for typos.

Parameter	In	Required	Type and constraints	Description
`q`	query	yes	string, max length 80	Partial search text.

Example:

curl 'https://e-shop.adscaled.media/api/v1/search/suggest?q=konev'

Responses:

200: Suggestions (empty lists for queries shorter than 2 characters).
403: A browser request from another website (its Origin is not the shop itself). Server-side clients send no Origin and are not affected.
429: Rate limit exceeded. Wait Retry-After seconds.
500: Unexpected server error. Retry later.

GET /api/v1/products (`getProductsByIds`)

Get product cards by id. Product cards for a comma-separated list of ids, in the given order; unknown or hidden ids are skipped.

Parameter	In	Required	Type and constraints	Description
`ids`	query	yes	string	Up to 60 product ids, e.g. `12,7,31`.

Example:

curl 'https://e-shop.adscaled.media/api/v1/products?ids=1,2'

Responses:

200: Product cards.
403: A browser request from another website (its Origin is not the shop itself). Server-side clients send no Origin and are not affected.
429: Rate limit exceeded. Wait Retry-After seconds.
500: Unexpected server error. Retry later.

GET /api/v1/products/{id} (`getProduct`)

Get product details. Full product with description, specifications and photos, reviews with a rating summary, answered questions, price history (lowest price in the last 30 days), related products and more products of the same shop. The website URL of a product is /en/product/{id}/{slug} (other languages: see llms.txt).

Parameter	In	Required	Type and constraints	Description
`id`	path	yes	integer, min 1	Product id.

Example:

curl 'https://e-shop.adscaled.media/api/v1/products/1'

Responses:

200: The product.
403: A browser request from another website (its Origin is not the shop itself). Server-side clients send no Origin and are not affected.
404: No public product or shop with this id or slug.
429: Rate limit exceeded. Wait Retry-After seconds.
500: Unexpected server error. Retry later.

GET /api/v1/compare (`compareProducts`)

Compare products. Product details including specifications for up to 4 products, for a side-by-side comparison.

Parameter	In	Required	Type and constraints	Description
`ids`	query	yes	string	Up to 4 product ids.

Example:

curl 'https://e-shop.adscaled.media/api/v1/compare?ids=1,2'

Responses:

200: Products to compare.
403: A browser request from another website (its Origin is not the shop itself). Server-side clients send no Origin and are not affected.
429: Rate limit exceeded. Wait Retry-After seconds.
500: Unexpected server error. Retry later.

GET /api/v1/shops (`listShops`)

List shops. All public shops with city, number of products and average rating.

Example:

curl 'https://e-shop.adscaled.media/api/v1/shops'

Responses:

200: Shops.
403: A browser request from another website (its Origin is not the shop itself). Server-side clients send no Origin and are not affected.
429: Rate limit exceeded. Wait Retry-After seconds.
500: Unexpected server error. Retry later.

GET /api/v1/shops/{slug} (`getShop`)

Get shop details. Shop profile with description and contact e-mail, plus reviews of its products. Its products: searchCatalog with shop={slug}.

Parameter	In	Required	Type and constraints	Description
`slug`	path	yes	string, max length 80	Shop slug.

Example:

curl 'https://e-shop.adscaled.media/api/v1/shops/adscaled-merch'

Responses:

200: The shop.
403: A browser request from another website (its Origin is not the shop itself). Server-side clients send no Origin and are not affected.
404: No public product or shop with this id or slug.
429: Rate limit exceeded. Wait Retry-After seconds.
500: Unexpected server error. Retry later.

Rate limits

Every /api response carries RateLimit-Policy and RateLimit headers (draft-ietf-httpapi-ratelimit-headers). All documented endpoints share the flood policy: 300 requests per 60 seconds per client IP (sliding window). Write endpoints used by the website add their own policies to the same headers.

Example: RateLimit-Policy: "flood";q=300;w=60 and RateLimit: "flood";r=297;t=58 (q quota, w window in seconds, r remaining, t seconds until a slot frees up). A 429 response adds Retry-After in seconds; wait at least that long.

Errors

Every non-2xx response uses one JSON shape (Error in the OpenAPI components): { "error": { "code": "not_found", "message": "not_found" } }. Branch on code, not on message. Codes of the documented operations: not_found (404), forbidden_origin (403, browser request from another website), rate_limited (429), server_error (500).

Versioning and deprecation

Current version: v1 (OpenAPI info.version 1.0.0). Base path: https://e-shop.adscaled.media/api/v1/.
Backwards-compatible changes (new response fields, new operations, new optional parameters) are added to v1 without notice; clients must ignore unknown fields.
Breaking changes (removed or renamed fields, changed meaning or types) are only released under a new path such as /api/v2/; v1 keeps working alongside it.
Before an operation or version is removed it is marked deprecated: true in this document and its responses carry the Deprecation header (RFC 9745) and the Sunset header (RFC 8594) with the removal date; it stays available for at least 90 days after the deprecation is announced.
The unversioned paths (/api/catalog, /api/products/{id} and so on) are the same handlers that the website uses; they are not deprecated, but new integrations should use /api/v1/.

Authentication

None for the documented endpoints. Requests from browsers are accepted only from the shop's own origin (CORS); server-side clients without an Origin header can read. Accounts, orders, reservations, reviews and seller tools are not part of the public API.

AdScaled Shop API

Endpoints

GET /api/v1/health (getHealth)

GET /api/v1/checkout-options (getCheckoutOptions)

GET /api/v1/catalog (searchCatalog)

GET /api/v1/search/suggest (suggestSearch)

GET /api/v1/products (getProductsByIds)

GET /api/v1/products/{id} (getProduct)

GET /api/v1/compare (compareProducts)

GET /api/v1/shops (listShops)

GET /api/v1/shops/{slug} (getShop)

Rate limits

Errors

Versioning and deprecation

Authentication

GET /api/v1/health (`getHealth`)

GET /api/v1/checkout-options (`getCheckoutOptions`)

GET /api/v1/catalog (`searchCatalog`)

GET /api/v1/search/suggest (`suggestSearch`)

GET /api/v1/products (`getProductsByIds`)

GET /api/v1/products/{id} (`getProduct`)

GET /api/v1/compare (`compareProducts`)

GET /api/v1/shops (`listShops`)

GET /api/v1/shops/{slug} (`getShop`)