title	label	order	desc	keywords
REST API	Overview	10	Payload generates a fully functional REST API from your Collection and Global configs.	rest, api, documentation, Content Management System, cms, headless, javascript, node, react, nextjs

A fully functional REST API is automatically generated from your Collection and Global configs.

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

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:

<RestExamples data={[ { operation: "Find", method: "GET", path: "/api/{collection-slug}", description: "Find paginated documents", example: { slug: "getCollection", req: true, res: { paginated: true, data: { id: "644a5c24cc1383022535fc7c", title: "Home", content: "REST API examples", slug: "home", createdAt: "2023-04-27T11:27:32.419Z", updatedAt: "2023-04-27T11:27:32.419Z", }, }, drawerContent: `

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 ` }, }, { operation: "Find By ID", method: "GET", path: "/api/{collection-slug}/{id}", description: "Find a specific document by ID", example: { slug: "findByID", req: true, res: { id: "644a5c24cc1383022535fc7c", title: "Home", content: "REST API examples", slug: "home", createdAt: "2023-04-27T11:27:32.419Z", updatedAt: "2023-04-27T11:27:32.419Z", }, }, }, { operation: "Count", method: "GET", path: "/api/{collection-slug}/count", description: "Count the documents", example: { slug: "count", req: true, res: { totalDocs: 10 }, }, }, { operation: "Create", method: "POST", path: "/api/{collection-slug}", description: "Create a new document", example: { slug: "createDocument", req: { credentials: true, headers: true, body: { title: "New page", content: "Here is some content", }, }, res: { message: "Page successfully created.", doc: { id: "644ba34c86359864f9535932", title: "New page", content: "Here is some content", slug: "new-page", createdAt: "2023-04-28T10:43:24.466Z", updatedAt: "2023-04-28T10:43:24.466Z", }, }, }, }, { operation: "Update", method: "PATCH", path: "/api/{collection-slug}", description: "Update all documents matching the where query", example: { slug: "updateDocument", req: { credentials: true, query: true, headers: true, body: { title: "I have been updated!", }, }, res: { docs: [ { id: "644ba34c86359864f9535932", title: "I have been updated!", content: "Here is some content", slug: "new-page", createdAt: "2023-04-28T10:43:24.466Z", updatedAt: "2023-04-28T10:45:23.724Z", }, ], errors: [], }, }, }, { operation: "Update By ID", method: "PATCH", path: "/api/{collection-slug}/{id}", description: "Update a document by ID", example: { slug: "updateDocumentByID", req: { credentials: true, headers: true, body: { title: "I have been updated by ID!", categories: "example-uuid", tags: { relationTo: "location", value: "another-example-uuid", }, }, }, res: { message: "Updated successfully.", doc: { id: "644a5c24cc1383022535fc7c", title: "I have been updated by ID!", content: "REST API examples", categories: { id: "example-uuid", name: "Test Category", }, tags: [ { relationTo: "location", value: { id: "another-example-uuid", name: "Test Location", }, }, ], slug: "home", createdAt: "2023-04-27T11:27:32.419Z", updatedAt: "2023-04-28T10:47:59.259Z", }, }, }, }, { operation: "Delete", method: "DELETE", path: "/api/{collection-slug}", description: "Delete all documents matching the where query", example: { slug: "deleteDocuments", req: { credentials: true, query: true, headers: true, }, res: { docs: [ { id: "644ba4cf86359864f953594b", title: "New page", content: "Here is some content", slug: "new-page", createdAt: "2023-04-28T10:49:51.359Z", updatedAt: "2023-04-28T10:49:51.359Z", }, ], errors: [], }, }, }, { operation: "Delete by ID", method: "DELETE", path: "/api/{collection-slug}/{id}", description: "Delete an existing document by ID", example: { slug: "deleteByID", req: { credentials: true, headers: true, }, res: { id: "644ba51786359864f9535954", title: "New page", content: "Here is some content", slug: "new-page", createdAt: "2023-04-28T10:51:03.028Z", updatedAt: "2023-04-28T10:51:03.028Z", }, }, },

]} />

Auth Operations

Auth enabled collections are also given the following endpoints:

<RestExamples data={[ { operation: "Login", method: "POST", path: "/api/{user-collection}/login", description: "Logs in a user with email / password", example: { slug: "login", req: { credentials: true, headers: true, body: { email: "dev@payloadcms.com", password: "password", }, }, res: { message: "Auth Passed", user: { id: "644b8453cd20c7857da5a9b0", email: "dev@payloadcms.com", _verified: true, createdAt: "2023-04-28T08:31:15.788Z", updatedAt: "2023-04-28T11:11:03.716Z", }, token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9", exp: 1682689147, }, }, }, { operation: "Logout", method: "POST", path: "/api/{user-collection}/logout", description: "Logs out a user", example: { slug: "logout", req: { headers: true, credentials: true, }, res: { message: "You have been logged out successfully.", }, }, }, { operation: "Unlock", method: "POST", path: "/api/{user-collection}/unlock", description: "Unlock a user account", example: { slug: "unlockCollection", req: { credentials: true, headers: true, body: { email: "dev@payloadcms.com", }, }, res: { message: "Success", }, }, }, { operation: "Refresh", method: "POST", path: "/api/{user-collection}/refresh-token", description: "Refreshes a token that has not yet expired", example: { slug: "refreshToken", req: { credentials: true, headers: true, }, res: { message: "Token refresh successful", refreshedToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9", exp: 1682689362, user: { email: "dev@payloadcms.com", id: "644b8453cd20c7857da5a9b0", collection: "users", }, }, }, }, { operation: "Verify User", method: "POST", path: "/api/{user-collection}/verify/{token}", description: "User verification", example: { slug: "verifyUser", req: { credentials: true, headers: true, }, res: { message: "Email verified successfully.", }, }, }, { operation: "Current User", method: "GET", path: "/api/{user-collection}/me", description: "Returns the currently logged in user with token", example: { slug: "currentUser", req: { credentials: true, headers: true, }, res: { user: { id: "644b8453cd20c7857da5a9b0", email: "dev@payloadcms.com", _verified: true, createdAt: "2023-04-28T08:31:15.788Z", updatedAt: "2023-04-28T11:45:23.926Z", _strategy: "local-jwt", }, collection: "users", token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9", exp: 1682689523, }, }, }, { operation: "Forgot Password", method: "POST", path: "/api/{user-collection}/forgot-password", description: "Password reset workflow entry point", example: { slug: "forgotPassword", req: { headers: true, credentials: true, body: { email: "dev@payloadcms.com", }, }, res: { message: "Success", }, }, }, { operation: "Reset Password", method: "POST", path: "/api/{user-collection}/reset-password", description: "Reset user password", example: { slug: "resetPassword", req: { credentials: true, headers: true, body: { token: "7eac3830ffcfc7f9f66c00315dabeb11575dba91", password: "newPassword", }, }, res: { message: "Password reset successfully.", token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9", user: { id: "644baa473ea9538765cc30fc", email: "dev@payloadcms.com", _verified: true, createdAt: "2023-04-28T11:13:11.569Z", updatedAt: "2023-04-28T11:49:23.860Z", }, }, }, },

]} />

Globals

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

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.

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.

Custom endpoints are not authenticated by default. You are responsible for securing your own endpoints.

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:

import type { CollectionConfig } from 'payload'

// a collection of 'orders' with an additional route for tracking details, reachable at /api/orders/:id/tracking
export const Orders: CollectionConfig = {
  slug: 'orders',
  fields: [
    /* ... */
  ],
  // highlight-start
  endpoints: [
    {
      path: '/:id/tracking',
      method: 'get',
      handler: async (req) => {
        const tracking = await getTrackingInfo(req.routeParams.id)

        if (!tracking) {
          return Response.json({ error: 'not found' }, { status: 404 })
        }

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

        // do something

        return Response.json({
          message: 'successfully updated tracking info',
        })
      },
    },
  ],
  // highlight-end
}

**Note:** **req** will have the **payload** object and can be used inside your endpoint handlers for making calls like req.payload.find() that will make use of [Access Control](../access-control/overview) and [Hooks](../hooks/overview).

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.

import { addDataAndFileToRequest } from 'payload'

// custom endpoint example
{
  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'
    })
  }
}

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.

import { addLocalesToRequestFromData } from 'payload'

// custom endpoint example
{
  path: '/:id/tracking',
  method: 'post',
  handler: async (req) => {
    await addLocalesToRequestFromData(req)
    // you now can access req.locale & req.fallbackLocale
    return Response.json({ message: 'success' })
  }
}

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.

import { headersWithCors } from 'payload'

// custom endpoint example
{
  path: '/:id/tracking',
  method: 'post',
  handler: async (req) => {
    return Response.json(
      { message: 'success' },
      {
        headers: headersWithCors({
          headers: new Headers(),
          req,
        })
      },
    )
  }
}

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

const res = await fetch(`${api}/${collectionSlug}`, {
  method: 'POST',
  credentials: 'include',
  headers: {
    'Accept-Language': i18n.language,
    'Content-Type': 'application/x-www-form-urlencoded',
    'X-HTTP-Method-Override': 'GET',
  },
  body: qs.stringify({
    depth: 1,
    locale: 'en',
  }),
})

Equivalent Regular GET Request

const res = await fetch(`${api}/${collectionSlug}?depth=1&locale=en`, {
  method: 'GET',
  credentials: 'include',
  headers: {
    'Accept-Language': i18n.language,
  },
})

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

overview.mdx

overview.mdx

Collections

Additional `find` query parameters

Auth Operations

Globals

Preferences

Custom Endpoints

Helpful tips

Method Override for GET Requests

How to Use

Example

Using Method Override (POST)

Equivalent Regular GET Request

Files

overview.mdx

Latest commit

History

overview.mdx

File metadata and controls

Collections

Additional `find` query parameters

Auth Operations

Globals

Preferences

Custom Endpoints

Helpful tips

Method Override for GET Requests

How to Use

Example

Using Method Override (POST)

Equivalent Regular GET Request