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

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
Next

Local API