{"id":51027057,"url":"https://github.com/matija2209/payload-plugin-api-guide","last_synced_at":"2026-06-21T20:30:25.883Z","repository":{"id":362499202,"uuid":"1258571172","full_name":"matija2209/payload-plugin-api-guide","owner":"matija2209","description":"Generate a live API reference and agent-first query guide for your Payload CMS project","archived":false,"fork":false,"pushed_at":"2026-06-04T12:45:41.000Z","size":346,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-06-04T14:15:56.847Z","etag":null,"topics":["ai-agents","api-documentation","llm","nextjs","openapi","payload","payload-cms","payload-plugin","typescript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/matija2209.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-06-03T17:52:53.000Z","updated_at":"2026-06-04T12:45:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/matija2209/payload-plugin-api-guide","commit_stats":null,"previous_names":["matija2209/payload-plugin-api-guide"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/matija2209/payload-plugin-api-guide","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matija2209%2Fpayload-plugin-api-guide","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matija2209%2Fpayload-plugin-api-guide/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matija2209%2Fpayload-plugin-api-guide/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matija2209%2Fpayload-plugin-api-guide/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/matija2209","download_url":"https://codeload.github.com/matija2209/payload-plugin-api-guide/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matija2209%2Fpayload-plugin-api-guide/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34625624,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-21T02:00:05.568Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","api-documentation","llm","nextjs","openapi","payload","payload-cms","payload-plugin","typescript"],"created_at":"2026-06-21T20:30:23.905Z","updated_at":"2026-06-21T20:30:25.872Z","avatar_url":"https://github.com/matija2209.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @matija2209/payload-agent-api-guide\n\nGenerate a live API reference and agent-first query guide from your Payload CMS configuration.\n\nThis 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.\n\n---\n\n## Why\n\nPayload'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`.\n\nThis plugin solves that by generating project-specific documentation directly from your Payload setup.\n\n---\n\n## Routes\n\nAll routes are served under `{payload.routes.api}/api-guide` (default: `/api/api-guide`).\n\n| Route | Description |\n|---|---|\n| `/api/api-guide` | Human-readable HTML guide |\n| `/api/api-guide/reference` | Interactive API browser (Scalar UI) |\n| `/api/api-guide/openapi.json` | OpenAPI 3.1 spec |\n| `/api/api-guide/agent.md` | Concise rules guide for AI coding agents |\n| `/api/api-guide/agent.json` | Structured project map (collections, fields, endpoints) |\n| `/api/api-guide/llms.txt` | LLM entry point with links to all resources |\n| `/api/api-guide/query-recipes.json` | Common query patterns per collection |\n\n---\n\n## Installation\n\n```bash\nnpm install @matija2209/payload-agent-api-guide\n# or\npnpm add @matija2209/payload-agent-api-guide\n```\n\n**Peer dependency:** `payload \u003e= 3.85.0`\n\n---\n\n## Usage\n\n```ts\nimport { buildConfig } from 'payload'\nimport { apiGuidePlugin } from '@matija2209/payload-agent-api-guide'\n\nexport default buildConfig({\n  plugins: [\n    apiGuidePlugin({\n      title: 'My Project API Guide',\n    }),\n  ],\n  // ...rest of config\n})\n```\n\n---\n\n## Options\n\n```ts\ntype ApiGuidePluginOptions = {\n  /** Disable the plugin without removing it. Default: true */\n  enabled?: boolean\n\n  /** Base path under the Payload API route. Default: '/api-guide' */\n  basePath?: string\n\n  /** Title shown in the HTML guide and OpenAPI spec. Default: 'Payload API Guide' */\n  title?: string\n\n  /** Include auth-enabled collections. Default: true */\n  includeAuth?: boolean\n}\n```\n\n---\n\n## What gets generated\n\n### From your collections\n\nFor each collection the plugin reads:\n\n- slug, labels (singular/plural)\n- all field names, types, required status, localization\n- relationship fields and their targets\n- upload fields\n- whether a `slug` field exists (for slug-based fetch recipes)\n- whether drafts are enabled\n- whether auth is enabled\n- whether it is an upload collection\n\n### From your globals\n\nFor each global:\n\n- slug, label\n- all field names and types\n\n### Generated outputs\n\n**`/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.\n\n**`/api/api-guide/reference`** — Scalar UI loaded from CDN, pointed at the generated OpenAPI spec.\n\n**`/api/api-guide/openapi.json`** — A complete OpenAPI 3.1 spec with:\n- Paths for every collection (`GET`, `POST`, `PATCH`, `DELETE`) and global (`GET`, `POST`)\n- Slug-based fetch path for collections that have a `slug` field\n- Shared query parameter components (`where`, `depth`, `select`, `limit`, `page`, `sort`, `locale`, `draft`)\n- Schema components per collection derived from field definitions\n\n**`/api/api-guide/agent.md`** — A markdown guide written for AI coding agents. Includes:\n- Critical rules (slug fetch pattern, qs-esm usage, depth, select, pagination)\n- `qs-esm` code example\n- Per-collection field tables and fetch examples\n- Common mistakes table\n\n**`/api/api-guide/agent.json`** — A structured JSON project map. Includes:\n- `apiBase`, `collections`, `globals`\n- Per-collection: field list, endpoint URLs, slug field name, draft/auth/upload traits\n- `queryGuide` block explaining Payload REST conventions in machine-readable form\n\n**`/api/api-guide/llms.txt`** — An entry-point file for LLMs following the [llms.txt](https://llmstxt.org) convention. Lists all generated resources with links.\n\n**`/api/api-guide/query-recipes.json`** — An array of concrete query recipes per collection:\n- List documents\n- Fetch by ID\n- Fetch by slug (where-based)\n- Paginated fetch\n- Fetch only published (for draft-enabled collections)\n- Fetch with populated relationships\n- Fetch with selected fields only\n- Fetch global\n\n---\n\n## Agent workflow\n\nThe recommended agent workflow when entering a Payload project with this plugin:\n\n1. Read `/api/api-guide/llms.txt` for an overview of available resources\n2. Read `/api/api-guide/agent.md` for the rules of how to query this project\n3. Inspect `/api/api-guide/agent.json` for collections, fields, and endpoint patterns\n4. Use `/api/api-guide/openapi.json` for formal endpoint reference\n5. Write fetch code using the project-specific field names and query patterns\n\n---\n\n## Key rule\n\n\u003e Never fetch by slug as a path segment.\n\nThis is the most common Payload REST mistake:\n\n```ts\n// Wrong — returns 404 or wrong data\nfetch('/api/posts/my-slug')\n\n// Correct — use where query\nfetch('/api/posts?where[slug][equals]=my-slug\u0026limit=1')\n  .then(r =\u003e r.json())\n  .then(({ docs }) =\u003e docs[0])\n```\n\nUse [`qs-esm`](https://www.npmjs.com/package/qs-esm) to build `where` queries safely:\n\n```ts\nimport qs from 'qs-esm'\n\nconst query = qs.stringify({\n  where: { slug: { equals: 'my-post' } },\n  depth: 1,\n  limit: 1,\n})\nconst res = await fetch(`/api/posts?${query}`)\nconst { docs } = await res.json()\nconst post = docs[0]\n```\n\n---\n\n## Requirements\n\n- Payload `\u003e= 3.85.0`\n- Node.js `\u003e= 18.20.2`\n\n---\n\n## Release process\n\nThe package is intended to publish compiled output from `dist/`.\n\nBefore publishing locally:\n\n```bash\npnpm install\npnpm build\npnpm test:int\nnpm pack --dry-run\nnpm publish --dry-run\n```\n\nFor the first public release, publish manually:\n\n```bash\nnpm publish --access public\n```\n\nAfter the package exists on npm, configure npm trusted publishing for\n`@matija2209/payload-agent-api-guide` and use the GitHub Actions workflows in\n`.github/workflows/`.\n\nRecommended release flow:\n\n1. Open a PR and let `.github/workflows/ci.yml` run build, lint, integration tests, and e2e.\n2. Bump `package.json` to the next version and commit it.\n3. Create a matching tag like `v1.0.1`.\n4. Push the commit and the tag.\n5. `.github/workflows/publish.yml` publishes only if the tag matches the package version exactly.\n\n---\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatija2209%2Fpayload-plugin-api-guide","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmatija2209%2Fpayload-plugin-api-guide","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatija2209%2Fpayload-plugin-api-guide/lists"}