payload plugin api guide

@matija2209/payload-agent-api-guide

Generate a live API reference and agent-first query guide from your Payload CMS configuration.

This plugin reads your live Payload config and turns it into practical API documentation, an OpenAPI reference, and agent-readable instructions — so developers and AI coding agents can understand how to query your project without guessing.

---

Why

Payload's REST API is powerful, but beginners and AI agents often get the details wrong. They may assume generic REST patterns — for example, fetching a post by slug with /api/posts/my-slug — instead of using Payload's actual query syntax with where.slug.equals.

This plugin solves that by generating project-specific documentation directly from your Payload setup.

---

Routes

All routes are served under {payload.routes.api}/api-guide (default: /api/api-guide).

Route	Description
/api/api-guide	Human-readable HTML guide
/api/api-guide/reference	Interactive API browser (Scalar UI)
/api/api-guide/openapi.json	OpenAPI 3.1 spec
/api/api-guide/agent.md	Concise rules guide for AI coding agents
/api/api-guide/agent.json	Structured project map (collections, fields, endpoints)
/api/api-guide/llms.txt	LLM entry point with links to all resources
/api/api-guide/query-recipes.json	Common query patterns per collection

---

Installation

npm install @matija2209/payload-agent-api-guide
# or
pnpm add @matija2209/payload-agent-api-guide

Peer dependency: payload >= 3.85.0

---

Usage

import { buildConfig } from 'payload'
import { apiGuidePlugin } from '@matija2209/payload-agent-api-guide'

export default buildConfig({
  plugins: [
    apiGuidePlugin({
      title: 'My Project API Guide',
    }),
  ],
  // ...rest of config
})

---

Options

type ApiGuidePluginOptions = {
  /** Disable the plugin without removing it. Default: true */
  enabled?: boolean

  /** Base path under the Payload API route. Default: '/api-guide' */
  basePath?: string

  /** Title shown in the HTML guide and OpenAPI spec. Default: 'Payload API Guide' */
  title?: string

  /** Include auth-enabled collections. Default: true */
  includeAuth?: boolean
}

---

What gets generated

From your collections

For each collection the plugin reads:

• slug, labels (singular/plural)
• all field names, types, required status, localization
• relationship fields and their targets
• upload fields
• whether a slug field exists (for slug-based fetch recipes)
• whether drafts are enabled
• whether auth is enabled
• whether it is an upload collection

From your globals

For each global:

• slug, label
• all field names and types

Generated outputs

/api/api-guide — A self-contained HTML page explaining how to use the REST API for this specific project. Includes field tables per collection, fetch examples, and a common-mistakes section.

/api/api-guide/reference — Scalar UI loaded from CDN, pointed at the generated OpenAPI spec.

/api/api-guide/openapi.json — A complete OpenAPI 3.1 spec with:

• Paths for every collection (GET, POST, PATCH, DELETE) and global (GET, POST)
• Slug-based fetch path for collections that have a slug field
• Shared query parameter components (where, depth, select, limit, page, sort, locale, draft)
• Schema components per collection derived from field definitions

/api/api-guide/agent.md — A markdown guide written for AI coding agents. Includes:

• Critical rules (slug fetch pattern, qs-esm usage, depth, select, pagination)
• qs-esm code example
• Per-collection field tables and fetch examples
• Common mistakes table

/api/api-guide/agent.json — A structured JSON project map. Includes:

• apiBase, collections, globals
• Per-collection: field list, endpoint URLs, slug field name, draft/auth/upload traits
• queryGuide block explaining Payload REST conventions in machine-readable form

/api/api-guide/llms.txt — An entry-point file for LLMs following the llms.txt convention. Lists all generated resources with links.

/api/api-guide/query-recipes.json — An array of concrete query recipes per collection:

• List documents
• Fetch by ID
• Fetch by slug (where-based)
• Paginated fetch
• Fetch only published (for draft-enabled collections)
• Fetch with populated relationships
• Fetch with selected fields only
• Fetch global

---

Agent workflow

The recommended agent workflow when entering a Payload project with this plugin:

1. Read /api/api-guide/llms.txt for an overview of available resources
2. Read /api/api-guide/agent.md for the rules of how to query this project
3. Inspect /api/api-guide/agent.json for collections, fields, and endpoint patterns
4. Use /api/api-guide/openapi.json for formal endpoint reference
5. Write fetch code using the project-specific field names and query patterns

---

Key rule

Never fetch by slug as a path segment.

This is the most common Payload REST mistake:

// Wrong — returns 404 or wrong data
fetch('/api/posts/my-slug')

// Correct — use where query
fetch('/api/posts?where[slug][equals]=my-slug&limit=1')
  .then(r => r.json())
  .then(({ docs }) => docs[0])

Use qs-esm to build where queries safely:

import qs from 'qs-esm'

const query = qs.stringify({
  where: { slug: { equals: 'my-post' } },
  depth: 1,
  limit: 1,
})
const res = await fetch(`/api/posts?${query}`)
const { docs } = await res.json()
const post = docs[0]

---

Requirements

• Payload >= 3.85.0
• Node.js >= 18.20.2

---

Release process

The package is intended to publish compiled output from dist/.

Before publishing locally:

pnpm install
pnpm build
pnpm test:int
npm pack --dry-run
npm publish --dry-run

For the first public release, publish manually:

npm publish --access public

After the package exists on npm, configure npm trusted publishing for @matija2209/payload-agent-api-guide and use the GitHub Actions workflows in .github/workflows/.

Recommended release flow:

1. Open a PR and let .github/workflows/ci.yml run build, lint, integration tests, and e2e.
2. Bump package.json to the next version and commit it.
3. Create a matching tag like v1.0.1.
4. Push the commit and the tag.
5. .github/workflows/publish.yml publishes only if the tag matches the package version exactly.

---

License

MIT