Payload is Good to agents.
Discry independently scored how well an AI agent can discover and understand the Payload API from what’s public — not whether it’s usable. Below: every signal we checked, what’s costing the score, and what to change.
SCORED UNDER RUBRIC 1.2 · A full re-launch under Discry Score 2.5 — a new behavioral instrument, not comparable to these scores — is in progress.
Discovery
45% of score · 71/100Comprehension
55% of score · 87/100What we found
- An agent can ingest Payload's entire documentation in clean markdown out of the box: both llms.txt (a structured, API-focused index) and a 1.7MB llms-full.txt (the full docs as markdown) are present, so no HTML scraping or guesswork is required.
- Payload actively invests in coding-agent support — a dedicated payloadcms/skills repo of agent skills, an AGENTS.md/CLAUDE.md in the main repo, and a create-payload-app --agent flag that installs the Payload skill for Claude/Codex/Cursor. This is rare and signals strong intent.
- An agent calling the REST API gets task-oriented endpoint tables, realistic copy-pasteable examples (real-looking IDs, dev@payloadcms.com), and a type-safe @payloadcms/sdk — the REST overview leads answer-first with method/path/purpose before details.
- The biggest discovery gap: there is no official, publicly accessible OpenAPI/Swagger spec. Because the REST API is auto-generated from each user's config, an agent cannot fetch a canonical machine-readable contract — only community plugins (payload-oapi, payload-swagger) generate per-instance specs.
- Capability boundaries and error recovery are documented inline (warning banners, APIError with 429 examples, try/catch patterns) rather than in a consolidated reference, so an agent must read across pages to learn what the API cannot do and how to recover from specific errors.
What to change
Prioritized by impact on discoverability. You (or your docs platform) deploy these — Discry never touches your API.
- 01Publish an official OpenAPI 3.1 spec (or document a first-party way to emit one from a config) and link it from the REST API docs — this is the single highest-impact discovery fix and the only failing check with weight 5.
- 02Add a .well-known/mcp.json now that an official MCP endpoint (/api/mcp) exists in Payload — declaring tools and auth at a discoverable path would let agents auto-detect MCP support instead of relying on third-party registry listings.
- 03Create a dedicated 'Errors & recovery' reference page documenting the JSON error response shape, the common HTTP status codes the auto-generated REST API returns, and explicit recovery guidance (e.g., what to do on 401/403/429) so agents can self-correct without trial and error.
- 04Add a consolidated 'Limits & boundaries' page (rate-limit defaults, query constraints like the join-field limitations currently buried in banners, payload/field size limits) so an agent learns constraints before failing.
- 05Promote a short, self-contained REST API quickstart at the top of llms.txt content so an agent can understand core CRUD + auth + query patterns in well under 5,000 tokens without traversing multiple pages.
Execution coverage · INFORMATIONAL, UNSCORED
Whether an agent can actually complete a call and recover from errors is the deeper Audit layer — documented here, but not part of the Discry Score.
Payload documents three complementary auth strategies (HTTP-only cookies, JWT, API keys) plus custom strategies, JSON error responses via the APIError class with explicit HTTP status codes, automatic offset/page pagination with rich meta (totalDocs, totalPages, page, limit), and configurable rate limiting. No idempotency-key support is documented. Note that Payload is a self-hosted framework that generates a per-instance REST API, so actual behavior depends on each deployment's config.