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).
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 in the result
populate - specifies which fields to include in the result from populated documents
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.
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:
1
importtype{CollectionConfig}from'payload'
2
3
// a collection of 'orders' with an additional route for tracking details, reachable at /api/orders/:id/tracking
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 and Hooks.
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
awaitaddDataAndFileToRequest(req)
9
await req.payload.update({
10
collection:'tracking',
11
data:{
12
// data to update the document with
13
}
14
})
15
returnResponse.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.
// you now can access req.locale & req.fallbackLocale
10
returnResponse.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.
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.
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.
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.
const res =awaitfetch(`${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.