Headless Content Delivery in Sitecore Content Hub Using GraphQL: A Developer’s Guide

Sitecore Content Hub provides a headless content delivery capability via GraphQL, enabling developers to query content and digital assets for any application or channel. In this post, we'll explore how GraphQL-based headless delivery works in Content Hub, explain the Preview vs Delivery GraphQL APIs (and when to use each), walk through generating API keys for access, and demonstrate how to use Sitecore’s GraphQL IDE (playground). Finally, we'll look at some sample GraphQL query patterns for retrieving assets (like images and metadata) and content items.

GraphQL in Sitecore Content Hub: An Overview

Sitecore Content Hub exposes content and media through GraphQL endpoints to facilitate headless delivery to any channel. GraphQL is a query language for APIs that allows clients to request exactly the data they need, making it ideal for headless scenarios. Unlike traditional REST, GraphQL uses a single endpoint and a formal query structure, letting clients combine multiple data requests into one call and get back a tailored JSON response. This unified approach is especially powerful in Content Hub, since it manages both structured content and media assets – GraphQL provides a single, flexible interface to query both content and digital assets.

In the context of Content Hub’s headless delivery:

You will send GraphQL queries (usually via HTTP POST) to Content Hub's GraphQL endpoints.
The endpoints expose a strongly-typed schema of your content model, meaning you can query content types, fields, and relationships (including media relationships) in a single request.
Read-only access: The Content Hub GraphQL APIs currently support queries only (no mutations), so you fetch content but cannot modify it via GraphQL. Content authoring and management are done through other APIs or the Content Hub UI, while GraphQL is optimized for content delivery.

Preview vs. Delivery APIs: What’s the Difference?

Sitecore Content Hub actually provides two GraphQL endpoints for content delivery: a Preview API and a Delivery API. Both share the same GraphQL schema (so the query syntax and types are identical), but they serve different purposes and have important differences in behavior and usage.

Preview API: The Preview API endpoint exposes a preview of your content – including all content items, even those not yet approved or published (e.g. draft or in-review content). This is ideal for testing and validating content in non-production environments. For example, a staging site or a content preview tool can use the Preview API to fetch content that authors have created or edited, before it goes live. Important: The Preview API is not optimized for high traffic or public production use. It’s intended for internal use cases like previewing content changes; in fact, Sitecore notes that the Preview API lacks the capacity for large volumes of traffic, so you should avoid using it in a live app or website

Delivery API: The Delivery API is the GraphQL endpoint intended for production content delivery. It only returns approved and published content – i.e. content that has been published to the "delivery" platform or Experience Edge network. This ensures that your live applications consume only the latest published content. The Delivery API is built for performance, with a globally distributed infrastructure and caching (via a CDN) to handle high traffic with low latency. In short, you use the Delivery API for any consumer-facing app, website, or service that needs to fetch Content Hub content at scale. The schema is identical to Preview, so you can develop queries against Preview and later switch to Delivery for production usage without rewriting queries.

The following diagram shows the API locations in the global architecture:

To summarize the use cases: use Preview API in authoring or testing scenarios (e.g. a content preview feature, integration testing, etc.), and use Delivery API in all production scenarios to serve content to end-users. The separation also allows using different API keys and security contexts for preview vs. live content.

Generating API Keys for GraphQL Access

Both the Preview and Delivery GraphQL endpoints are secured and require an API key for access. You’ll need to generate an API key in your Sitecore Content Hub instance for each type of API (one for preview, one for delivery) and include that key in your GraphQL requests. Sitecore provides an interface to create and manage these keys.

Step-by-Step: Creating a Preview/Delivery API Key in Content Hub:

1. Open the Manage page: Log in to your Content Hub instance with a user that has administrative privileges (you must be a superuser to manage API keys). In the top navigation menu, click the Manage icon (gear/cog icon).

2. Navigate to API Keys: On the Manage page, find and click API keys. This will open the API keys management screen, which lists existing keys (if any) and allows creation of new keys.

3. Add a new API key:

4. Click on the "+ API key" button. In the dialog that appears, provide a name for your new key (for example, "GraphQL Preview API" or "GraphQL Delivery API")

Choose the key type (scope): Select the type/purpose of the key you need:

Delivery – for the Delivery API (production, published content)
Preview – for the Preview API (staging/test, includes unpublished content)

5. Create and copy the key:

Click Create to generate the key. The new API key value will be displayed once – copy it and store it securely now. You will not be able to retrieve this key again after closing the dialog (for security reasons, Content Hub will only show it on creation)

Repeat the above if you need both a preview key and a delivery key (you can create multiple keys). For example, you might generate one Preview API key for developers to use in testing, and one Delivery API key that your production app will use to fetch live content.

Using the API Key: Once you have the key, any GraphQL request to Content Hub’s endpoints must include it in the headers. The header name is X-GQL-Token and the value is your API key. In the GraphQL IDE (which we'll discuss next), you can set this in the HTTP HEADERS tab. In custom code (e.g., a fetch/Ajax call), you would include a header like X-GQL-Token: {your-key} in the HTTP request. Without a valid key, the GraphQL endpoints will reject your requests.

Using the GraphQL IDE (Playground)

Sitecore provides a built-in GraphQL IDE (interactive playground) for both the Preview and Delivery endpoints. This is essentially a hosted version of GraphQL Playground where you can write queries, execute them against your Content Hub content, and see the results – very useful for developers building and testing queries before implementing them in code. The GraphQL IDE also provides quality-of-life features like syntax highlighting, autocompletion, documentation lookup, and query history to speed up development.

Accessing the GraphQL IDE:

Preview API IDE: Usually accessible at a URL under your specific Content Hub instance. For example, if your Content Hub instance URL is https://your-sitecorecontenthub-instaceurl, the preview IDE might be at:

https://your-sitecorecontenthub-instaceurl/api/graphql/preview/ide
(If you are using Sitecore Content Hub One via Sitecore Cloud Portal, the preview IDE is available at the content API domain, e.g. https://your-sitecorecontenthub-instaceurl/api/content/v1/preview/graphql/ide/. In either case, you will be hitting the Content Hub directly for preview.)

Delivery API IDE: Accessible via Sitecore’s global Edge domain. The base URL for the Delivery IDE is:

 https://edge.sitecorecloud.io/api/graphql/ide
(This is the Experience Edge GraphQL playground for delivery. (Under the hood, your API key tells the Edge endpoint which tenant/instance’s content to query.)

To launch the IDE, simply navigate to the appropriate URL in your web browser. You should see the GraphQL Playground interface. Before running any queries, enter your API key for authentication: click on the HTTP HEADERS section and add a JSON object with your key. For example:

{
"X-GQL-Token": "YOUR-GENERATED-API-KEY" }

Replace the value with the Preview or Delivery API key you created earlier. This header will be sent with your GraphQL requests in the IDE. After adding the key, you can start writing queries in the editor pane.

IDE Features: The GraphQL IDE's right-hand side contains a DOCS tab and a SCHEMA tab which are extremely helpful. The DOCS tab is interactive documentation that lets you browse the schema (types, fields, and allowed query structure) – essentially self-documenting your content model. You can click through content types, see what fields are available, and what arguments queries accept. The SCHEMA tab shows the underlying schema definition. You also have autocompletion in the query editor, so you can type a type name or field name and the IDE will suggest possible completions, making it easier to construct queries.

Tip: You can use the history and bookmark features of the playground to save queries you frequently run. This is useful when iterating on queries. Also, the "Prettify" button can auto-format your query for readability.

Sample GraphQL Query Patterns

Now, let's look at some practical examples of GraphQL queries in Sitecore Content Hub. We’ll cover queries for both content items (structured content) and media assets (digital assets like images), since Content Hub manages both. These examples assume you have the relevant content in your Content Hub instance and that you’ve authenticated (with an API key) either in the GraphQL IDE or via an API client.

Quering Content Items by Type: Let’s use a real example based on a Blog content type defined in Content Hub. This content type has fields like blog_Title, blog_Quote, and blog_Body. The following query retrieves blog content items:

In our case, this query returned 4 blog items, which matches exactly what we see when filtering by content type Blog on the All work tab in the Sitecore Content Hub Content page. This validates that the GraphQL query reflects the actual published data available in the system.

Filter By File Type: Retrieve JPG assets

Search Assets Containing a Keyword in File Name: Find assets containing a specific keyword in the file name.

Filter by Creation Date: Retrieve assets based on their creation date.

Combine Multiple Filters (e.g., .jpg + date): For example, filter assets that are JPGs and were created on a specific date.

These sample queries leverage simple and direct scalar properties like fileName and createdOn, making them efficient and schema-safe for real-world projects.

Conclusion

In a nutshell, Sitecore Content Hub’s GraphQL endpoints empower developers to deliver content headlessly with great flexibility. Using the Preview and Delivery APIs appropriately allows you to support content-authoring previews and high-performance content delivery for live applications, respectively. We saw how to generate API keys and authenticate, and how to use the GraphQL Playground to write and test queries. With GraphQL, you can pull exactly the content and asset data you need – whether it's a list of blog posts with metadata or an image with its URL – all in a single round trip. This makes integrating Content Hub content into websites, mobile apps, or any other digital channels much more efficient and developer-friendly.

Leveraging the sample queries and patterns above, you can start building your own queries to suit your application’s needs. Happy querying! 🎉