REST API

The REST API is a fully functional HTTP client that allows you to interact with your Documents in a RESTful manner. It supports all CRUD operations and is equipped with automatic pagination, depth, and sorting. All Payload API routes are mounted and 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
select - specifies which fields to include to the result
populate - specifies which fields to include to the result from populated documents

Collections

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:

Operation	Method	Path
Find	`GET`	/api/{collection-slug}
Find By ID	`GET`	/api/{collection-slug}/{id}
Count	`GET`	/api/{collection-slug}/count
Create	`POST`	/api/{collection-slug}
Update	`PATCH`	/api/{collection-slug}
Update By ID	`PATCH`	/api/{collection-slug}/{id}
Delete	`DELETE`	/api/{collection-slug}
Delete by ID	`DELETE`	/api/{collection-slug}/{id}

Auth Operations

Auth enabled collections are also given the following endpoints:

Operation	Method	Path
Login	`POST`	/api/{user-collection}/login
Logout	`POST`	/api/{user-collection}/logout
Unlock	`POST`	/api/{user-collection}/unlock
Refresh	`POST`	/api/{user-collection}/refresh-token
Verify User	`POST`	/api/{user-collection}/verify/{token}
Current User	`GET`	/api/{user-collection}/me
Forgot Password	`POST`	/api/{user-collection}/forgot-password
Reset Password	`POST`	/api/{user-collection}/reset-password

Globals

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

Operation	Method	Path	View
Get Global	`GET`	/api/globals/{global-slug}
Update Global	`POST`	/api/globals/{global-slug}

Preferences

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.

Operation	Method	Path
Get Preference	`GET`	/api/payload-preferences/{key}
Create Preference	`POST`	/api/payload-preferences/{key}
Delete Preference	`DELETE`	/api/payload-preferences/{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:

Property	Description
`path`	A string for the endpoint route after the collection or globals slug
`method`	The lowercase HTTP verb to use: 'get', 'head', 'post', 'put', 'delete', 'connect' or 'options'
`handler`	A function or array of functions to be called with req, res and next arguments. Next.js
`root`	When `true`, defines the endpoint on the root Next.js 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.
`custom`	Extension point for adding custom data (e.g. for plugins)

Example:

1import type { CollectionConfig } from 'payload'
2
3// a collection of 'orders' with an additional route for tracking details, reachable at /api/orders/:id/tracking
4export const Orders: CollectionConfig = {
slug: 'orders',
fields: [
  /* ... */
],
endpoints: [
  {
    path: '/:id/tracking',
    method: 'get',
    handler: async (req) => {
      const tracking = await getTrackingInfo(req.routeParams.id)
15
      if (!tracking) {
        return Response.json({ error: 'not found' }, { status: 404})
      }
19
      return Response.json({
        message: `Hello ${req.routeParams.name as string} @ ${req.routeParams.group as string}`,
      })
    },
  },
  {
    path: '/:id/tracking',
    method: 'post',
    handler: async (req) => {
      // `data` is not automatically appended to the request
      // if you would like to read the body of the request
      // you can use `data = await req.json()`
      const data = await req.json()
      await req.payload.update({
        collection: 'tracking',
        data: {
          // data to update the document with
        }
      })
      return Response.json({
        message: 'successfully updated tracking info'
      })
    }
  },
  {
    path: '/:id/forbidden',
    method: 'post',
    handler: async (req) => {
      // this is an example of an authenticated endpoint
      if (!req.user) {
        return Response.json({ error: 'forbidden' }, { status: 403 })
      }
52
      // do something
54
      return Response.json({
        message: 'successfully updated tracking info'
      })
    }
  }
],
61}

Helpful tips

req.data

Data is not automatically appended to the request. You can read the body data by calling await req.json().

Or you could use our helper function that mutates the request and appends data and file if found.

1import { addDataAndFileToRequest } from '@payloadcms/next/utilities'
2
3// custom endpoint example
4{
path: '/:id/tracking',
method: 'post',
handler: async (req) => {
  await addDataAndFileToRequest(req)
  await req.payload.update({
    collection: 'tracking',
    data: {
      // data to update the document with
    }
  })
  return Response.json({
    message: 'successfully updated tracking info'
  })
}
19}

req.locale & req.fallbackLocale

The locale and the fallback locale are not automatically appended to custom endpoint requests. If you would like to add them you can use this helper function.

1import { addLocalesToRequestFromData } from '@payloadcms/next/utilities'
2
3// custom endpoint example
4{
5  path: '/:id/tracking',
6  method: 'post',
7  handler: async (req) => {
8    await addLocalesToRequestFromData(req)
9    // you now can access req.locale & req.fallbackLocale
10    return Response.json({ message: 'success' })
11  }
12}

1const res = await fetch(`${api}/${collectionSlug}`, {
method: 'POST',
credentials: 'include',
headers: {
  'Accept-Language': i18n.language,
  'Content-Type': 'application/x-www-form-urlencoded',
  'X-HTTP-Method-Override': 'GET',
},
body: qs.stringify({
  depth: 1,
  locale: 'en',
}),
13})

Equivalent Regular GET Request

1const res = await fetch(`${api}/${collectionSlug}?depth=1&locale=en`, {
method: 'GET',
credentials: 'include',
headers: {
  'Accept-Language': i18n.language,
},
7})

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.

REST API

Collections

Auth Operations

Globals

Preferences

Custom Endpoints

Helpful tips

Method Override for GET Requests

How to Use

Example

Using Method Override (POST)

Equivalent Regular GET Request

GraphQL Overview

Related Help Topics