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
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.
Payload is available anywhere you have access to the Express
req - including within your access control and hook functions.
You can specify more options within the Local API vs. REST or GraphQL due to the server-only context that they are executed in.
|Required for Collection operations. Specifies the Collection slug to operate against.|
|The data to use within the operation. Required for |
|Control auto-population of nested relationship and upload fields.|
|Specify locale for any returned documents.|
|Specify a fallback locale to use for any returned documents.|
|Skip access control. By default, this property is set to true within all Local API operations.|
|If you set |
|Opt-in to receiving hidden fields. By default, they are hidden from returned documents in accordance to your config.|
|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:
Local API calls also support passing in a generic. This is especially useful if you generate your TS types using a generate types script.
Here is an example of usage: