Discovery API documentation
The Discovery API is the API which is designed to power your storefront with product information and marketing content. It is a read only API that is distributed and designed for read performance. You can browse, search, filter, facet and sort your data from Crystallize via the Discovery API.
It is designed to replace the catalogue API and search API (to be deprecated) as one API for fetching data from your Crystallize tenant. Discovery is a semantic API which means that the API signature follows the structure of your shapes and the components on your shape.
Base URL
You can access the Discovery API from the following URL. Remember to replace the tenant-name with your tenant identifier.
https://api.crystallize.com/tenant-name/discoveryhttps://api.crystallize.com/tenant-name/discoveryAll queries in this Discovery documentation is connected to the demo site Furnitut which is using a best practice setup for content modeling. You can check out our open-source Next.js commerce storefront accelerator which is built on top of this tenant.
API Access
By default, this is an open endpoint. However if you set up restricted access for your Catalogue API, you would need to provide the static token or access tokens as required.
Protect your Discovery API in production
The Discovery API is designed for flexible data access, but exposing it without proper protection in a production environment can pose security risks. Always secure your API with authentication in production.
Sorting and Pagination
Score variations are expected and can arise from corpus updates (e.g. BM25 recalculation) or internal segment merges. Additionally, when multiple documents receive the same score, the engine does not guarantee which one is returned first — tied results may appear in any order. Without an explicit secondary sort, this can lead to random-looking result order and even duplication or omission when paginating. To ensure a stable and reproducible order, always include a deterministic sort field alongside the score (e.g. sort by score first, then by a unique field like itemId).
Performance and pagination
When paginating search results, using `skip` is discouraged. Offset-based pagination forces the engine to scan and discard rows up to the offset on every request, which becomes increasingly slow as you move deeper in the result set.
A paginationToken (a.k.a. cursor-based pagination) solves these issues. Instead of saying “give me page N”, it says “continue after this exact last document”. It prevents random reordering, avoids duplication between pages, and scales correctly on large datasets.
In short:
Use paginationToken (combined with after). for correctness and performance; avoid skip for real-world pagination.