\n\nThe official OpenAPI 3.1 specification for the ApostropheCMS REST API. Explore endpoints interactively, mock the API for rapid prototyping, or generate type-safe SDKs in your preferred language.\n\n---\n\n## What This Is (And Isn't)\n\nThis repository contains the **core ApostropheCMS OpenAPI specification** - the base REST API that every Apostrophe project inherits. It documents standard endpoints for pages, pieces, assets, users, and workflow management.\n\n**Think of it as the foundation, not the complete building.** Your project likely has custom piece types (like products, events, or blog posts) and project-specific routes that aren't included here.\n\n> ⚠️ **Important**: This repository contains the API specification, not ApostropheCMS itself. For the CMS, visit the [main ApostropheCMS repository](https://github.com/apostrophecms/apostrophe).\n\n### For Your Own Project\n\nTo generate a specification that includes **both** core and your custom modules:\n\n1. Install [@apostrophecms/openapi-generator](https://github.com/apostrophecms/openapi-generator) in your Apostrophe project\n2. Run the generator from your project directory \n3. Use the generated specification for SDK creation and documentation specific to your application\n\n### For Exploring Core ApostropheCMS\n\nUse this repository to:\n\n- **Explore the API** - Browse all core endpoints in interactive documentation\n- **Design API contracts** - Use as a foundation for planning new projects and features\n- **Mock for prototyping** - Build frontend apps before your backend is ready\n- **Generate SDKs** - Create client libraries in TypeScript, Python, PHP, and more\n- **Learn conventions** - Understand ApostropheCMS API patterns and best practices\n\n---\n\n## Getting Started\n\n### Explore the API Interactively\n\nView the complete API documentation with Swagger UI:\n\n```bash\n# Install dependencies\nnpm install\n\n# Open interactive documentation\nnpm run docs:open\n```\n\nThis opens a browser interface where you can browse endpoints, view schemas, and test API calls.\n\n> **Note**: You will have to have an ApostropheCMS project running before testing the endpoints.\n\n### Authenticate for Testing\n\nYou can authenticate in Swagger UI using either an API key or bearer token:\n\n#### Option 1: API Key (Recommended)\n\nThe simplest method - requires one-time setup in your project:\n\n1. **Add an API key** to your ApostropheCMS project in `modules/@apostrophecms/express/index.js`:\n\n```javascript\nexport default {\n options: {\n apiKeys: {\n myTestKey: {\n role: 'admin'\n }\n }\n }\n};\n```\n\n2. **In Swagger UI**: Click \"Authorize\" → scroll to \"ApiKeyAuth\" → enter `myTestKey`\n\n3. **Test away**: Execute requests directly from the documentation\n\n#### Option 2: Bearer Token\n\nNo project configuration needed - use your existing login credentials:\n\n1. **Generate a token**: In Swagger UI, find the `POST /@apostrophecms/login/login` endpoint and execute it with:\n\n```json\n{\n \"username\": \"your-username\",\n \"password\": \"your-password\"\n}\n```\n\n2. **Copy the token**: From the response, copy **only the token value** (not the full JSON). \n - Example: if response is `{\"token\": \"abc123xyz\"}`, copy only `abc123xyz`\n\n3. **Authorize**: Click \"Authorize\" → scroll to \"BearerAuth\" → paste the token value\n\nThe token will be automatically sent as `Authorization: Bearer {your-token}` with each request.\n\n---\n\n## API-First Development\n\nUse this specification to design and prototype before writing code - perfect for parallel frontend/backend development.\n\n### Design Your API Contract\n\nWhen starting a new project or feature:\n\n1. **Start with the core spec** as your foundation\n2. **Manually add your custom endpoints** following the same patterns used in the core spec\n3. **Share the spec** with your team as the contract between frontend and backend\n4. **Develop in parallel** - frontend uses mocks, backend implements to match the spec\n\n### Mock the API\n\nCreate a fully functional mock server without any backend code:\n\n```bash\n# Install Prism globally\nnpm install -g @stoplight/prism-cli\n\n# Mock the core API\nprism mock apostrophecms-openapi.yaml\n\n# Or mock your project-specific spec\nprism mock my-project-openapi.yaml\n\n# Mock server runs at http://localhost:4010\n```\n\nThe mock server returns realistic example responses, letting frontend developers build and test their applications before the backend is ready.\n\n**Use cases:**\n- Prototype new features without backend changes\n- Frontend development while backend is in progress \n- Demo UIs to stakeholders before implementation\n- Test frontend error handling and edge cases\n\n> **Note:** The [@apostrophecms/openapi-generator](https://github.com/apostrophecms/openapi-generator) generates documentation for *existing* ApostropheCMS projects - it documents what you've already built. For true API-first design, you'd manually extend this core spec before implementation.\n\n---\n\n## Generate an SDK\n\nCreate a client library in your preferred language (requires Java runtime):\n\n```bash\n# TypeScript/JavaScript\nnpm run generate:typescript\n\n# Python\nnpm run generate:python\n\n# PHP\nnpm run generate:php\n```\n\nThe generated SDK will be in the `examples/` folder, complete with documentation and usage examples.\n\n---\n\n## Using Generated SDKs\n\nAfter generating an SDK, you'll find complete documentation in the generated folder including a README with examples for every endpoint.\n\n### Quick TypeScript Example\n\n```bash\n# Build the SDK\ncd examples/typescript\nnpm install && npm run build\n\n# Install in your project\nnpm install /path/to/examples/typescript\n```\n\nBasic usage:\n\n```typescript\nimport { Configuration, PagesApi } from 'apostrophecms-client';\n\nconst config = new Configuration({\n basePath: 'http://localhost:3000/api/v1',\n apiKey: process.env.APOSTROPHE_API_KEY\n});\n\nconst pages = new PagesApi(config);\n\n// Get page tree\nconst tree = await pages.pageGet();\nconsole.log(tree.data);\n\n// Create a page\nconst newPage = await pages.pagePost({\n title: 'Welcome',\n type: 'default-page',\n slug: '/welcome'\n});\n```\n\n**See the generated `examples/typescript/README.md` for complete documentation**, including authentication options, error handling, and examples for all endpoints.\n\n---\n\n## What's Included\n\n### Specifications\n\n- **`apostrophecms-openapi.yaml`** - Core ApostropheCMS REST API specification\n- **`examples/apostrophecms-piece-examples.yaml`** - Sample piece types for learning\n\n### Generated Examples\n\n- **`examples/typescript/`** - Pre-generated TypeScript SDK with full documentation\n- Includes comprehensive README with examples for every endpoint\n\n### Scripts\n\n| Command | Purpose |\n|---------|---------|\n| `npm run docs:open` | Open core API documentation |\n| `npm run example-docs:open` | Open example piece documentation |\n| `npm run validate` | Validate OpenAPI specification |\n| `npm run lint` | Lint specification with Spectral |\n| `npm test` | Run validation and linting |\n| `npm run generate:typescript` | Generate TypeScript SDK |\n| `npm run generate:python` | Generate Python SDK |\n| `npm run generate:php` | Generate PHP SDK |\n\n---\n\n## Validation\n\nEnsure specification quality:\n\n```bash\nnpm run validate # Check OpenAPI structure\nnpm run lint # Lint with Spectral\nnpm test # Run both checks\n```\n\nThe specification follows OpenAPI 3.1 standards and uses [Spectral](https://stoplight.io/open-source/spectral/) for linting.\n\n---\n\n## SDK Generation Details\n\nThis repository uses [OpenAPI Generator](https://openapi-generator.tech/) to create client libraries. \n\n### Other Languages\n\n```bash\n# Python\nnpm run generate:python\n\n# PHP\nnpm run generate:php\n\n# See full list of supported languages:\n# https://openapi-generator.tech/docs/generators/\n```\n\nEach generated SDK includes:\n- Complete API client with type definitions\n- README with usage examples\n- Documentation for all endpoints\n- Authentication configuration helpers\n\nCheck the generated SDK's README for language-specific setup and usage instructions.\n\n---\n\n## Contributing\n\nWe welcome contributions! To contribute:\n\n1. Fork the repository and create a feature branch\n2. Make changes to the OpenAPI specification\n3. Run `npm test` to validate your changes\n4. Submit a pull request with a clear description\n\nPlease ensure your changes:\n- Follow OpenAPI 3.1 standards\n- Include appropriate examples\n- Pass validation and linting\n- Update documentation as needed\n\n---\n\n## Resources\n\n### ApostropheCMS Documentation\n- [Main Documentation](https://docs.apostrophecms.org/)\n- [REST API Guide](https://docs.apostrophecms.org/guide/rest-api.html)\n- [Headless CMS Guide](https://docs.apostrophecms.org/guide/headless.html)\n- [Main Repository](https://github.com/apostrophecms/apostrophe)\n\n### Support & Community\n- [Discord Community](https://discord.com/invite/HwntQpADJr) - Get help from other developers\n- [GitHub Issues](https://github.com/apostrophecms/apostrophecms-openapi/issues) - Report bugs or request features\n- [Professional Support](https://apostrophecms.com/contact-us) - Enterprise support and consulting\n\n---\n\n## Versioning\n\n- **Specification Version**: Follows semantic versioning (current: `1.0.0`)\n- **API Compatibility**: The `x-apostrophe.cmsVersion` field indicates compatible ApostropheCMS versions\n- **Breaking Changes**: Major version updates indicate breaking API changes\n\n---\n\n
![\"ApostropheCMS](\"https://raw.githubusercontent.com/apostrophecms/apostrophe/main/logo.svg\"){kind=logo}
\n\n ![](\"https://img.shields.io/badge/MADE%20FOR%20ApostropheCMS-000000.svg?style=for-the-badge&logo=Apostrophe&labelColor=6516dd\"){kind=icon}
\n ![\"\"](\"https://img.shields.io/discord/517772094482677790?color=5865f2&label=Join%20the%20Discord&logo=discord&logoColor=fff&labelColor=000&style=for-the-badge&logoWidth=20\")
\n ![\"\"](\"https://img.shields.io/static/v1?style=for-the-badge&labelColor=000000&label=License&message=MIT&color=3DA639\")
\n