Crystallize logo

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.

Overview

The Discovery API is a powerful, flexible API for querying and retrieving content from Crystallize. It is a read-only API, distributed and optimized for read performance, designed to power storefronts with product information and marketing content. From a single GraphQL endpoint you can browse, search, filter, facet, sort, paginate, rank, and personalize results across your entire catalogue.

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/discovery

All queries in this Discovery documentation are 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, the Discovery API is a public, open endpoint that requires no authentication. If you configure a static authentication token for your tenant, every request must include it in the X-Crystallize-Static-Auth-Token header; requests without a valid token are rejected.

Send your queries as POST requests to the base URL. Open the same URL in a browser (a GET request) to launch the built-in GraphiQL IDE, where you can explore the tenant-specific schema and run queries interactively.

Optionally, pass the X-Discovery-Feature-Flags header (a comma-separated list) to opt into experimental capabilities.

warning

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.

Capabilities

The Discovery API brings together everything you need to query your catalogue from a single endpoint:

  • Filtering — narrow results with rich operators (equals, in, contains, regex, phrase, numeric and date ranges, exists) and geo filters, combined with AND/OR logic.
  • Faceting — compute aggregations over string, number, and date fields to power navigation and filter UIs.
  • Sorting — order results ascending or descending on indexed fields, or by relevance score.
  • Pagination — page through results with limit and skip (offset), or, preferably, with cursor tokens (after/before) for stable, high-performance paging.
  • Ranking & relevance — full-text matching with BM25 relevance, plus rankBy to blend weighted signals (relevance, recency, field boosts, in-stock boosts) into a custom score.
  • Personalization — bias results toward a visitor's preferences with per-request taste vectors (context.userTaste).
  • Similarity / vector search — surface items that are "more like this" using vector similarity to an anchor item (nearestTo).
  • Typo tolerance — optional fuzzy matching keeps search resilient to misspellings.

Query types

The Discovery API exposes a few top-level query types. Each has its own dedicated page with in-depth guidance and examples:

  • Browse — shape-first listing of items belonging to a single Shape, ideal for category and listing pages.
  • Search — full-text, relevance-based search across all items or a subset of Shapes, with ranking, personalization, and similarity.
  • Autocomplete — typeahead suggestions from partial matches on the name field.
  • Topics — retrieve the topic hierarchy for taxonomy-based navigation, and the items within a topic.

Price & commerce queries

For commerce use cases, the API resolves price-list-aware pricing alongside your results. priceRange returns the minimum and maximum price across a result set, priceFor resolves the best price for a given price variant and markets (with optional quantity-tier matching), and bestPriceList reveals which price list produced that best price. See the Discovery Queries page for details.

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).

tip

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.

Watch the Discovery API livestream

;