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:
req
Payload is available anywhere you have access to the Express req
- including within your access control and hook functions.
Example:
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 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. |
queryHiddenFields | Allow querying by hidden fields. By default, hidden fields are not allowed to be queried on. |
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:
If a collection has Authentication
enabled, additional Local API operations will be available:
The following Global operations are available through the Local API:
The Local API is especially useful for running scripts
Local API calls will automatically infer your generated types.
Here is an example of usage: