GraphQL tools for getting started with Contentful

New to using GraphQL with Contentful? Here's a handy cheatsheet to get you started, highlighting the most commonly used GraphQL tools and features.
December 20, 2022


If you’re new to using GraphQL with Contentful, we have put together a handy cheat sheet to get you started. In this guide, we highlight the most commonly used GraphQL tools and features. 

First things first, GraphQL is a query language that provides developers with the flexibility to retrieve data from APIs. In particular, the GraphQL Content API supports our Content Delivery API (CDA) and our Content Preview API (CPA). 

A GraphQL schema comes with every Contentful space, which is based on the query language’s content types. You can find out more information on endpoint filtering capabilities, schema generation process, and error codes in the reference guide.

There are some fantastic educational resources available, which you can check out below:

With all this in mind, let’s dive into the need-to-knows.

GraphQL tools and access

There are many tools that allow you to use GraphQL with Contentful. Here's a selection to get you started.

1. Basic Contentful GraphQL API

Typically when you are using the GraphQL API in your code, you will use the following URL to request content:[SPACE_ID]. 

The content you receive from this URL is the same as the content you would receive when using the Contentful Delivery API. 

2. GraphiQL tool

You also may use GraphiQL, an IDE tool by going to this URL:[SPACE_ID]/explore?access_token=[CDA_API_TOKEN]. 

This tool allows you to build GraphQL queries easily in the browser. 


You can access your space ID and Content Delivery API token in your Contentful space settings.

3. GraphQL Playground App

Within Contentful, we also offer the GraphQL Playground App. It is similar to GraphiQL in that it allows you to build GraphQL queries, but the main benefit is that it allows you to do so within the Contentful web app and also automatically will connect to your Contentful space so there is no need to insert your API token or Contentful space ID.

Playground App

Contentful GraphQL queries

Keep in mind that in order to access draft content, you'll need to use your Contentful Preview API. Here are some of the most used Contentful GraphQL queries you’ll want to know.

Single entry query

Here’s how to retrieve a single entry.

Which returns the following:

Collection query

This is how you can retrieve multiple entries.

Which returns the following:

Preview query

Finally, use the following code, should you wish to include draft entries.

Reference queries

For single reference queries; query a reference field that only accepts a specific entry type.

Which returns the following:

When a reference field is created in a content type, there is the option to limit what types of entries can be referenced. The screenshot below is an example of what the validation would look like for a field where this query should be used. 


Various reference types

Query a reference field that accepts multiple entry types. 

In the reference field validation, if multiple entry types are selected as shown below, in your query, you must specify which entry type you would like to return. 


For queries that have many references, it’s possible that you might hit query complexity limits. To avoid this, you can add limits to your queries to lower the complexity cost.

GraphQL basics

Reference queries

You can reuse queries by passing down variables. In this example, this query might be used on a blog to show all of the posts for a certain author. Instead of writing a new query for every author, the same query can be used as the author’s name changes. 

Step 1: Define variable

Step 2: Use variable in query

Named queries

You can provide unique query names to organize multiple queries.


You can provide alternative names, or aliases, for query results to avoid conflicts when fetching from the same field or collection.


These are reusable field groups that can be shared between multiple fields and queries.

Which returns the following:


You can include or skip a field in a query based on a variable value. 

Step 1: Create variable

Step 2: Use variable with directives


Here’s an example of how to request data using GraphQL with JavaScript.


You can create dynamic queries and add type safety.

Step 1: Define variables

Step 2: Use variable in a query

Step 3: Use variable in an API request

You can check out our blog for a detailed walkthrough of how to utilize variables in GraphQL in requests.

Wrapping up

Visit our developer portal for even more guides, tips and tricks. The portal also houses developer blog posts, videos, and tutorials.

Check out our Developer Showcase to see what developers have built with Contentful and to submit your own projects.

As always, feel free to contact us on Slack or Twitter to let us know how we can better support your awesome builds.

Start building

Use your favorite tech stack, language, and framework of your choice.

About the authors

Don't miss the latest

Get updates in your inbox
Discover new insights from the Contentful developer community each month.
add-circle arrow-right remove style-two-pin-marker subtract-circle remove