agents-store PayloadCMS — API Reference
Endpoint-by-endpoint reference. Triggered only on explicit user request — heavy content lives in references/ files below.
Three API Surfaces
| Surface | Endpoint | When to use |
|---|---|---|
| Local API | In-process JS calls (payload.find, …) |
Server-side code, hooks, scripts, server components |
| REST API | /api/<collection>/... |
Browser fetch, external services, mobile apps |
| GraphQL | /api/graphql |
Typed frontends, codegen pipelines, federation |
All three share the same where query syntax, access control rules, and hook firing order.
Typed external client: @payloadcms/sdk — the official REST SDK (same 3.x version line) for browser/service callers; mirrors Local API options over HTTP.
Reference Files
references/local-api.md— every method on thepayloadinstance with full TypeScript signatures.references/rest-api.md— every REST route grouped by collection-CRUD, globals, auth, uploads, versions, jobs.references/graphql-api.md— auto-generated schema rules, query/mutation patterns, custom resolvers.
Auth Headers (cross-API)
| Header | Purpose |
|---|---|
Authorization: JWT <token> |
Authenticate as a user. Token comes from /api/<auth-collection>/login. |
Authorization: <api-key-collection> API-Key <key> |
API key auth (when auth.useAPIKey: true). |
Cookie: payload-token=<jwt> |
HTTP-only cookie set by /login. Browser sessions use this. |
Base URL
The Payload server URL is the Next.js dev/prod URL — typically:
- Dev:
http://localhost:3000 - Prod:
https://your-app.com
All routes shown in references are relative to that base.
Common Query Parameters (REST)
| Param | Type | Example |
|---|---|---|
where |
JSON-encoded object | ?where[status][equals]=published |
sort |
string | ?sort=-publishedAt,title |
limit |
number | ?limit=50 |
page |
number | ?page=2 |
depth |
0–10 | ?depth=2 |
select |
object | ?select[title]=true&select[slug]=true |
locale |
string | ?locale=es |
fallback-locale |
string | ?fallback-locale=en |
draft |
boolean | ?draft=true |
Use the qs-esm library (Payload-maintained) to encode complex where clauses from the browser.
Error Format
REST/GraphQL errors return:
{
"errors": [
{ "message": "You are not allowed to perform this action.", "name": "Forbidden" }
]
}
HTTP status codes: 400 (validation), 401 (auth missing), 403 (access denied), 404 (not found), 500 (server).
Local API throws typed APIError / ValidationError instances — catch and inspect .status / .name.
Don't Hardcode URLs
Inside generated app code, prefer the alias:
import config from '@payload-config'
const payload = await getPayload({ config })
For external clients, read base URL from env (NEXT_PUBLIC_PAYLOAD_URL). Never hardcode localhost or production hosts in committed code.
This skill has disable-model-invocation: true — Claude will not auto-trigger it. Users must reference it explicitly ("show me the REST endpoint for…") or another skill must link to it. See the linked reference files for the full content.