Simplify your stack and build anything. Or everything.
Build tomorrow’s web with a modern solution you truly own.
Code-based nature means you can build on top of it to power anything.
It’s time to take back your content infrastructure.

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

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 to the result
  • populate - specifies which fields to include to 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:

OperationMethodPathView
FindGET/api/{collection-slug}
Find By IDGET/api/{collection-slug}/{id}
CountGET/api/{collection-slug}/count
CreatePOST/api/{collection-slug}
UpdatePATCH/api/{collection-slug}
Update By IDPATCH/api/{collection-slug}/{id}
DeleteDELETE/api/{collection-slug}
Delete by IDDELETE/api/{collection-slug}/{id}

Auth Operations

Auth enabled collections are also given the following endpoints:

OperationMethodPathView
LoginPOST/api/{user-collection}/login
LogoutPOST/api/{user-collection}/logout
UnlockPOST/api/{user-collection}/unlock
RefreshPOST/api/{user-collection}/refresh-token
Verify UserPOST/api/{user-collection}/verify/{token}
Current UserGET/api/{user-collection}/me
Forgot PasswordPOST/api/{user-collection}/forgot-password
Reset PasswordPOST/api/{user-collection}/reset-password

Globals

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

OperationMethodPathView
Get GlobalGET/api/globals/{global-slug}
Update GlobalPOST/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.

OperationMethodPathView
Get PreferenceGET/api/payload-preferences/{key}
Create PreferencePOST/api/payload-preferences/{key}
Delete PreferenceDELETE/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.

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:

1
import type { CollectionConfig } from 'payload'
2
3
// a collection of 'orders' with an additional route for tracking details, reachable at /api/orders/:id/tracking
4
export const Orders: CollectionConfig = {
5
slug: 'orders',
6
fields: [
7
/* ... */
8
],
9
endpoints: [
10
{
11
path: '/:id/tracking',
12
method: 'get',
13
handler: async (req) => {
14
const tracking = await getTrackingInfo(req.routeParams.id)
15
16
if (!tracking) {
17
return Response.json({ error: 'not found' }, { status: 404 })
18
}
19
20
return Response.json({
21
message: `Hello ${req.routeParams.name as string} @ ${req.routeParams.group as string}`,
22
})
23
},
24
},
25
{
26
path: '/:id/tracking',
27
method: 'post',
28
handler: async (req) => {
29
// `data` is not automatically appended to the request
30
// if you would like to read the body of the request
31
// you can use `data = await req.json()`
32
const data = await req.json()
33
await req.payload.update({
34
collection: 'tracking',
35
data: {
36
// data to update the document with
37
},
38
})
39
return Response.json({
40
message: 'successfully updated tracking info',
41
})
42
},
43
},
44
{
45
path: '/:id/forbidden',
46
method: 'post',
47
handler: async (req) => {
48
// this is an example of an authenticated endpoint
49
if (!req.user) {
50
return Response.json({ error: 'forbidden' }, { status: 403 })
51
}
52
53
// do something
54
55
return Response.json({
56
message: 'successfully updated tracking info',
57
})
58
},
59
},
60
],
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.

1
import { addDataAndFileToRequest } from 'payload'
2
3
// custom endpoint example
4
{
5
path: '/:id/tracking',
6
method: 'post',
7
handler: async (req) => {
8
await addDataAndFileToRequest(req)
9
await req.payload.update({
10
collection: 'tracking',
11
data: {
12
// data to update the document with
13
}
14
})
15
return Response.json({
16
message: 'successfully updated tracking info'
17
})
18
}
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.

1
import { 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.

1
import { headersWithCors } from 'payload'
2
3
// custom endpoint example
4
{
5
path: '/:id/tracking',
6
method: 'post',
7
handler: async (req) => {
8
return Response.json(
9
{ message: 'success' },
10
{
11
headers: headersWithCors({
12
headers: new Headers(),
13
req,
14
})
15
},
16
)
17
}
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)

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

Equivalent Regular GET Request

1
const res = await fetch(`${api}/${collectionSlug}?depth=1&locale=en`, {
2
method: 'GET',
3
credentials: 'include',
4
headers: {
5
'Accept-Language': i18n.language,
6
},
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

1
const res = await fetch(`${api}/${collectionSlug}/${id}`, {
2
// Only the findByID endpoint supports HTTP method overrides with JSON data
3
method: 'POST',
4
credentials: 'include',
5
headers: {
6
'Accept-Language': i18n.language,
7
'Content-Type': 'application/json',
8
'X-Payload-HTTP-Method-Override': 'GET',
9
},
10
body: JSON.stringify({
11
depth: 1,
12
locale: 'en',
13
}),
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:

1
pnpm add @payloadcms/sdk

Its usage is very similar to the Local API.

Example:

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

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

1
await sdk.me(
2
{
3
collection: 'users',
4
},
5
{
6
// RequestInit object
7
headers: {
8
Authorization: `JWT ${token}`,
9
},
10
},
11
)

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

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

Custom fetch implementation and baseInit for shared RequestInit properties:

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

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

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

GraphQL Overview