You are currently viewing documentation for version 2 of Payload.
Local API
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.
Tip:
The Local API is incredibly powerful when used with server-side rendering app frameworks like NextJS. With other headless CMS, you need to request your data from third-party servers which can add significant loading time to your server-rendered pages. With Payload, you don't have to leave your server to gather the data you need. It can be incredibly fast and is definitely a game changer.
Here are some common examples of how you can use the Local API:
Seeding data via Node seed scripts that you write and maintain
Opening custom Express routes which feature additional functionality but still rely on Payload
Within access control and hook functions
Accessing payload
You can gain access to the currently running payload object via two ways:
Importing it
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.
Specify a fallback locale to use for any returned documents.
overrideAccess
Skip access control. By default, this property is set to true within all Local API operations.
user
If you set overrideAccess to false, you can pass 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.
context
Context, which will then be passed to context and req.context, which can be read by hooks. Useful if you want to pass additional information to the hooks which shouldn't be necessarily part of the document, for example a triggerBeforeChange option which can be read by the BeforeChange hook to determine if it should run or not.
There are more options available on an operation by operation basis outlined below.
Note:
By default, all access control checks are disabled in the Local API, but you can re-enable them if you'd like, as well as pass a specific user to run the operation with.
Collections
The following Collection operations are available through the Local API:
Create
1
// The created Post document is returned
2
const post =await payload.create({
3
collection:'posts',// required
4
data:{
5
// required
6
title:'sure',
7
description:'maybe',
8
},
9
locale:'en',
10
fallbackLocale:false,
11
user: dummyUserDoc,
12
overrideAccess:true,
13
showHiddenFields:false,
14
15
// If creating verification-enabled auth doc,
16
// you can optionally disable the email that is auto-sent
17
disableVerificationEmail:true,
18
19
// If your collection supports uploads, you can upload
20
// a file directly through the Local API by providing
// If you are uploading a file and would like to replace
30
// the existing file instead of generating a new filename,
31
// you can set the following property to `true`
32
overwriteExistingFiles:true,
33
})
Delete
1
// Result will be the now-deleted Post document.
2
const result =await payload.delete({
3
collection:'posts',// required
4
id:'507f1f77bcf86cd799439011',// required
5
depth:2,
6
locale:'en',
7
fallbackLocale:false,
8
user: dummyUser,
9
overrideAccess:false,
10
showHiddenFields:true,
11
})
Delete Many
1
// Result will be an object with:
2
// {
3
// docs: [], // each document that is now deleted
4
// errors: [], // any errors that occurred, including the id of the errored on document
5
// }
6
const result =await payload.delete({
7
collection:'posts',// required
8
where:{
9
// required
10
fieldName:{equals:'value'},
11
},
12
depth:0,
13
locale:'en',
14
fallbackLocale:false,
15
user: dummyUser,
16
overrideAccess:false,
17
showHiddenFields:true,
18
})
Auth Operations
If a collection has Authentication enabled, additional Local API operations will be available:
Login
1
// result will be formatted as follows:
2
// {
3
// token: 'o38jf0q34jfij43f3f...', // JWT used for auth
4
// user: { ... } // the user document that just logged in
5
// exp: 1609619861 // the UNIX timestamp when the JWT will expire
6
// }
7
8
const result =await payload.login({
9
collection:'users',// required
10
data:{
11
// required
12
email:'dev@payloadcms.com',
13
password:'rip',
14
},
15
req: req,// pass an Express `req` which will be provided to all hooks
16
res: res,// used to automatically set an HTTP-only auth cookie
17
depth:2,
18
locale:'en',
19
fallbackLocale:false,
20
overrideAccess:false,
21
showHiddenFields:true,
22
})
Forgot Password
1
// Returned token will allow for a password reset
2
const token =await payload.forgotPassword({
3
collection:'users',// required
4
data:{
5
// required
6
email:'dev@payloadcms.com',
7
},
8
req: req,// pass an Express `req` which will be provided to all hooks
9
})
Reset Password
1
// Result will be formatted as follows:
2
// {
3
// token: 'o38jf0q34jfij43f3f...', // JWT used for auth
4
// user: { ... } // the user document that just logged in
5
// }
6
const result =await payload.resetPassword({
7
collection:'users',// required
8
data:{
9
// required
10
password: req.body.password,// the new password to set
11
token:'afh3o2jf2p3f...',// the token generated from the forgotPassword operation
12
},
13
req: req,// pass an Express `req` which will be provided to all hooks
14
res: res,// used to automatically set an HTTP-only auth cookie
15
})
Unlock
1
// Returned result will be a boolean representing success or failure
2
const result =await payload.unlock({
3
collection:'users',// required
4
data:{
5
// required
6
email:'dev@payloadcms.com',
7
},
8
req: req,// pass an Express `req` which will be provided to all hooks
9
overrideAccess:true,
10
})
Verify
1
// Returned result will be a boolean representing success or failure
2
const result =await payload.verifyEmail({
3
collection:'users',// required
4
token:'afh3o2jf2p3f...',// the token saved on the user as `_verificationToken`
5
})
Globals
The following Global operations are available through the Local API:
Find
1
// Result will be the Header Global.
2
const result =await payload.findGlobal({
3
slug:'header',// required
4
depth:2,
5
locale:'en',
6
fallbackLocale:false,
7
user: dummyUser,
8
overrideAccess:false,
9
showHiddenFields:true,
10
})
Update
1
// Result will be the updated Header Global.
2
const result =await payload.updateGlobal({
3
slug:'header',// required
4
data:{
5
// required
6
nav:[
7
{
8
url:'https://google.com',
9
},
10
{
11
url:'https://payloadcms.com',
12
},
13
],
14
},
15
depth:2,
16
locale:'en',
17
fallbackLocale:false,
18
user: dummyUser,
19
overrideAccess:false,
20
showHiddenFields:true,
21
})
Next.js Conflict with Local API
There is a known issue when using the Local API with Next.js version 13.4.13 and higher. Next.js executes within a separate child process, and Payload has not been initalized yet in these instances. That means that unless you explicitly initialize Payload within your operation, it will not be running and return no data / an empty object.
As a workaround, we recommend leveraging the following pattern to determine and ensure Payload is initalized: