obsidian/wiki/payloadcms/graphql-overview.md

title	aliases	tags	sources	created	updated
GraphQL API — Overview	graphql-api payload-graphql	payloadcms graphql api queries mutations	raw/graphql__overview.md	2026-05-15	2026-05-15

Overview

Payload ships a fully featured GraphQL API alongside wiki/payloadcms/rest-api and wiki/payloadcms/local-api APIs.

• Default endpoint: /api/graphql
• Playground: /api/graphql-playground (dev only by default)
• Route can be customized via routes in wiki/payloadcms/configuration

GraphQL Config Options

Set under graphQL in buildConfig:

Option	Default	Description
mutations	—	Additional custom mutations
queries	—	Additional custom queries
maxComplexity	—	Limit query complexity score
disablePlaygroundInProduction	true	Set false to expose playground in prod
disableIntrospectionInProduction	true	Set false to allow introspection in prod
disable	false	Entirely disable GraphQL
validationRules	—	(ExecutionArgs) => ValidationRule[]

Auto-Generated Operations

Collections

Given a collection with slug public-users and auth: true:

Queries:

Name	Operation
PublicUser	findByID
PublicUsers	find
countPublicUsers	count
mePublicUser	me

Mutations:

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

File uploads are REST-only — not available via GraphQL.

Globals

Given a global with slug header:

Name	Operation
Header	findOne (query)
updateHeader	update (mutation)

Preferences

User admin preferences are also exposed:

Name	Operation
Preference	findOne (query)
updatePreference	update (mutation)
deletePreference	delete (mutation)

Auth token required in header; only current user's preferences are accessible.

GraphQL Playground

• Enabled in development by default at /api/graphql-playground
• Disabled in production by default — override with graphQL.disablePlaygroundInProduction: false
• Use the playground's Schema/Docs panel to explore all generated types
• Authenticate via login[Collection] mutation to test as a logged-in user

Query Complexity Limits

• Built-in complexity limiter prevents expensive nested queries
• Set graphQL.maxComplexity to a number in config
• Per-field complexity override on relationship, upload, and join fields:

{
  name: 'authors',
  type: 'relationship',
  relationTo: 'authors',
  graphQL: {
    complexity: 100,
  },
}

See wiki/payloadcms/production for full abuse-prevention docs.

Custom Validation Rules

Pass a validationRules function returning an array of GraphQL ValidationRule objects:

graphQL: {
  validationRules: (args) => [NoProductionIntrospection],
}

Useful for blocking introspection, rate-limiting, or field-level guards.

Key Takeaways

• GraphQL API is auto-generated from Collections, Globals, and the Preferences system — no setup required
• Type names are derived from Collection/Global labels (special chars and spaces removed)
• File uploads are REST-only; all other CRUD + auth ops are available via GraphQL
• Playground is dev-only by default; disablePlaygroundInProduction: false to expose it
• Use graphQL.maxComplexity + per-field complexity values to prevent expensive query abuse
• Custom operations go in graphQL.queries / graphQL.mutations — see wiki/payloadcms/graphql-extending
• Schema export: payload-graphql generate:schema — see wiki/payloadcms/graphql-schema

Sources

• raw/graphql__overview.md — https://payloadcms.com/docs/graphql/overview