GraphQL Overview

In addition to its REST and Local APIs, Payload ships with a fully featured and extensible GraphQL API.

By default, the GraphQL API is exposed via /api/graphql, but you can customize this URL via specifying your routes within the main Payload Config.

The labels you provide for your Collections and Globals are used to name the GraphQL types that are created to correspond to your config. Special characters and spaces are removed.

GraphQL Options

At the top of your Payload Config you can define all the options to manage GraphQL.

Option	Description
`mutations`	Any custom Mutations to be added in addition to what Payload provides. More
`queries`	Any custom Queries to be added in addition to what Payload provides. More
`maxComplexity`	A number used to set the maximum allowed complexity allowed by requests More
`disablePlaygroundInProduction`	A boolean that if false will enable the GraphQL playground, defaults to true. More
`disable`	A boolean that if true will disable the GraphQL entirely, defaults to false.
`validationRules`	A function that takes the ExecutionArgs and returns an array of ValidationRules.

Collections

Everything that can be done to a Collection via the REST or Local API can be done with GraphQL (outside of uploading files, which is REST-only). If you have a collection as follows:

1import type { CollectionConfig } from 'payload'
2
3export const PublicUser: CollectionConfig = {
4  slug: 'public-users',
5  auth: true, // Auth is enabled
6  fields: [
7    ...
8  ],
9}

Payload will automatically open up the following queries:

Query Name	Operation
`PublicUser`	`findByID`
`PublicUsers`	`find`
`countPublicUsers`	`count`
`mePublicUser`	`me` auth operation

And the following mutations:

Query Name	Operation
`createPublicUser`	`create`
`updatePublicUser`	`update`
`deletePublicUser`	`delete`
`forgotPasswordPublicUser`	`forgotPassword` auth operation
`resetPasswordPublicUser`	`resetPassword` auth operation
`unlockPublicUser`	`unlock` auth operation
`verifyPublicUser`	`verify` auth operation
`loginPublicUser`	`login` auth operation
`logoutPublicUser`	`logout` auth operation
`refreshTokenPublicUser`	`refresh` auth operation

Globals

Globals are also fully supported. For example:

1import type { GlobalConfig } from 'payload';
2
3const Header: GlobalConfig = {
4  slug: 'header',
5  fields: [
6    ...
7  ],
8}

Payload will open the following query:

Query Name	Operation
`Header`	`findOne`

And the following mutation:

Query Name	Operation
`updateHeader`	`update`

User preferences for the Admin Panel are also available to GraphQL the same way as other collection schemas are generated. To query preferences you must supply an authorization token in the header and only the preferences of that user will be accessible.

Payload will open the following query:

Query Name	Operation
`Preference`	`findOne`

And the following mutations:

Query Name	Operation
`updatePreference`	`update`
`deletePreference`	`delete`

GraphQL Playground

GraphQL Playground is enabled by default for development purposes, but disabled in production. You can enable it in production by passing graphQL.disablePlaygroundInProduction a false setting in the main Payload Config.

You can even log in using the login[collection-singular-label-here] mutation to use the Playground as an authenticated user.

Custom Validation Rules

You can add custom validation rules to your GraphQL API by defining a validationRules function in your Payload Config. This function should return an array of Validation Rules that will be applied to all incoming queries and mutations.

1import { GraphQL } from '@payloadcms/graphql/types'
2import { buildConfig } from 'payload'
3
4export default buildConfig({
// ...
graphQL: {
  validationRules: (args) => [
    NoProductionIntrospection
  ]
},
// ...
12})
13
14const NoProductionIntrospection: GraphQL.ValidationRule = (context) => ({
Field(node) {
  if (process.env.NODE_ENV === 'production') {
    if (node.name.value === '__schema' || node.name.value === '__type') {
      context.reportError(
        new GraphQL.GraphQLError(
          'GraphQL introspection is not allowed, but the query contained __schema or __type',
          { nodes: [node] }
        )
      );
    }
  }
}
27})

Query complexity limits

Payload comes with a built-in query complexity limiter to prevent bad people from trying to slow down your server by running massive queries. To learn more, click here.

Field complexity

You can define custom complexity for relationship, upload and join type fields. This is useful if you want to assign a higher complexity to a field that is more expensive to resolve. This can help prevent users from running queries that are too complex.

1const fieldWithComplexity = {
name: 'authors',
type: 'relationship',
relationship: 'authors',
graphQL: {
  complexity: 100, 
}
8}

See what others are building with Payload.

"Payload has transformed the way our clients manage content. It's an indispensable tool for any modern agency."

Deploy your entire stack in one place with Payload Cloud.

Microsoft chose Payload to tell the world about AI.