REST API

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

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
Find/api/{collection-slug}
Find By ID/api/{collection-slug}/{id}
Create/api/{collection-slug}
Update/api/{collection-slug}
Update By ID/api/{collection-slug}/{id}
Delete/api/{collection-slug}
Delete by ID/api/{collection-slug}/{id}

Auth Operations

Auth enabled collections are also given the following endpoints:

OperationMethodPathView
Login/api/{user-collection}/login
Logout/api/{user-collection}/logout
Unlock/api/{user-collection}/unlock
Refresh/api/{user-collection}/refresh-token
Verify User/api/{user-collection}/verify/{token}
Current User/api/{user-collection}/me
Forgot Password/api/{user-collection}/forgot-password
Reset Password/api/{user-collection}/reset-password

Globals

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

OperationMethodPathView
Get Global/api/globals/{global-slug}
Update Global/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 Preference/api/payload-preferences/{key}
Create Preference/api/payload-preferences/{key}
Delete Preference/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:

PropertyDescription
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.
customExtension point for adding custom data (e.g. for plugins)

Example:

1
import { CollectionConfig } from 'payload/types'
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
],
10
endpoints: [
11
{
12
path: '/:id/tracking',
13
method: 'get',
14
handler: async (req, res, next) => {
15
const tracking = await getTrackingInfo(req.params.id)
16
if (tracking) {
17
res.status(200).send({ tracking })
18
} else {
19
res.status(404).send({ error: 'not found' })
20
}
21
},
22
},
23
],
25
}
Next

Local API