REST API

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

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.

All CRUD operations are exposed as follows:

MethodPathDescription
GET/api/{collectionSlug}Find paginated documents
GET/api/{collectionSlug}/:idFind a specific document by ID
POST/api/{collectionSlug}Create a new document
PUT/api/{collectionSlug}/:idUpdate a document by ID
DELETE/api/{collectionSlug}/: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:

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

Globals

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

MethodPathDescription
GET/api/globals/{globalSlug}Get a global by slug
POST/api/globals/{globalSlug}Update a global by 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.

MethodPathDescription
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 collections and globals by providing array of endpoints in the configuration. These can be used to write additional middleware on existing routes or build custom functionality into Payload apps and plugins.

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

Example:

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

Local API