Craft Pro provides an autogenerated GraphQL API for your content, which you can query to pull your content into separate applications, such as single-page apps (SPAs) or static site generators.

[[toc]]

{
  entries (section: "news", limit: 2, orderBy: "dateCreated DESC") {
    dateCreated @formatDateTime (format: "Y-m-d")
    title
    children {
      title
    }
    ... on news_article_Entry {
      shortDescription
      featuredImage {
        url @transform (width: 300, immediately: true)
      }
    }
  }
}

{
  "data": {
    "entries": [
      {
        "dateCreated": "2019-08-21",
        "title": "An important news item",
        "children": [],
        "shortDescription": "<p>This is how we roll these days.</p>",
        "featuredImage": [
          {
            "url": "/assets/site/_300xAUTO_crop_center-center_none/glasses.jpg"
          }
        ]
      },
      {
        "dateCreated": "2019-07-02",
        "title": "Dolorem ea eveniet alias",
        "children": [
          {
            "title": "Child entry"
          },
          {
            "title": "This is also a child entry"
          }
        ],
        "shortDescription": "Et omnis explicabo iusto eum nobis. Consequatur debitis architecto est exercitationem vitae velit repellendus. Aut consequatur maiores error ducimus ea et. Rem ipsa asperiores eius quas et omnis. Veniam quasi qui repellendus dignissimos et necessitatibus. Aut a illo tempora.",
        "featuredImage": []
      }
    ]
  }
}

Before you begin, make sure that you are running Craft 3.3 or later, and you’ve got the Pro edition installed.

The first step to adding a GraphQL API to your project is to set up a public endpoint for it.

To do that, create a URL rule from config/routes.php that points to the graphql/api controller action. For example, the following URL rule would cause /api requests to route to the GraphQL API:

return [
    'api' => 'graphql/api',
    // ...
];

You can verify that your endpoint is configured correctly, try sending a {ping} query to it.

curl -H "Content-Type: application/graphql" -d '{ping}' http://my-project.test/api

(Replace http://my-project.test/api with the actual URL to your endpoint.)

If that comes back with the following JSON response, then your GraphQL API is up and running!

{"data":{"ping":"pong"}}

Once you’ve created a GraphQL API endpoint, you need to tell Craft which content should be available from it. (No content is available by default.) You do that by defining a Schema.

Craft has two types of schemas:

• The Public Schema defines which content should be available publicly.
• You can also define multiple private schemas, which each have their own secret Access Token.

You can manage your schemas from the Control Panel, at GraphQL → Schemas. In addition to defining the scope of each schema, you can also give them expiration dates, or disable them.

::: tip When performing a GraphQL API request, the schema will be determined automatically based on the token that is supplied (if any). See below to learn how to do that. :::

The easiest way to start exploring your GraphQL API is with the built-in GraphiQL IDE, which is available in the Control Panel from GraphQL → Explore.

Additional GraphQL IDEs are available as well:

• Insomnia
• GraphQL Playground
• GraphQL Playground online

::: tip When you are initially exploring the API, make sure that Dev Mode is enabled so the IDE can be informed about the entire schema available to it. :::

The GraphQL API can be queried in three ways:

• Using a GET request, with the GraphQL query defined by a query parameter:

  curl \
    --data-urlencode "query={ping}" \
    http://craft32.test/api
  # or
  curl http://craft32.test/api?query=%7Bping%7D

• Using a POST request with an application/json content type, with the GraphQL query defined by a query key:

  curl \
    -H "Content-Type: application/json" \
    -d '{"query":"{ping}"}' \
    http://my-project.test/api

• Using a POST request with an application/graphql content type, with the GraphQL query defined by the raw request body:

  curl \
    -H "Content-Type: application/graphql" \
    -d '{ping}' \
    http://my-project.test/api

If you need to specify any variables along with your query, then you must send request as a POST request with an application/json content type, and include a variables key in the JSON body alongside query.

curl \
  -H "Content-Type: application/json" \
  -d '{
        "query": "query($id:[Int]) { entries(id: $id) { id, title } }",
        "variables": { "id": [1, 2, 3] }
      }' \
  http://my-project.test/api

The Public Schema will be used by default. To query against a different schema, pass its Access Token using an Authorization header.

curl \
  -H "Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/graphql" \
  -d '{entries{id}}' \
  http://my-project.test/api

All query results are cached, so that repeated queries can yield results faster. The GraphQL result cache does not have a sophisticated ruleset on invalidating the cache - if the site's content or structure changes, the entire cache is invalidated.

Craft has GraphQL result caching enabled by default, but it can be disabled with the enableGraphQlCaching config setting.

A defined type exists for each specific interface implementation. For example, if a “News” section has “Article” and “Editorial” entry types, in addition to the EntryInterface interface type, two additional types would be defined the GraphQL schema, if the token used allows it: news_article_Entry and news_editorial_Entry types.

::: tip The actual API features will depend on what your schema allows. :::

This query is used to query for assets.

This query is used to query for a single asset.

This query is used to query for entries.

This query is used to query for a single entry.

This query is used to query for global sets.

This query is used to query for a single global set.

This query is used to query for users.

This query is used to query for a single user.

This query is used to query for tags.

This query is used to query for a single tag.

This query is used to query for categories.

This query is used to query for a single category.

Directives are not regulated by permissions and they affect how the returned data is displayed.

This directive allows for formatting any date to the desired format. It can be applied to all fields, but changes anything only when applied to a DateTime field.

This directive is used to return a URL for an asset tranform. It accepts the same arguments you would use for a transform in Craft and adds the immediately argument.

Parses the passed field value as Markdown.

Craft defines several interfaces to be implemented by the different GraphQL types.

This is the interface implemented by all assets.

This is the interface implemented by all entries.

This is the interface implemented by all global sets.

This is the interface implemented by all matrix blocks.

This is the interface implemented by all users.

This is the interface implemented by all categories.

This is the interface implemented by all tags.