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).

For example, if you have a Collection called pages, you can fetch its documents directly from the browser or any HTTP client:

1fetch('https://localhost:3000/api/pages') 
2  .then((res) => res.json())
3  .then((data) => console.log(data))

To enhance DX, you can use Payload SDK to query your REST 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 in the result
populate - specifies which fields to include in the result from populated documents
limit - limits the number of documents returned
page - specifies which page to get documents from when used with a limit
sort - specifies the field(s) to use to sort the returned documents by
where - specifies advanced filters to use to query documents
joins - specifies the custom request for each join field by name of the field

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 that accepts req - `PayloadRequest` object which contains Web Request properties, currently authenticated `user` and the Local API instance `payload`.
`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}

Root-level routes

Custom endpoints defined in your Payload Config are always mounted under your configured routes.api path (default: /api). To define a route that is not prefixed by this path, add a Next.js Route Handler at the desired location in your app directory:

1// src/app/my-route/route.ts
2
3export const GET = async () => {
4  return Response.json({
5    message: 'This is an example of a custom route.',
6  })
7}

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 'payload'
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 'payload'
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}

headersWithCors

By default, custom endpoints don't handle CORS headers in responses. The headersWithCors function checks the Payload config and sets the appropriate CORS headers in the response accordingly.

1import { headersWithCors } from 'payload'
2
3// custom endpoint example
4{
path: '/:id/tracking',
method: 'post',
handler: async (req) => {
  return Response.json(
    { message: 'success' },
    {
      headers: headersWithCors({
        headers: new Headers(),
        req,
      })
    },
  )
}
18}

Method Override for GET Requests

Payload supports a method override feature that allows you to send GET requests using the HTTP POST method. This can be particularly useful in scenarios when the query string in a regular GET request is too long.

How to Use

To use this feature, include the X-Payload-HTTP-Method-Override header set to GET in your POST request. The parameters should be sent in the body of the request with the Content-Type set to application/x-www-form-urlencoded.

Example

Here is an example of how to use the method override to perform a GET request:

Using Method Override (POST)

1const res = await fetch(`${api}/${collectionSlug}`, {
method: 'POST',
credentials: 'include',
headers: {
  'Accept-Language': i18n.language,
  'Content-Type': 'application/x-www-form-urlencoded',
  'X-Payload-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})

Passing as JSON

When using X-Payload-HTTP-Method-Override, it expects the body to be a query string. If you want to pass JSON instead, you can set the Content-Type to application/json and include the JSON body in the request.

Example

1const res = await fetch(`${api}/${collectionSlug}/${id}`, {
// Only the findByID endpoint supports HTTP method overrides with JSON data
method: 'POST',
credentials: 'include',
headers: {
  'Accept-Language': i18n.language,
  'Content-Type': 'application/json',
  'X-Payload-HTTP-Method-Override': 'GET',
},
body: JSON.stringify({
  depth: 1,
  locale: 'en',
}),
14})

This can be more efficient for large JSON payloads, as you avoid converting data to and from query strings. However, only certain endpoints support this. Supported endpoints will read the parsed body under a data property, instead of reading from query parameters as with standard GET requests.

Payload REST API SDK

The best, fully type-safe way to query Payload REST API is to use the SDK package, which can be installed with:

1pnpm add @payloadcms/sdk

Its usage is very similar to the Local API.

Example:

1import { PayloadSDK } from '@payloadcms/sdk'
2
3const sdk = new PayloadSDK({
4  baseURL: 'https://example.com/api',
5})

For projects without a payload-types.ts file, or when working with multiple Payload configs, you can manually pass the types as a generic:

1import { PayloadSDK } from '@payloadcms/sdk'
2import type { Config } from './payload-types'
3
4const sdk = new PayloadSDK<Config>({
5  baseURL: 'https://example.com/api',
6})

Operations

1// Find operation
2const posts = await sdk.find({
3  collection: 'posts',
4  draft: true,
5  limit: 10,
6  locale: 'en',
7  page: 1,
8  where: { _status: { equals: 'published' } },
9})
10
11// Find by ID operation
12const posts = await sdk.findByID({
13  id,
14  collection: 'posts',
15  draft: true,
16  locale: 'en',
17})
18
19// Auth login operation
20const result = await sdk.login({
21  collection: 'users',
22  data: {
23    email: 'dev@payloadcms.com',
24    password: '12345',
25  },
26})
27
28// Create operation
29const result = await sdk.create({
30  collection: 'posts',
31  data: { text: 'text' },
32})
33
34// Create operation with a file
35// `file` can be either a Blob | File object or a string URL
36const result = await sdk.create({ collection: 'media', file, data: {} })
37
38// Count operation
39const result = await sdk.count({
40  collection: 'posts',
41  where: { id: { equals: post.id } },
42})
43
44// Update (by ID) operation
45const result = await sdk.update({
46  collection: 'posts',
47  id: post.id,
48  data: {
49    text: 'updated-text',
50  },
51})
52
53// Update (bulk) operation
54const result = await sdk.update({
55  collection: 'posts',
56  where: {
57    id: {
58      equals: post.id,
59    },
60  },
61  data: { text: 'updated-text-bulk' },
62})
63
64// Delete (by ID) operation
65const result = await sdk.delete({ id: post.id, collection: 'posts' })
66
67// Delete (bulk) operation
68const result = await sdk.delete({
69  where: { id: { equals: post.id } },
70  collection: 'posts',
71})
72
73// Find Global operation
74const result = await sdk.findGlobal({ slug: 'global' })
75
76// Update Global operation
77const result = await sdk.updateGlobal({
78  slug: 'global',
79  data: { text: 'some-updated-global' },
80})
81
82// Auth Login operation
83const result = await sdk.login({
84  collection: 'users',
85  data: { email: 'dev@payloadcms.com', password: '123456' },
86})
87
88// Auth Me operation
89const result = await sdk.me(
90  { collection: 'users' },
91  {
92    headers: {
93      Authorization: `JWT  ${user.token}`,
94    },
95  },
96)
97
98// Auth Refresh Token operation
99const result = await sdk.refreshToken(
100  { collection: 'users' },
101  { headers: { Authorization: `JWT ${user.token}` } },
102)
103
104// Auth Forgot Password operation
105const result = await sdk.forgotPassword({
106  collection: 'users',
107  data: { email: user.email },
108})
109
110// Auth Reset Password operation
111const result = await sdk.resetPassword({
112  collection: 'users',
113  data: { password: '1234567', token: resetPasswordToken },
114})
115
116// Find Versions operation
117const result = await sdk.findVersions({
118  collection: 'posts',
119  where: { parent: { equals: post.id } },
120})
121
122// Find Version by ID operation
123const result = await sdk.findVersionByID({
124  collection: 'posts',
125  id: version.id,
126})
127
128// Restore Version operation
129const result = await sdk.restoreVersion({
130  collection: 'posts',
131  id,
132})
133
134// Find Global Versions operation
135const result = await sdk.findGlobalVersions({
136  slug: 'global',
137})
138
139// Find Global Version by ID operation
140const result = await sdk.findGlobalVersionByID({
141  id: version.id,
142  slug: 'global',
143})
144
145// Restore Global Version operation
146const result = await sdk.restoreGlobalVersion({
147  slug: 'global',
148  id,
149})

Every operation has optional 3rd parameter which is used to add additional data to the RequestInit object (like headers):

1await sdk.me(
{
  collection: 'users',
},
{
  // RequestInit object
  headers: {
    Authorization: `JWT ${token}`,
  },
},
11)

To query custom endpoints, you can use the request method, which is used internally for all other methods:

1await sdk.request({
method: 'POST',
path: '/send-data',
json: {
  id: 1,
},
7})

Custom fetch implementation and baseInit for shared RequestInit properties:

1const sdk = new PayloadSDK<Config>({
baseInit: { credentials: 'include' },
baseURL: 'https://example.com/api',
fetch: async (url, init) => {
  console.log('before req')
  const response = await fetch(url, init)
  console.log('after req')
  return response
},
10})

Example of a custom fetch implementation for testing the REST API without needing to spin up a next development server:

1import config from '@payload-config'
2import {
3  REST_DELETE,
4  REST_GET,
5  REST_PATCH,
6  REST_POST,
7  REST_PUT,
8} from '@payloadcms/next/routes'
9import { PayloadSDK } from '@payloadcms/sdk'
10
11const api = {
12  GET: REST_GET(config),
13  POST: REST_POST(config),
14  PATCH: REST_PATCH(config),
15  DELETE: REST_DELETE(config),
16  PUT: REST_PUT(config),
17}
18
19const awaitedConfig = await config
20
21export const sdk = new PayloadSDK({
22  baseURL: ``,
23  fetch: (path: string, init: RequestInit) => {
24    const [slugs, search] = path.slice(1).split('?')
25    const url = `${awaitedConfig.serverURL || 'http://localhost:3000'}${awaitedConfig.routes.api}/${slugs}${search ? `?${search}` : ''}`
26
27    if (init.body instanceof FormData) {
28      const file = init.body.get('file') as Blob
29      if (file && init.headers instanceof Headers) {
30        init.headers.set('Content-Length', file.size.toString())
31      }
32    }
33    const request = new Request(url, init)
34
35    const params = {
36      params: Promise.resolve({
37        slug: slugs.split('/'),
38      }),
39    }
40
41    return api[init.method.toUpperCase()](request, params)
42  },
43})

Was this page helpful?

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."

Get the resources you need to start building today

Microsoft chose Payload to tell the world about AI.

REST API

Collections

Auth Operations

Globals

Preferences

Custom Endpoints

Root-level routes

Helpful tips

Method Override for GET Requests

How to Use

Example

Using Method Override (POST)

Equivalent Regular GET Request

Passing as JSON

Example

Payload REST API SDK

Operations

GraphQL Overview