Like what we’re doing? Star us on GitHub!


All Payload API routes are mounted prefixed to your config's routes.api URL segment (default: /api).

REST query parameters:

  • depth - automatically populates relationships and uploads
  • locale - retrieves document(s) in a specific locale
  • fallback-locale - specifies a fallback locale if no locale value exists


Each collection is mounted using its slug value. For example, if a collection's slug is users, all corresponding routes will be mounted on /api/users.

Note: Collection slugs must be formatted in kebab-case

All CRUD operations are exposed as follows:

GET/api/{collection-slug}Find paginated documents
GET/api/{collection-slug}/:idFind a specific document by ID
POST/api/{collection-slug}Create a new document
PATCH/api/{collection-slug}/:idUpdate a document by ID
DELETE/api/{collection-slug}/:idDelete an existing document by ID
Additional find query parameters

The find endpoint supports the following additional query parameters:

  • sort - sort by field
  • where - pass a where query to constrain returned documents
  • limit - limit the returned documents to a certain number
  • page - get a specific page of documents

Auth Operations

Auth enabled collections are also given the following endpoints:

POST/api/{collection-slug}/verify/:tokenEmail verification, if enabled.
POST/api/{collection-slug}/unlockUnlock a user's account, if enabled.
POST/api/{collection-slug}/loginLogs in a user with email / password.
POST/api/{collection-slug}/logoutLogs out a user.
POST/api/{collection-slug}/refresh-tokenRefreshes a token that has not yet expired.
GET/api/{collection-slug}/meReturns the currently logged in user with token.
POST/api/{collection-slug}/forgot-passwordPassword reset workflow entry point.
POST/api/{collection-slug}/reset-passwordTo reset the user's password.


Globals cannot be created or deleted, so there are only two REST endpoints opened:

GET/api/globals/{globalSlug}Get a global by slug
POST/api/globals/{globalSlug}Update a global by slug


In addition to the dynamically generated endpoints above Payload also has REST endpoints to manage the admin user preferences for data specific to the authenticated user.

GET/api/_preferences/{key}Get a preference by key
POST/api/_preferences/{key}Create or update by key
DELETE/api/_preferences/{key}Delete a user preference by key

Custom Endpoints

Additional REST API endpoints can be added to your application by providing an array of endpoints in various places within a Payload config. Custom endpoints are useful for adding additional middleware on existing routes or for building custom functionality into Payload apps and plugins. Endpoints can be added at the top of the Payload config, collections, and globals and accessed respective of the api and slugs you have configured.

Each endpoint object needs to have:

pathA string for the endpoint route after the collection or globals slug
methodThe lowercase HTTP verb to use: 'get', 'head', 'post', 'put', 'delete', 'connect' or 'options'
handlerA function or array of functions to be called with req, res and next arguments. Express
rootWhen true, defines the endpoint on the root Express app, bypassing Payload handlers and the routes.api subpath. Note: this only applies to top-level endpoints of your Payload config, endpoints defined on collections or globals cannot be root.


import { CollectionConfig } from 'payload/types';
// a collection of 'orders' with an additional route for tracking details, reachable at /api/orders/:id/tracking
const Orders: CollectionConfig = {
slug: 'orders',
fields: [ /* ... */ ],
endpoints: [
path: '/:id/tracking',
method: 'get',
handler: async (req, res, next) => {
const tracking = await getTrackingInfo(;
if (tracking) {
res.status(200).send({ tracking });
} else {
res.status(404).send({ error: 'not found' });

Local API