openapi: 3.1.0 info: title: ReadMe API description: >- The ReadMe API lets you programmatically control your ReadMe developer hub. You can manage API definitions, API reference pages, guides, changelogs, custom pages, categories, branches, images, recipes, and search. version: '2.0' contact: name: ReadMe Support url: https://docs.readme.com servers: - url: https://api.readme.com/v2 description: ReadMe API v2 base URL - url: https://dash.readme.io/api/v1 description: ReadMe API v1 (legacy) security: - bearerAuth: [] tags: - name: APIs description: Manage API definitions and reference pages - name: Guides description: Manage knowledge base guide pages - name: Changelog description: Manage changelog posts - name: Custom Pages description: Manage custom documentation pages - name: Categories description: Manage sidebar groupings - name: Branches description: Manage versions and branches - name: Images description: Upload and manage images - name: Search description: Search knowledge base content - name: API Keys description: Manage ReadMe API keys paths: /api-specification: get: tags: - APIs summary: List API specifications description: Retrieve metadata for API specifications uploaded to a project. parameters: - name: perPage in: query schema: type: integer minimum: 1 maximum: 100 default: 10 - name: page in: query schema: type: integer minimum: 1 default: 1 - name: x-readme-version in: header required: true schema: type: string responses: '200': description: Successful retrieval '400': description: Missing version parameter '401': description: Unauthorized '404': description: Version not found post: tags: - APIs summary: Upload an API specification responses: '201': description: Created /api-specification/{id}: put: tags: - APIs summary: Update an API specification parameters: - name: id in: path required: true schema: type: string responses: '200': description: Updated delete: tags: - APIs summary: Delete an API specification parameters: - name: id in: path required: true schema: type: string responses: '204': description: Deleted /docs: get: tags: - Guides summary: List guide pages responses: '200': description: List of guides post: tags: - Guides summary: Create a guide page responses: '201': description: Created /docs/{slug}: get: tags: - Guides summary: Get a guide by slug parameters: - name: slug in: path required: true schema: type: string responses: '200': description: Guide page put: tags: - Guides summary: Update a guide parameters: - name: slug in: path required: true schema: type: string responses: '200': description: Updated delete: tags: - Guides summary: Delete a guide parameters: - name: slug in: path required: true schema: type: string responses: '204': description: Deleted /changelogs: get: tags: - Changelog summary: List changelog posts responses: '200': description: Changelog posts post: tags: - Changelog summary: Create a changelog post responses: '201': description: Created /changelogs/{slug}: get: tags: - Changelog summary: Get a changelog post parameters: - name: slug in: path required: true schema: type: string responses: '200': description: Changelog post put: tags: - Changelog summary: Update a changelog post parameters: - name: slug in: path required: true schema: type: string responses: '200': description: Updated delete: tags: - Changelog summary: Delete a changelog post parameters: - name: slug in: path required: true schema: type: string responses: '204': description: Deleted /custompages: get: tags: - Custom Pages summary: List custom pages responses: '200': description: Custom pages post: tags: - Custom Pages summary: Create a custom page responses: '201': description: Created /custompages/{slug}: get: tags: - Custom Pages summary: Get a custom page parameters: - name: slug in: path required: true schema: type: string responses: '200': description: Custom page put: tags: - Custom Pages summary: Update a custom page parameters: - name: slug in: path required: true schema: type: string responses: '200': description: Updated delete: tags: - Custom Pages summary: Delete a custom page parameters: - name: slug in: path required: true schema: type: string responses: '204': description: Deleted /categories: get: tags: - Categories summary: List categories responses: '200': description: Categories post: tags: - Categories summary: Create a category responses: '201': description: Created /categories/{slug}: get: tags: - Categories summary: Get a category parameters: - name: slug in: path required: true schema: type: string responses: '200': description: Category put: tags: - Categories summary: Update a category parameters: - name: slug in: path required: true schema: type: string responses: '200': description: Updated delete: tags: - Categories summary: Delete a category parameters: - name: slug in: path required: true schema: type: string responses: '204': description: Deleted /version: get: tags: - Branches summary: List versions responses: '200': description: Versions list post: tags: - Branches summary: Create a version responses: '201': description: Created /version/{versionId}: get: tags: - Branches summary: Get a version parameters: - name: versionId in: path required: true schema: type: string responses: '200': description: Version put: tags: - Branches summary: Update a version parameters: - name: versionId in: path required: true schema: type: string responses: '200': description: Updated delete: tags: - Branches summary: Delete a version parameters: - name: versionId in: path required: true schema: type: string responses: '204': description: Deleted /images: post: tags: - Images summary: Upload an image responses: '201': description: Image uploaded /search: get: tags: - Search summary: Search knowledge base parameters: - name: search in: query required: true schema: type: string responses: '200': description: Search results /apikeys: get: tags: - API Keys summary: List API keys responses: '200': description: API keys post: tags: - API Keys summary: Create an API key responses: '201': description: Created /apikeys/{id}: delete: tags: - API Keys summary: Delete an API key parameters: - name: id in: path required: true schema: type: string responses: '204': description: Deleted components: securitySchemes: bearerAuth: type: http scheme: bearer description: Use your ReadMe API key as a Bearer token.