The Payload Local API gives you the ability to execute the same operations that are available through REST and GraphQL within Node, directly on your server. Here, you don't need to deal with server latency or network speed whatsoever and can interact directly with your database.
Here are some common examples of how you can use the Local API:
You can gain access to the currently running payload
object via two ways:
You can import or require payload
into your own files after it's been initialized, but you need to make sure that your import
/ require
statements come after you call payload.init()
—otherwise Payload won't have been initialized yet. That might be obvious. To us, it's usually not.
Example:
import payload from 'payload';const afterChangeHook = async () => {const posts = await payload.find({collection: 'posts',});}
req
Payload is available anywhere you have access to the Express req
- including within your access control and hook functions.
Example:
const afterChangeHook = async ({ req: { payload }}) => {const posts = await payload.find({collection: 'posts',});}
You can specify more options within the Local API vs. REST or GraphQL due to the server-only context that they are executed in.
Local Option | Description |
---|---|
collection | Required for Collection operations. Specifies the Collection slug to operate against. |
data | The data to use within the operation. Required for create , update . |
depth | Control auto-population of nested relationship and upload fields. |
locale | Specify locale for any returned documents. |
fallbackLocale | Specify a fallback locale to use for any returned documents. |
overrideAccess | Skip access control. By default, this property is set to false. |
user | If you re-enable access control, you can specify a user to use against the access control checks. |
showHiddenFields | Opt-in to receiving hidden fields. By default, they are hidden from returned documents in accordance to your config. |
pagination | Set to false to return all documents and avoid querying for document counts. |
There are more options available on an operation by operation basis outlined below.
The following Collection operations are available through the Local API:
// The created Post document is returnedconst post = await payload.create({collection: 'posts', // requireddata: { // requiredtitle: 'sure',description: 'maybe',},locale: 'en',fallbackLocale: false,user: dummyUserDoc,overrideAccess: true,showHiddenFields: false,// If creating verification-enabled auth doc,// you can optionally disable the email that is auto-sentdisableVerificationEmail: true,// If your collection supports uploads, you can upload// a file directly through the Local API by providing// its full, absolute file path.filePath: path.resolve(__dirname, './path-to-image.jpg'),})
// Result will be a paginated set of Posts.// See /docs/queries/pagination for more.const result = await payload.find({collection: 'posts', // requireddepth: 2,page: 1,limit: 10,where: {}, // pass a `where` query heresort: '-title',locale: 'en',fallbackLocale: false,user: dummyUser,overrideAccess: false,showHiddenFields: true,})
// Result will be a Post document.const result = await payload.findByID({collection: 'posts', // requiredid: '507f1f77bcf86cd799439011', // requireddepth: 2,locale: 'en',fallbackLocale: false,user: dummyUser,overrideAccess: false,showHiddenFields: true,})
// Result will be the updated Post document.const result = await payload.update({collection: 'posts', // requiredid: '507f1f77bcf86cd799439011', // requireddata: { // requiredtitle: 'sure',description: 'maybe',},depth: 2,locale: 'en',fallbackLocale: false,user: dummyUser,overrideAccess: false,showHiddenFields: true,// If your collection supports uploads, you can upload// a file directly through the Local API by providing// its full, absolute file path.filePath: path.resolve(__dirname, './path-to-image.jpg'),// If you are uploading a file and would like to replace// the existing file instead of generating a new filename,// you can set the following property to `true`overwriteExistingFiles: true,})
// Result will be the now-deleted Post document.const result = await payload.delete({collection: 'posts', // requiredid: '507f1f77bcf86cd799439011', // requireddepth: 2,locale: 'en',fallbackLocale: false,user: dummyUser,overrideAccess: false,showHiddenFields: true,})
If a collection has Authentication
enabled, additional Local API operations will be available:
// result will be formatted as follows:// {// token: 'o38jf0q34jfij43f3f...', // JWT used for auth// user: { ... } // the user document that just logged in// exp: 1609619861 // the UNIX timestamp when the JWT will expire// }const result = await payload.login({collection: 'users', // requireddata: { // requiredemail: 'dev@payloadcms.com',password: 'rip',},req: req, // pass an Express `req` which will be provided to all hooksres: res, // used to automatically set an HTTP-only auth cookiedepth: 2,locale: 'en',fallbackLocale: false,overrideAccess: false,showHiddenFields: true,})
// Returned token will allow for a password resetconst token = await payload.forgotPassword({collection: 'users', // requireddata: { // requiredemail: 'dev@payloadcms.com',},req: req, // pass an Express `req` which will be provided to all hooks})
// Result will be formatted as follows:// {// token: 'o38jf0q34jfij43f3f...', // JWT used for auth// user: { ... } // the user document that just logged in// }const result = await payload.forgotPassword({collection: 'users', // requireddata: { // requiredtoken: 'afh3o2jf2p3f...', // the token generated from the forgotPassword operation},req: req, // pass an Express `req` which will be provided to all hooksres: res, // used to automatically set an HTTP-only auth cookie})
// Returned result will be a boolean representing success or failureconst result = await payload.unlock({collection: 'users', // requireddata: { // requiredemail: 'dev@payloadcms.com',},req: req, // pass an Express `req` which will be provided to all hooksoverrideAccess: true,})
// Returned result will be a boolean representing success or failureconst result = await payload.verify({collection: 'users', // requiredtoken: 'afh3o2jf2p3f...', // the token saved on the user as `_verificationToken`})
The following Global operations are available through the Local API:
// Result will be the Header Global.const result = await payload.findGlobal({slug: 'header', // requireddepth: 2,locale: 'en',fallbackLocale: false,user: dummyUser,overrideAccess: false,showHiddenFields: true,})
// Result will be the updated Header Global.const result = await payload.updateGlobal({slug: 'header', // requireddata: { // requirednav: [{url: 'https://google.com',},{url: 'https://payloadcms.com',},],},depth: 2,locale: 'en',fallbackLocale: false,user: dummyUser,overrideAccess: false,showHiddenFields: true,})