Payload CMS API: REST, GraphQL and the Local API explained

Idea Labz · Nov 17, 2026 · 14 min read

You’ve defined your collections in Payload, and now a website, a mobile app and maybe a partner’s system all need the same data. Payload doesn’t make you build an API for them. It generates one from your config, in three forms, and each suits a different caller.

As of 16 November 2026, Payload 3.93.0 gives every collection and global a REST API, a GraphQL API and a Local API that you call from server code. This guide covers each API, how to query and secure it, the tools around it, and what Payload 4 changes.

We build client projects on Payload from our own project template, which reads the same backend through all three APIs.

  • What APIs does Payload give you?
  • The REST API: routes for collections and globals
  • How do you query Payload’s APIs?
  • The GraphQL API
  • The Local API
  • How access control works in each API
  • Custom endpoints
  • The REST SDK (@payloadcms/sdk)
  • Generated TypeScript types
  • The payload commands
  • Which Payload API should you use?
  • How we use Payload’s APIs on our builds
  • What changes in Payload 4
  • Frequently asked questions
  • What to do next

What APIs does Payload give you?

Payload gives you three APIs from one config. REST and GraphQL work over HTTP, and the Local API runs your queries inside the same Node.js process as Payload. All three run the same operations underneath (find, create, update, delete and the rest), with the same hooks and validation.

For example, take a car rental company in Dubai with three collections, cars, branches and bookings. Its website is a Next.js app that reads cars in server components. Its mobile app lets customers book. A hotel concierge system checks which cars are free, and a second marketing site on another stack lists the fleet. Each of those callers reaches Payload a different way.

RESTGraphQLLocal API
Where your code runsAnywhere that can send HTTPAnywhere that can send HTTPServer code in the same app as Payload
Address/api/{collection-slug} and /api/globals/{global-slug}/api/graphqlpayload.find() and the other methods
Query written asA query stringGraphQL argumentsA JavaScript object
Access rulesAlways runAlways runSkipped unless you turn them on
Related documentsdepth, 2 by defaultThe fields your query asks fordepth, 2 by default
File uploadsYesNoYes

If your front end is Next.js, our guide to Payload and Next.js covers one app versus two and how pages read content.

The REST API: routes for collections and globals

Payload mounts a REST route for every operation under /api by default, using each collection’s slug. In payload@3.93.0 a collection gets these routes:

MethodPathOperation
GET/api/carsFind, paginated
GET/api/cars/:idFind by ID
GET/api/cars/countCount
POST/api/carsCreate
PATCH/api/cars/:idUpdate by ID
PATCH/api/cars?where=…Update every match
DELETE/api/cars/:idDelete by ID
DELETE/api/cars?where=…Delete every match
POST/api/cars/:id/duplicateDuplicate
GET/api/cars/versions and /api/cars/versions/:idRead versions
POST/api/cars/versions/:idRestore a version

A global gets fewer, because it has one document. You read it with GET /api/globals/{slug} and update it with POST /api/globals/{slug}, plus the same version routes. Collections with login switched on also get the auth routes (/login, /logout, /me, /refresh-token and the password routes).

For example, the marketing site can list the cars free at branch 12, with each car’s branch filled in one level deep:

const res = await fetch(
  'https://rentals.example.com/api/cars?where[available][equals]=true&where[branch][equals]=12&depth=1',
)
const { docs, totalDocs, page, totalPages } = await res.json()

A long query string can hit URL limits. Payload accepts a POST with the header X-Payload-HTTP-Method-Override: GET and the parameters in the body for that case (Payload’s REST API docs).

How do you query Payload’s APIs?

Every Payload API uses the same query language, so you learn where, sort, limit and the rest once, and only the syntax differs.

  • where filters with operators such as equals, in, like, exists, greater_than and near, combined with and and or, and dot paths such as branch.city reach into related documents (Payload’s query docs).
  • sort takes a field name, with a minus sign for descending (-pricePerDay).
  • limit and page page the results. In 3.93.0 find returns 10 documents a page unless you set a limit.
  • depth sets how many levels of related documents come back filled in. The default is 2 and the ceiling is 10.
  • select and populate choose which fields come back, for the document and for each related document.
  • locale and draft read one language or the latest draft. Localised fields and drafts and versions have their own guides.

For example, the rental company wants the available cars at one branch, cheapest first, with only the name and daily price. Through REST, qs-esm builds the query string from an object:

import { stringify } from 'qs-esm'

const query = stringify(
  {
    where: { available: { equals: true }, branch: { equals: 12 } },
    sort: 'pricePerDay',
    limit: 20,
    select: { title: true, pricePerDay: true },
  },
  { addQueryPrefix: true },
)
const cars = await fetch(`https://rentals.example.com/api/cars${query}`).then((r) => r.json())

Through GraphQL, the same query is arguments, and the fields you list are the fields you get:

query {
  Cars(
    where: { available: { equals: true }, branch: { equals: 12 } }
    sort: "pricePerDay"
    limit: 20
  ) {
    docs { title pricePerDay }
    totalDocs
  }
}

Through the Local API, it’s an object passed straight to find:

const cars = await payload.find({
  collection: 'cars',
  where: { available: { equals: true }, branch: { equals: 12 } },
  sort: 'pricePerDay',
  limit: 20,
  select: { title: true, pricePerDay: true },
  depth: 0,
})

Set depth and select on every read a page makes. The defaults fill in two levels of relationships and every field, which is more than a list of cars needs.

Payload batches the related documents it fills in. For each level of depth, it runs one query per related collection, in REST, the Local API and GraphQL alike. For example, a list of 20 cars at depth 1 fills in all their branches with one query to branches. So a high depth costs you mostly in response size, plus one query per related collection at each extra level. In GraphQL, a join field is the exception, because it runs its own query for every document in the list, so keep join fields out of long lists, or read them with REST or the Local API.

The GraphQL API

Payload’s GraphQL API is one endpoint, /api/graphql, with a query and a mutation for each operation, named from your collection. A cars collection gets Car (find by ID), Cars (find), countCars, and the mutations createCar, updateCar, deleteCar and duplicateCar (Payload’s GraphQL docs). A global gets one query and one update mutation.

GraphQL works differently from REST in three ways:

  • No depth. In @payloadcms/graphql@3.93.0 the find resolver always runs at depth 0, and related documents load only when your query asks for their fields. Rich text fields are the exception. They take their own depth argument, which defaults to your config’s defaultDepth (2 unless you change it), for the uploads and links inside them.
  • select: true. Add this argument to a find query and Payload turns the fields your query lists into a select, as REST and the Local API use, so it asks the database for those fields only.
  • No file uploads. Upload through REST or the Local API.

By default, Payload rejects queries above a complexity of 1,000 (maxComplexity in payload@3.93.0’s config defaults), and in production it also switches off the GraphQL Playground and introspection. You can add your own queries and mutations under graphQL.queries and graphQL.mutations, and a build that doesn’t need GraphQL can set graphQL: { disable: true }.

For example, the marketing site uses a GraphQL client and generates its own types from the schema. Payload exports that schema to a file with the payload-graphql generate:schema command from the @payloadcms/graphql package (Payload’s GraphQL schema docs).

The Local API

The Local API is the same set of operations called as functions in your server code, with no HTTP request in between. You get it from req.payload inside hooks, access functions and endpoints, or by calling getPayload({ config }) anywhere else on the server (Payload’s Local API docs).

It takes options the HTTP APIs don’t, because only trusted code can call it:

  • overrideAccess skips access rules. It’s true by default.
  • user names the user to check access for, when access rules run.
  • showHiddenFields returns fields marked hidden.
  • context passes values to your hooks.
  • req carries the current request, so the call joins its database transaction.

For example, the rental website’s car page reads one car in a Next.js server component:

import { getPayload } from 'payload'
import config from '@payload-config'

export default async function CarPage({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params
  const payload = await getPayload({ config })
  const car = await payload.findByID({ collection: 'cars', id, depth: 1 })
  return <h1>{car.title}</h1>
}

Inside a hook, pass req along, so a new booking and the car it marks unavailable change in the same transaction.

How access control works in each API

Access control is where the three APIs differ most. REST and GraphQL always run your access functions, and the Local API skips them unless you ask.

Over HTTP, Payload identifies the caller by a session cookie, a JWT or an API key, and runs your access functions for that user. This is where role-based access control (RBAC) lives, in access functions on each collection. The concierge system signs its requests with an API key on a partners collection, so it can read cars but no bookings. Our authentication guide covers API keys and the header they use.

For example, the rental company’s read rule on bookings lets staff see every booking and returns a query for customers, so a customer’s request only ever matches their own:

access: {
  read: ({ req: { user } }) => {
    if (user?.collection === 'staff') return true
    if (user?.collection === 'customers') return { customer: { equals: user.id } }
    return false
  },
},

The Local API defaults overrideAccess to true, so a call skips every access function. Passing user on its own doesn’t change that. In payload@3.93.0 the access check runs only when overrideAccess is false, so a call made for a signed-in customer needs both:

const myBookings = await payload.find({
  collection: 'bookings',
  overrideAccess: false,
  user: req.user,
})

Keep the default for system work, such as seeding or a nightly job. Set overrideAccess: false with the user wherever a call answers a person.

Custom endpoints

A custom endpoint is your own route, added to the endpoints array on the root config, a collection or a global. Each one has a path, a method, a handler that receives Payload’s request and returns a Response. Routes on a collection mount under that collection, so a /:id/quote path on cars answers at /api/cars/:id/quote.

For example, the booking form needs a price for a car between two dates, with weekly discounts the front end shouldn’t know about:

import type { CollectionConfig } from 'payload'

export const Cars: CollectionConfig = {
  slug: 'cars',
  fields: [/* title, branch, available, and pricePerDay as a required number */],
  endpoints: [
    {
      path: '/:id/quote',
      method: 'get',
      handler: async (req) => {
        const from = req.searchParams.get('from')
        const to = req.searchParams.get('to')
        if (!from || !to) {
          return Response.json({ error: 'from and to are required' }, { status: 400 })
        }
        const car = await req.payload.findByID({
          collection: 'cars',
          id: req.routeParams?.id as string,
          depth: 0,
        })
        const days = Math.ceil((Date.parse(to) - Date.parse(from)) / 86_400_000)
        const rate = days >= 7 ? car.pricePerDay * 0.85 : car.pricePerDay
        return Response.json({ days, total: days * rate })
      },
    },
  ],
}

Payload reads the user from the request before your handler runs, but it runs no access function on a custom endpoint. Check req.user yourself in any handler that changes data or returns private fields, and return a 401 or 403 when it’s missing. Read a request body with await req.json(), or call addDataAndFileToRequest(req) to get req.data and an uploaded file.

In payload@3.93.0, custom endpoints are matched before the generated ones, so a custom get on /:id replaces the generated find-by-ID route. And endpoints: false on a collection switches off its REST routes, which then answer 501. For a route outside /api, such as a webhook URL a third party has fixed, add a Next.js route handler to your app instead.

The REST SDK (@payloadcms/sdk)

@payloadcms/sdk is Payload’s own typed client for the REST API. It has been published alongside every Payload release since 3.58.0 (30 September 2025), under the MIT licence, and as of November 2026 Payload’s REST docs still label it beta and say it may change in minor releases.

It mirrors the Local API’s method names (find, findByID, count, create, update, delete, the version methods, findGlobal, updateGlobal and the auth methods), and it takes the same query options, including depth, select, populate, joins, locale and draft. It doesn’t take overrideAccess or user, because it sends an HTTP request, and the server runs access for whoever the request authenticates as.

For example, the mobile app books a car like this:

import { PayloadSDK } from '@payloadcms/sdk'
import type { Config } from './payload-types'

const sdk = new PayloadSDK<Config>({ baseURL: 'https://rentals.example.com/api' })

const booking = await sdk.create(
  { collection: 'bookings', data: { car: 7, from: '2026-12-01', to: '2026-12-08' } },
  { headers: { Authorization: `JWT ${token}` } },
)

Passing your generated Config type gives typed collections, fields and results. For a custom endpoint, sdk.request({ method: 'GET', path: '/cars/7/quote?from=' + from + '&to=' + to }) returns the raw Response when the status is 2xx, and throws an error carrying the status and messages otherwise. Put your own parameters in the path, because args only carries Payload’s query options (where, depth, limit and the rest) in 3.93.0. On the web, baseInit: { credentials: 'include' } sends the login cookie with every call.

Generated TypeScript types

payload generate:types reads your config and writes a TypeScript interface for every collection and global, and for blocks you register at the top level of the config, plus a Config type that ties them together (Payload’s TypeScript docs). Run it after every schema change, so a renamed field shows up as a type error in every file that reads it.

In payload@3.93.0 the file goes to typescript.outputFile if you set it, and otherwise to payload-types.ts in the folder you run the command from. It also adds a declare module 'payload' block, which lets Payload’s own functions infer your types. If you share the file with a project that doesn’t install Payload, set typescript.declare: false and the block is left out. Add interfaceName to a group, array, block or named tab field to get a reusable interface for it.

For example, the mobile app imports the same types the CMS generates. With pricePerDay, from and to marked required in the config, none of them can be null:

import type { Booking, Car } from './payload-types'

export function bookingTotal(car: Car, booking: Booking): number {
  const days = Math.ceil((Date.parse(booking.to) - Date.parse(booking.from)) / 86_400_000)
  return days * car.pricePerDay
}

For the kinds of field a collection can hold, such as text, relationship and blocks, see our guide to Payload’s field types.

The payload commands

Payload’s command-line tool is the payload command, run through your package manager (pnpm payload <command>). In 3.93.0 it runs these:

CommandWhat it does
generate:typesWrites your TypeScript types
generate:importmapRebuilds the import map for custom admin components
generate:db-schemaWrites a database schema file, for the Postgres and SQLite adapters
infoPrints your installed Payload package versions and your Node.js version, for bug reports
run <script>Runs a script with your environment loaded, so it can call the Local API
jobs:runRuns queued jobs
jobs:handle-schedulesQueues jobs that are due on a schedule
migrate, migrate:create, migrate:status, migrate:down, migrate:refresh, migrate:reset, migrate:freshDatabase migrations

It also runs scripts you register in the config’s bin array, by the key you give them. The migrate commands have their own guide. To start a new project, create-payload-app is a separate package, which our Payload tutorial uses step by step.

For example, the rental company fills a new database with its fleet by running pnpm payload run src/seed.ts, a script that calls getPayload and creates the cars through the Local API.

Which Payload API should you use?

Pick by where your code runs and who is calling. For the rental company, that gives five answers:

  1. Code running on Payload’s own server uses the Local API, as the website’s server components, hooks and jobs do.
  2. A client you build in TypeScript uses REST through the SDK, or through a small client of your own. The mobile app books with the customer’s token, and access rules decide what it can touch.
  3. A system someone else built uses REST with an API key. The concierge system needs no SDK, only the route and the header.
  4. A front end that wants to choose its own fields uses GraphQL, as the marketing site does.
  5. Logic that belongs on the server goes in a custom endpoint. The quote stays in one place, whatever calls it.

For an AI assistant reading or editing content, Payload’s MCP plugin exposes the same operations as tools, covered in our guide to Payload and MCP.

How we use Payload’s APIs on our builds

Our project template (v2.13.0, November 2026, on Payload 3.93.0) uses all three APIs, and each build uses the ones it needs. It ships two Next.js front ends that do the same job on purpose, one reading Payload’s GraphQL API with Apollo Client and the other reading the REST API, and an Expo mobile app that reads REST. Pages served from the CMS app itself, and the server work inside it (seeding, jobs, workflow steps and our plugins), use the Local API. Where a Local API call acts for a signed-in user, we pass the user and switch access checks back on; system work runs with Payload’s default.

We don’t use @payloadcms/sdk. The REST web app and the mobile app share a small REST client of our own. On the phone it keeps the login token in secure storage and sends it as a bearer token; on the web the browser sends a login cookie. Either way, a 401 is handled in one place. Our client sends depth and limit on each call, and the REST web app asks for depth 2 by name when it loads a page. Types come from payload generate:types, written into a shared package with the declare block switched off, so the web apps, Node code and the mobile app import the same types. The GraphQL schema is exported to a file in the same package.

Our core collections add no custom endpoints. Our own plugins add theirs, such as import and export routes for field definitions and a WhatsApp webhook, and a few routes, such as a form submission route, sit outside Payload as Next.js route handlers. If you want this set up on your own project, see how we build on Payload.

What changes in Payload 4

Payload 4 is in beta, and the latest beta as of 16 November 2026 is 4.0.0-beta.9 (13 November). Two of its changes alter how the APIs behave by default. Betas can still change before the stable release.

  • The Local API enforces access by default. In payload@4.0.0-beta.9 overrideAccess defaults to false, so a Local API call that relied on skipping access now runs your access functions. Seeding and jobs need overrideAccess: true set explicitly. Payload’s codemod (npx @payloadcms/codemod) adds overrideAccess: true to existing Local API calls so they keep today’s behaviour. Then remove it from every call that acts for a user.
  • The default depth drops from 2 to 1. Queries that don’t set depth fill in one level of related documents.

For example, the car page in the Local API section calls findByID without overrideAccess. On 4.0.0-beta.9 that call runs the read rule on cars with no user, so the page keeps working only if your rule lets anonymous visitors read cars.

The SDK’s methods are unchanged in 4.0.0-beta.9. The full list of changes is in Payload’s 3.0 to 4.0 migration guide.

Frequently asked questions

Does Payload CMS have an API?

Yes. Payload generates a REST API and a GraphQL API from your collections and globals, and gives server code the Local API for the same operations without HTTP. You don’t write any of them, but you can add your own routes as custom endpoints.

Is Payload’s API free to use?

Yes. The REST, GraphQL and Local APIs are part of Payload’s open-source core, under the MIT licence. Your costs are the hosting for Payload and its database, and there’s no charge per API call.

How do I authenticate requests to Payload’s REST API?

Send the session cookie Payload sets at login, a JWT in the Authorization header, or an API key for collections that have keys switched on. Our guide to Payload authentication shows each one.

Can I upload files through GraphQL?

No. Payload’s GraphQL API doesn’t take file uploads. Upload with REST or the Local API first, then reference the upload’s ID from GraphQL.

Can I turn off the GraphQL API?

Yes. Set graphQL: { disable: true } in your Payload config, and /api/graphql answers 404. REST and the Local API keep working.

Is the Local API faster than REST?

Yes, for code on the same server, because there’s no HTTP request or JSON round trip. It only runs in server code inside your Payload app, so browsers, mobile apps and other systems use REST or GraphQL. The database work is the same, with the same queries and the same batching of related documents, so depth and select matter just as much.

Where does payload generate:types save the file?

In payload@3.93.0 it writes to typescript.outputFile if your config sets it, and otherwise to payload-types.ts in the folder you run the command from. Set outputFile so the file always lands in the same place.

Does Payload have an official SDK?

Yes. @payloadcms/sdk is Payload’s typed client for the REST API, published with every release since 3.58.0. As of November 2026 Payload’s docs still label it beta.

What to do next

Start with one collection and read it through the API your first caller needs, setting depth and select on the query. Generate your types before you write the client, and add access rules before any custom endpoint goes live.

If you don’t have a project yet, build one with our Payload tutorial. If your callers need to sign in, read how logins and API keys work in Payload.

References

All links checked and active as of 16 November 2026.

READY TO MAKE A REAL CHANGE?

Let's build it together