Preview GraphQL API

The read-only Preview GraphQL API lets you retrieve both unpublished (draft) and published Sitecore content, which is served from your content management instance. This API is typically used for local development and in your app's non-production (testing and staging) environments. Previewing your unpublished content is an important part of the content development lifecycle, before finalizing content and publishing to Experience Edge.

To retrieve only published content for production environments, use the Delivery GraphQL API instead.

Authorization and API access

Authorization and API access options vary depending on where you access this API.

Request body

The request body is a GraphQL query. See also query examples.

Response format

The response is a JSON object. See also query examples.

Schema and reference documentation

Access the GraphQL schema and the API reference documentation in the GraphQL IDE.

Limitations and restrictions

Review the Preview GraphQL API limitations and restrictions.

Schema extension

The Preview GraphQL API schema mirrors the schema of the Delivery GraphQL API. The Preview GraphQL API schema is not extensible because it must remain compatible with Experience Edge.

Tokenized search index

Unlike the Delivery GraphQL API, the Preview GraphQL API endpoint uses a tokenized search index. As a result, search behavior depends on how fields are indexed:

  • The CONTAINS operator can return multiple results based on tokenized field values.
  • The EQ (Equals) operator may also return multiple results for tokenized text fields, even when an exact match is expected.

To ensure exact matching with EQ on the Preview endpoint, use the SearchQueryFieldMapping feature to map tokenized fields to non-tokenized computed fields. See also the related support article KB1003665.

For information about the behavior of search operators, see Search operator behavior.

Disabling authentication for media items

By default, viewing media items in the Preview endpoint requires authentication. However, you can disable that requirement for a specified period, by using the Media.UrlSignatureExpirationTimeout setting in the sitecore.config file, in the following format:

xml
<!-- MEDIA URL SIGNATURE EXPIRATION TIMEOUT
            The time after which the media URL signature expires.
            The value must be in the format "hh:mm:ss".
            Default value: 00:10:00 (10 minutes)
      -->
        <setting name="Media.UrlSignatureExpirationTimeout" value="00:10:00"/>

If the value is set to 0, authentication is enforced at all times.

After you update the setting, remember to use a patch file to apply the configuration change.

If you have suggestions for improving this article, let us know!