canonical: https://jentic.com/apis/payloadcms.com/payloadcms # Payloadcms Payload Headless CMS API Jentic publishes the only available OpenAPI specification for Payload Headless CMS API, keeping it validated and agent-ready. The Payload CMS REST API provides a generic pattern for managing any collection defined in your Payload project. It supports finding, creating, updating, and deleting documents across all collections, plus built-in authentication with JWT tokens and HTTP-only cookies. Global configuration endpoints allow reading and updating singleton data like site settings or navigation menus. ## For AI agents Manage content collections, authenticate users, and access global configurations in self-hosted Payload CMS instances through a unified REST interface. ## Scope Does not handle media processing, email delivery, or deployment orchestration - use for content management, authentication, and collection operations only. ## Capabilities - Query and filter documents across any user-defined collection with pagination - Create and update content documents with full field validation - Authenticate users via JWT tokens and manage sessions with refresh and logout - Read and update global configuration objects like site settings - Handle password reset flows with forgot-password and reset-password endpoints - Retrieve the currently authenticated user's profile and permissions ## Use cases ### Headless Content Management Manage structured content for websites, mobile apps, or digital products through the REST API. Payload's collection-based architecture means every content type you define gets full CRUD endpoints automatically. Documents support rich text, relationships, media uploads, and localization fields, making it suitable for multi-site or multi-language content delivery. Example prompt: Create a new blog post document in the 'posts' collection with title, body, and published status set to true via POST /{collection} ### User Authentication and Access Control Payload includes built-in authentication for any collection marked as auth-enabled. The API handles login, logout, token refresh, password reset, and session management using JWT bearer tokens or HTTP-only cookies. This supports role-based access control without needing a separate identity provider. Example prompt: Authenticate a user via POST /{collection}/login with email and password, then retrieve the user profile using GET /{collection}/me with the returned JWT token ### Content Querying and Filtering Query documents across collections using Payload's query operators for filtering, sorting, pagination, and field selection. The API supports nested field queries, relationship population, and locale-specific content retrieval. Ideal for building search pages, content feeds, or filtered catalogs driven by user input. Example prompt: Query the 'products' collection for all documents where status equals 'active' with pagination limit of 10 and sort by createdAt descending via GET /{collection} ### AI Agent Content Operations via Jentic AI agents use Jentic to perform content operations on Payload CMS instances without managing JWT token lifecycles or constructing complex query parameters manually. Jentic provides intent-based discovery so agents find operations like 'create a document' or 'query a collection' and receive validated schemas for immediate execution. Example prompt: Search Jentic for 'create a document in a CMS collection', load the operation schema, and execute it to create a new page in the 'pages' collection ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | `/{collection}` | Find documents in a collection with query filters | | POST | `/{collection}` | Create a new document in a collection | | GET | `/{collection}/{id}` | Retrieve a document by ID | | PATCH | `/{collection}/{id}` | Update a document by ID | | DELETE | `/{collection}/{id}` | Delete a document by ID | | POST | `/{collection}/login` | Authenticate and receive a JWT token | | GET | `/{collection}/me` | Get the currently authenticated user | | GET | `/globals/{global_slug}` | Read a global configuration object | ## Key resources - **Collections** — Generic CRUD operations on any user-defined collection (find, create, update, delete) - **Authentication** — Login, logout, token refresh, password reset, and current user retrieval - **Globals** — Read and update singleton global configuration objects ## Why Jentic - **Setup:** Wiring Payload by hand means handling its bearer or cookie token auth, pointing at your own self-hosted domain, and mapping dynamic collection and global routes yourself. Through Jentic you install once, import the Payload Headless CMS API from the API Directory, store the token once, and your agent calls it. - **Permission scoping:** Payload puts the collection and document id in the URL path (/{collection}/{id}), so a rule can pin your agent to reading one collection: it can fetch and list those documents and nothing else. You choose the operations it may call, so update and delete are not included unless you add them. - **Credential handling:** Your Payload token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'create a document in a collection' or 'fetch a global's content', and Jentic returns the matching Payload operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Contentful API** — Cloud-hosted headless CMS with CDN delivery and structured content modeling - **Sanity API** — Real-time headless CMS with GROQ query language and collaborative editing - **Stripe API** — Payment processing for e-commerce sites built with headless CMS frontends ## FAQ ### Why is there no official OpenAPI spec for Payload Headless CMS API? Payload CMS does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Payload Headless CMS API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer. ### What authentication does the Payload CMS API use? Payload CMS supports two authentication methods: JWT bearer tokens passed in the Authorization header, and HTTP-only cookies named payload-token set during login. Both are obtained from the POST /{collection}/login endpoint. Through Jentic, JWT tokens are managed automatically in your Jentic One instance. ### Can I query documents with filters using the Payload CMS API? Yes. The GET /{collection} endpoint supports query parameters for filtering by any field, sorting, pagination with limit and page parameters, and depth control for relationship population. Query operators include equals, not_equals, greater_than, less_than, like, contains, and exists. ### Does the Payload CMS API work with any collection type? Yes. The API uses a generic pattern where {collection} in the URL maps to any collection slug defined in your Payload configuration. Whether you have posts, products, users, or custom types, the same endpoints apply. The response schema adapts to the fields defined in each collection. ### How do I create content in Payload CMS through Jentic? Search Jentic for 'create a document in a CMS collection' to find the POST /{collection} operation. Jentic returns the input schema showing the collection path parameter and the document body fields. Provide your collection slug and document data, and Jentic handles authentication and request execution. Install with pip install jentic. ### Can I manage global settings through the API? Yes. The GET `/globals/{global_slug}` endpoint retrieves any global configuration defined in your Payload project, such as site settings, navigation menus, or footer content. You can update globals with a PATCH request to the same endpoint. Globals are singleton objects that exist outside of collections. ### Can I limit what my agent is allowed to do with the Payload CMS API? Yes. Because Jentic One is self-hosted and runs under your own rules, you decide which Payload operations and which stored token your agent may use. Payload places the collection and document id in the URL path (/{collection}/{id}), so a rule can pin the agent to reading a single collection, letting it fetch and list those documents and nothing else. Update and delete operations stay out of reach unless you explicitly add them, so the agent never writes to or removes content you did not grant.