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

## Overview

Payload ships a fully featured GraphQL API alongside [[wiki/payloadcms/rest-api|REST]] and [[wiki/payloadcms/local-api|Local]] APIs.

- **Default endpoint:** `/api/graphql`
- **Playground:** `/api/graphql-playground` (dev only by default)
- Route can be customized via `routes` in [[wiki/payloadcms/configuration|Payload Config]]

## 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:

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

See [[wiki/payloadcms/production|Production & Performance]] for full abuse-prevention docs.

## Custom Validation Rules

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

```ts
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|GraphQL — Custom Queries and Mutations]]
- Schema export: `payload-graphql generate:schema` — see [[wiki/payloadcms/graphql-schema|GraphQL — Schema Generation]]

## Sources

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