@readme/oas-examples

openapi: 3.0.2 info: description: Create beautiful product and API documentation with our developer friendly platform. version: 5.427.1 title: Legacy API contact: name: API Support url: https://docs.readme.com/main/docs/need-more-support email: support@readme.io servers: - url: https://dash.readme.com/api/v1 tags: - name: API Registry - name: API Specification - name: Apply to ReadMe - name: Categories - name: Changelog - name: Custom Pages - name: Docs - name: Errors - name: IP Addresses - name: Owlbot AI - name: Projects - name: Version paths: '/': get: operationId: getProject summary: Get metadata about the current project description: |- Returns project data for the API key. >❗ > API v1 and this route are not available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored). [Check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide) for information on how to migrate to the new API. tags: - Projects responses: '200': description: Project data content: application/json: schema: '$ref': '#/components/schemas/condensedProjectData' '401': '$ref': '#/components/responses/authUnauthorized' '403': '$ref': '#/components/responses/authForbidden' security: - apiKey: [] '/api-registry/{uuid}': get: operationId: getAPIRegistry summary: Retrieve an entry from the API Registry description: Get an API definition file that's been uploaded to ReadMe. tags: - API Registry parameters: - name: uuid in: path description: An API Registry UUID. This can be found by navigating to your API Reference page and viewing code snippets for Node with the `api` library. schema: type: string required: true responses: '200': description: Successfully retrieved API registry entry. content: application/json: schema: type: object '404': '$ref': '#/components/responses/error_REGISTRY_NOTFOUND' '/api-specification': get: operationId: getAPISpecification summary: Get metadata description: |- Get API specification metadata. >❗ > API v1 and this route are not available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored). [Check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide) for information on how to migrate to the new API. tags: - API Specification parameters: - '$ref': '#/components/parameters/perPage' - '$ref': '#/components/parameters/page' - '$ref': '#/components/parameters/x-readme-version' responses: '200': description: Successfully retrieved API specification metadata. headers: Link: '$ref': '#/components/headers/link' x-total-count: '$ref': '#/components/headers/x-total-count' '400': '$ref': '#/components/responses/error_VERSION_EMPTY' '401': '$ref': '#/components/responses/authUnauthorized' '403': '$ref': '#/components/responses/authForbidden' '404': '$ref': '#/components/responses/error_VERSION_NOTFOUND' security: - apiKey: [] post: operationId: uploadAPISpecification summary: Upload specification description: |- Upload an API specification to ReadMe. Or, to use a newer solution see https://docs.readme.com/main/docs/rdme. >❗ > API v1 and this route are not available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored). [Check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide) for information on how to migrate to the new API. tags: - API Specification parameters: - '$ref': '#/components/parameters/x-readme-version' requestBody: required: true content: multipart/form-data: schema: type: object properties: spec: description: An OpenAPI/Swagger file. We accept JSON or YAML. type: string format: binary url: description: A public URL to an OpenAPI/Swagger definition. We accept JSON or YAML. type: string format: url responses: '201': description: The API specification was successfully uploaded. '400': description: There was a validation error during upload. content: application/json: schema: oneOf: - '$ref': '#/components/schemas/error_SPEC_FILE_EMPTY' - '$ref': '#/components/schemas/error_SPEC_INVALID' - '$ref': '#/components/schemas/error_SPEC_INVALID_SCHEMA' - '$ref': '#/components/schemas/error_SPEC_VERSION_NOTFOUND' '401': '$ref': '#/components/responses/authUnauthorized' '403': '$ref': '#/components/responses/authForbidden' '408': '$ref': '#/components/responses/error_SPEC_TIMEOUT' security: - apiKey: [] '/api-specification/{id}': put: operationId: updateAPISpecification summary: Update specification description: |- Update an API specification in ReadMe. >❗ > API v1 and this route are not available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored). [Check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide) for information on how to migrate to the new API. tags: - API Specification parameters: - name: id in: path description: ID of the API specification. The unique ID for each API can be found by navigating to your **API Definitions** page. schema: type: string required: true requestBody: required: true content: multipart/form-data: schema: type: object properties: spec: description: An OpenAPI/Swagger file. We accept JSON or YAML. type: string format: binary url: description: A public URL to an OpenAPI/Swagger definition. We accept JSON or YAML. type: string format: url responses: '200': description: The API specification was updated. '400': description: There was a validation error during upload. content: application/json: schema: oneOf: - '$ref': '#/components/schemas/error_SPEC_FILE_EMPTY' - '$ref': '#/components/schemas/error_SPEC_ID_DUPLICATE' - '$ref': '#/components/schemas/error_SPEC_ID_INVALID' - '$ref': '#/components/schemas/error_SPEC_INVALID' - '$ref': '#/components/schemas/error_SPEC_INVALID_SCHEMA' - '$ref': '#/components/schemas/error_SPEC_VERSION_NOTFOUND' '401': '$ref': '#/components/responses/authUnauthorized' '403': '$ref': '#/components/responses/authForbidden' '404': description: There is no API specification with that ID. '408': '$ref': '#/components/responses/error_SPEC_TIMEOUT' security: - apiKey: [] delete: operationId: deleteAPISpecification summary: Delete specification description: |- Delete an API specification in ReadMe. >❗ > API v1 and this route are not available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored). [Check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide) for information on how to migrate to the new API. tags: - API Specification parameters: - name: id in: path description: ID of the API specification. The unique ID for each API can be found by navigating to your **API Definitions** page. schema: type: string required: true responses: '204': description: The API specification was deleted. '400': '$ref': '#/components/responses/error_SPEC_ID_INVALID' '401': '$ref': '#/components/responses/authUnauthorized' '403': '$ref': '#/components/responses/authForbidden' '404': '$ref': '#/components/responses/error_SPEC_NOTFOUND' security: - apiKey: [] '/categories': get: operationId: getCategories summary: Get all categories description: |- Returns all the categories for a specified version. >❗ > API v1 and this route are not available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored). [Check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide) for information on how to migrate to the new API. tags: - Categories parameters: - '$ref': '#/components/parameters/x-readme-version' - '$ref': '#/components/parameters/perPage' - '$ref': '#/components/parameters/page' responses: '200': description: The list of categories. headers: Link: '$ref': '#/components/headers/link' x-total-count: '$ref': '#/components/headers/x-total-count' security: - apiKey: [] post: operationId: createCategory summary: Create category description: |- Create a new category inside of this project. >❗ > API v1 and this route are not available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored). [Check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide) for information on how to migrate to the new API. tags: - Categories parameters: - '$ref': '#/components/parameters/x-readme-version' requestBody: required: true content: application/json: schema: allOf: - '$ref': '#/components/schemas/category' - required: - title responses: '201': description: The category has successfully been created. '400': '$ref': '#/components/responses/error_CATEGORY_INVALID' security: - apiKey: [] '/categories/{slug}': get: operationId: getCategory summary: Get category description: |- Returns the category with this slug. >❗ > API v1 and this route are not available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored). [Check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide) for information on how to migrate to the new API. tags: - Categories parameters: - name: slug in: path description: A URL-safe representation of the category title. Slugs must be all lowercase, and replace spaces with hyphens. For example, for the category "Getting Started", enter the slug "getting-started". example: getting-started required: true schema: type: string - '$ref': '#/components/parameters/x-readme-version' responses: '200': description: The category exists and has been returned. '404': '$ref': '#/components/responses/error_CATEGORY_NOTFOUND' security: - apiKey: [] put: operationId: updateCategory summary: Update category description: |- Change the properties of a category. >❗ > API v1 and this route are not available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored). [Check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide) for information on how to migrate to the new API. tags: - Categories parameters: - name: slug in: path description: A URL-safe representation of the category title. Slugs must be all lowercase, and replace spaces with hyphens. For example, for the category "Getting Started", enter the slug "getting-started". example: getting-started required: true schema: type: string - '$ref': '#/components/parameters/x-readme-version' requestBody: required: true content: application/json: schema: '$ref': '#/components/schemas/category' responses: '200': description: The category was successfully updated. '400': '$ref': '#/components/responses/error_CATEGORY_INVALID' '404': '$ref': '#/components/responses/error_CATEGORY_NOTFOUND' security: - apiKey: [] delete: operationId: deleteCategory summary: Delete category description: |- Delete the category with this slug. >❗ > API v1 and this route are not available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored). [Check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide) for information on how to migrate to the new API. tags: - Categories parameters: - name: slug in: path description: A URL-safe representation of the category title. Slugs must be all lowercase, and replace spaces with hyphens. For example, for the category "Getting Started", enter the slug "getting-started". example: getting-started required: true schema: type: string - '$ref': '#/components/parameters/x-readme-version' responses: '204': description: The category was deleted. '404': '$ref': '#/components/responses/error_CATEGORY_NOTFOUND' security: - apiKey: [] '/categories/{slug}/docs': get: operationId: getCategoryDocs summary: Get docs for category description: |- Returns the docs and children docs within this category. >❗ > API v1 and this route are not available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored). [Check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide) for information on how to migrate to the new API. tags: - Categories parameters: - name: slug in: path description: A URL-safe representation of the category title. Slugs must be all lowercase, and replace spaces with hyphens. For example, for the category "Getting Started", enter the slug "getting-started". example: getting-started required: true schema: type: string - '$ref': '#/components/parameters/x-readme-version' responses: '200': description: The category exists and all of the docs have been returned. '404': '$ref': '#/components/responses/error_CATEGORY_NOTFOUND' security: - apiKey: [] '/changelogs': get: operationId: getChangelogs summary: Get changelogs description: |- Returns a list of changelogs. >❗ > API v1 and this route are not available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored). [Check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide) for information on how to migrate to the new API. tags: - Changelog parameters: - '$ref': '#/components/parameters/perPage' - '$ref': '#/components/parameters/page' responses: '200': description: The list of changelogs. headers: Link: '$ref': '#/components/headers/link' x-total-count: '$ref': '#/components/headers/x-total-count' security: - apiKey: [] post: operationId: createChangelog summary: Create changelog description: |- Create a new changelog entry. >❗ > API v1 and this route are not available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored). [Check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide) for information on how to migrate to the new API. tags: - Changelog requestBody: required: true content: application/json: schema: '$ref': '#/components/schemas/changelog' responses: '201': description: The changelog was successfully created. '400': description: There was a validation error during creation. security: - apiKey: [] '/changelogs/{slug}': get: operationId: getChangelog summary: Get changelog description: |- Returns the changelog with this slug. >❗ > API v1 and this route are not available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored). [Check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide) for information on how to migrate to the new API. tags: - Changelog parameters: - name: slug in: path description: A URL-safe representation of the changelog title. Slugs must be all lowercase, and replace spaces with hyphens. For example, for the changelog "Owlet Update", enter the slug "owlet-update". required: true schema: type: string responses: '200': description: The changelog exists and has been returned. '404': description: There is no changelog with that slug. security: - apiKey: [] put: operationId: updateChangelog summary: Update changelog description: |- Update a changelog with this slug. >❗ > API v1 and this route are not available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored). [Check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide) for information on how to migrate to the new API. tags: - Changelog parameters: - name: slug in: path description: A URL-safe representation of the changelog title. Slugs must be all lowercase, and replace spaces with hyphens. For example, for the changelog "Owlet Weekly Update", enter the slug "owlet-weekly-update". required: true schema: type: string requestBody: required: true content: application/json: schema: '$ref': '#/components/schemas/changelog' responses: '200': description: The changelog was successfully updated. '400': description: There was a validation error during update. '404': description: There is no changelog with that slug. security: - apiKey: [] delete: operationId: deleteChangelog summary: Delete changelog description: |- Delete the changelog with this slug. >❗ > API v1 and this route are not available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored). [Check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide) for information on how to migrate to the new API. tags: - Changelog parameters: - name: slug in: path description: A URL-safe representation of the changelog title. Slugs must be all lowercase, and replace spaces with hyphens. For example, for the changelog "Owlet Weekly Update", enter the slug "owlet-weekly-update". required: true schema: type: string responses: '204': description: The changelog was successfully updated. '404': description: There is no changelog with that slug. security: - apiKey: [] '/custompages': get: operationId: getCustomPages summary: Get custom pages description: |- Returns a list of custom pages. >❗ > API v1 and this route are not available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored). [Check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide) for information on how to migrate to the new API. tags: - Custom Pages parameters: - '$ref': '#/components/parameters/perPage' - '$ref': '#/components/parameters/page' responses: '200': description: The list of custom pages. headers: Link: '$ref': '#/components/headers/link' x-total-count: '$ref': '#/components/headers/x-total-count' '401': '$ref': '#/components/responses/authUnauthorized' '403': '$ref': '#/components/responses/authForbidden' security: - apiKey: [] post: operationId: createCustomPage summary: Create custom page description: |- Create a new custom page inside of this project. >❗ > API v1 and this route are not available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored). [Check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide) for information on how to migrate to the new API. tags: - Custom Pages requestBody: required: true content: application/json: schema: '$ref': '#/components/schemas/customPage' responses: '201': description: The custom page was successfully created. '400': '$ref': '#/components/responses/error_CUSTOMPAGE_INVALID' '401': '$ref': '#/components/responses/authUnauthorized' '403': '$ref': '#/components/responses/authForbidden' security: - apiKey: [] '/custompages/{slug}': get: operationId: getCustomPage summary: Get custom page description: |- Returns the custom page with this slug. >❗ > API v1 and this route are not available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored). [Check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide) for information on how to migrate to the new API. tags: - Custom Pages parameters: - '$ref': '#/components/parameters/slug' responses: '200': description: The custom page exists and has been returned. '401': '$ref': '#/components/responses/authUnauthorized' '403': '$ref': '#/components/responses/authForbidden' '404': '$ref': '#/components/responses/error_CUSTOMPAGE_NOTFOUND' security: - apiKey: [] put: operationId: updateCustomPage summary: Update custom page description: |- Update a custom page with this slug. >❗ > API v1 and this route are not available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored). [Check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide) for information on how to migrate to the new API. tags: - Custom Pages parameters: - '$ref': '#/components/parameters/slug' requestBody: required: true content: application/json: schema: '$ref': '#/components/schemas/customPage' responses: '200': description: The custom page was successfully updated. '400': '$ref': '#/components/responses/error_CUSTOMPAGE_INVALID' '401': '$ref': '#/components/responses/authUnauthorized' '403': '$ref': '#/components/responses/authForbidden' '404': '$ref': '#/components/responses/error_CUSTOMPAGE_NOTFOUND' security: - apiKey: [] delete: operationId: deleteCustomPage summary: Delete custom page description: |- Delete the custom page with this slug. >❗ > API v1 and this route are not available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored). [Check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide) for information on how to migrate to the new API. tags: - Custom Pages parameters: - '$ref': '#/components/parameters/slug' responses: '204': description: The custom page was successfully updated. '401': '$ref': '#/components/responses/authUnauthorized' '403': '$ref': '#/components/responses/authForbidden' '404': '$ref': '#/components/responses/error_CUSTOMPAGE_NOTFOUND' security: - apiKey: [] '/docs': post: operationId: createDoc summary: Create doc description: |- Create a new doc inside of this project. >❗ > API v1 and this route are not available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored). [Check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide) for information on how to migrate to the new API. tags: - Docs parameters: - '$ref': '#/components/parameters/x-readme-version' requestBody: required: true content: application/json: schema: '$ref': '#/components/schemas/docSchemaPost' responses: '201': description: The doc was successfully created. content: application/json: schema: '$ref': '#/components/schemas/docSchemaResponse' '400': '$ref': '#/components/responses/error_DOC_INVALID' '401': '$ref': '#/components/responses/authUnauthorized' '403': '$ref': '#/components/responses/authForbidden' security: - apiKey: [] '/docs/search': post: operationId: searchDocs summary: Search docs description: |- Returns all docs that match the search. >❗ > API v1 and this route are not available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored). [Check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide) for information on how to migrate to the new API. tags: - Docs parameters: - name: search in: query description: Search string to look for. required: true schema: type: string - '$ref': '#/components/parameters/x-readme-version' responses: '200': description: The search was successful and results were returned. '401': '$ref': '#/components/responses/authUnauthorized' '403': '$ref': '#/components/responses/authForbidden' security: - apiKey: [] '/docs/{slug}': get: operationId: getDoc summary: Get doc description: |- Returns the doc with this slug. >❗ > API v1 and this route are not available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored). [Check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide) for information on how to migrate to the new API. tags: - Docs parameters: - '$ref': '#/components/parameters/slug' - '$ref': '#/components/parameters/x-readme-version' responses: '200': description: The doc exists and has been returned. content: application/json: schema: '$ref': '#/components/schemas/docSchemaResponse' '401': '$ref': '#/components/responses/authUnauthorized' '403': '$ref': '#/components/responses/authForbidden' '404': '$ref': '#/components/responses/error_DOC_NOTFOUND' security: - apiKey: [] put: operationId: updateDoc summary: Update doc description: |- Update a doc with this slug. >❗ > API v1 and this route are not available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored). [Check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide) for information on how to migrate to the new API. tags: - Docs parameters: - '$ref': '#/components/parameters/slug' - '$ref': '#/components/parameters/x-readme-version' requestBody: required: true content: application/json: schema: '$ref': '#/components/schemas/docSchemaPut' responses: '200': description: The doc was successfully updated. content: application/json: schema: '$ref': '#/components/schemas/docSchemaResponse' '400': '$ref': '#/components/responses/error_DOC_INVALID' '401': '$ref': '#/components/responses/authUnauthorized' '403': '$ref': '#/components/responses/authForbidden' '404': '$ref': '#/components/responses/error_DOC_NOTFOUND' security: - apiKey: [] delete: operationId: deleteDoc summary: Delete doc description: |- Delete the doc with this slug. >❗ > API v1 and this route are not available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored). [Check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide) for information on how to migrate to the new API. tags: - Docs parameters: - '$ref': '#/components/parameters/slug' - '$ref': '#/components/parameters/x-readme-version' responses: '204': description: The doc was successfully updated. '401': '$ref': '#/components/responses/authUnauthorized' '403': '$ref': '#/components/responses/authForbidden' '404': '$ref': '#/components/responses/error_DOC_NOTFOUND' security: - apiKey: [] '/docs/{slug}/production': get: operationId: getProductionDoc summary: Get production doc description: |- This is intended for use by enterprise users with staging enabled. This endpoint will return the live version of your document, whereas the standard endpoint will always return staging. >❗ > API v1 and this route are not available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored). [Check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide) for information on how to migrate to the new API. tags: - Docs parameters: - '$ref': '#/components/parameters/slug' - '$ref': '#/components/parameters/x-readme-version' responses: '200': description: The doc exists and has been returned. content: application/json: schema: '$ref': '#/components/schemas/docSchemaResponse' '401': '$ref': '#/components/responses/authUnauthorized' '403': '$ref': '#/components/responses/authForbidden' '404': '$ref': '#/components/responses/error_DOC_NOTFOUND' security: - apiKey: [] '/outbound-ips': get: operationId: getOutboundIPs summary: Get ReadMe’s outbound IP addresses description: | Returns all of ReadMe’s IP addresses used for outbound webhook requests and the “Try It!” button on the API Explorer. Although ReadMe’s outbound IP addresses may change, the IPs in this API response will be valid for at least 7 days. If you configure your API or webhooks to limit access based on these IPs, you should refresh the IP list from this endpoint weekly. tags: - IP Addresses responses: '200': description: List of current IP addresses used for webhook and “Try It!” proxy requests. content: application/json: schema: type: array items: '$ref': '#/components/schemas/ipListEntry' '/owlbot/ask': post: operationId: askOwlbot summary: Ask Owlbot AI a question description: |- Ask Owlbot a question about the content of your docs. >❗ > API v1 and this route are not available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored). [Check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide) for information on how to migrate to the new API. tags: - Owlbot AI requestBody: required: true content: application/json: schema: type: object required: - question properties: question: type: string description: The question being asked to Owlbot. stream: type: boolean description: If true the response will be streamed as it is generated. responses: '200': description: The answer to the question that was asked. content: text/event-stream: examples: streaming response: value: 'sources: [{ title: "Page Title", url: "https://docs.example.com/docs/owl-facts"}]\n\nOwls have extremely flexible necks and can rotate their heads up to 270 degrees in each direction, giving them a 540-degree range in total.' application/json: schema: type: object properties: answer: type: string sources: type: array items: type: object properties: title: type: string description: The page title for the given source. url: type: string description: A link to the source. examples: non-streaming response: value: answer: Owls have extremely flexible necks and can rotate their heads up to 270 degrees in each direction, giving them a 540-degree range in total. sources: - title: Page Title url: https://docs.example.com/docs/owl-facts security: - apiKey: [] '/schema': get: operationId: getAPISchema summary: Get our OpenAPI Definition description: Returns a copy of our OpenAPI Definition. tags: - API Specification responses: '200': description: OpenAPI Definition data content: application/json: schema: type: object additionalProperties: true '/version': get: operationId: getVersions summary: Get versions description: |- Retrieve a list of versions associated with a project API key. >❗ > API v1 and this route are not available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored). [Check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide) for information on how to migrate to the new API. tags: - Version responses: '200': description: A list of versions. '401': '$ref': '#/components/responses/authUnauthorized' '403': '$ref': '#/components/responses/authForbidden' security: - apiKey: [] post: operationId: createVersion summary: Create version description: |- Create a new version. >❗ > API v1 and this route are not available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored). [Check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide) for information on how to migrate to the new API. tags: - Version requestBody: required: true content: application/json: schema: '$ref': '#/components/schemas/version' responses: '200': description: The version was successfully created. '400': description: There was a validation error during creation. content: application/json: schema: oneOf: - '$ref': '#/components/schemas/error_VERSION_EMPTY' - '$ref': '#/components/schemas/error_VERSION_DUPLICATE' - '$ref': '#/components/schemas/error_VERSION_FORK_EMPTY' '401': '$ref': '#/components/responses/authUnauthorized' '403': '$ref': '#/components/responses/authForbidden' '404': '$ref': '#/components/responses/error_VERSION_FORK_NOTFOUND' security: - apiKey: [] '/version/{versionId}': get: operationId: getVersion summary: Get version description: |- Returns the version with this version ID. >❗ > API v1 and this route are not available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored). [Check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide) for information on how to migrate to the new API. tags: - Version parameters: - '$ref': '#/components/parameters/versionId' responses: '200': description: The version exists and has been returned. '401': '$ref': '#/components/responses/authUnauthorized' '403': '$ref': '#/components/responses/authForbidden' '404': '$ref': '#/components/responses/error_VERSION_NOTFOUND' security: - apiKey: [] put: operationId: updateVersion summary: Update version description: |- Update an existing version. >❗ > API v1 and this route are not available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored). [Check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide) for information on how to migrate to the new API. tags: - Version parameters: - '$ref': '#/components/parameters/versionId' requestBody: required: true content: application/json: schema: '$ref': '#/components/schemas/version' responses: '200': description: The version was successfully updated. '400': '$ref': '#/components/responses/error_VERSION_CANT_DEMOTE_STABLE' '401': '$ref': '#/components/responses/authUnauthorized' '403': '$ref': '#/components/responses/authForbidden' '404': '$ref': '#/components/responses/error_VERSION_NOTFOUND' security: - apiKey: [] delete: operationId: deleteVersion summary: Delete version description: |- Delete a version. >❗ > API v1 and this route are not available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored). [Check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide) for information on how to migrate to the new API. tags: - Version parameters: - '$ref': '#/components/parameters/versionId' responses: '200': description: The version was successfully deleted. '400': '$ref': '#/components/responses/error_VERSION_CANT_REMOVE_STABLE' '401': '$ref': '#/components/responses/authUnauthorized' '403': '$ref': '#/components/responses/authForbidden' '404': '$ref': '#/components/responses/error_VERSION_NOTFOUND' security: - apiKey: [] components: securitySchemes: apiKey: type: http scheme: basic headers: link: description: Pagination information. See https://docs.readme.com/main/reference/pagination for more information. schema: type: string x-total-count: description: The total amount of results, ignoring pagination. See https://docs.readme.com/main/reference/pagination for more information about pagination. schema: type: string parameters: slug: name: slug in: path description: A URL-safe representation of the page title. Slugs must be all lowercase, and replace spaces with hyphens. For example, for the title "Getting Started", enter the slug "getting-started". required: true schema: type: string page: name: page in: query description: Used to specify further pages (starts at 1). schema: type: integer default: 1 minimum: 1 perPage: name: perPage in: query description: Number of items to include in pagination (up to 100, defaults to 10). schema: type: integer default: 10 minimum: 1 maximum: 100 x-readme-version: in: header name: x-readme-version description: Version number of your docs project, for example, v3.0. By default the main project version is used. To see all valid versions for your docs project call https://docs.readme.com/main/reference/version#getversions. example: v3.0 required: false schema: type: string versionId: name: versionId in: path description: Semver identifier for the project version. For best results, use the formatted `version_clean` value listed in the response from the [Get Versions endpoint](/reference/getversions). example: v1.0.0 required: true schema: type: string responses: authForbidden: description: Unauthorized content: application/json: schema: oneOf: - '$ref': '#/components/schemas/error_APIKEY_MISMATCH' authUnauthorized: description: Unauthorized content: application/json: schema: oneOf: - '$ref': '#/components/schemas/error_APIKEY_EMPTY' - '$ref': '#/components/schemas/error_APIKEY_NOTFOUND' error_APIKEY_EMPTY: description: An API key was not supplied. content: application/json: schema: '$ref': '#/components/schemas/error_APIKEY_EMPTY' error_APIKEY_MISMATCH: description: The API key doesn't match the project. content: application/json: schema: '$ref': '#/components/schemas/error_APIKEY_MISMATCH' error_APIKEY_NOTFOUND: description: The API key couldn't be located. content: application/json: schema: '$ref': '#/components/schemas/error_APIKEY_NOTFOUND' error_API_ACCESS_REVOKED: description: Your ReadMe API access has been revoked. content: application/json: schema: '$ref': '#/components/schemas/error_API_ACCESS_REVOKED' error_API_ACCESS_UNAVAILABLE: description: Your ReadMe project does not have access to this API. Please reach out to support@readme.io. content: application/json: schema: '$ref': '#/components/schemas/error_API_ACCESS_UNAVAILABLE' error_APPLY_INVALID_EMAIL: description: You need to provide a valid email. content: application/json: schema: '$ref': '#/components/schemas/error_APPLY_INVALID_EMAIL' error_APPLY_INVALID_JOB: description: You need to provide a job. content: application/json: schema: '$ref': '#/components/schemas/error_APPLY_INVALID_JOB' error_APPLY_INVALID_NAME: description: You need to provide a name. content: application/json: schema: '$ref': '#/components/schemas/error_APPLY_INVALID_NAME' error_CATEGORY_INVALID: description: The category couldn't be saved. content: application/json: schema: '$ref': '#/components/schemas/error_CATEGORY_INVALID' error_CATEGORY_NOTFOUND: description: The category couldn't be found. content: application/json: schema: '$ref': '#/components/schemas/error_CATEGORY_NOTFOUND' error_CHANGELOG_INVALID: description: The changelog couldn't be saved. content: application/json: schema: '$ref': '#/components/schemas/error_CHANGELOG_INVALID' error_CHANGELOG_NOTFOUND: description: The changelog couldn't be found. content: application/json: schema: '$ref': '#/components/schemas/error_CHANGELOG_NOTFOUND' error_CUSTOMBLOCK_NOTFOUND: description: The API key couldn't be located. content: application/json: schema: '$ref': '#/components/schemas/error_CUSTOMBLOCK_NOTFOUND' error_CUSTOMPAGE_INVALID: description: The page couldn't be saved. content: application/json: schema: '$ref': '#/components/schemas/error_CUSTOMPAGE_INVALID' error_CUSTOMPAGE_NOTFOUND: description: The custom page couldn't be found. content: application/json: schema: '$ref': '#/components/schemas/error_CUSTOMPAGE_NOTFOUND' error_DOC_INVALID: description: The doc couldn't be saved. content: application/json: schema: '$ref': '#/components/schemas/error_DOC_INVALID' error_DOC_NOTFOUND: description: The doc couldn't be found. content: application/json: schema: '$ref': '#/components/schemas/error_DOC_NOTFOUND' error_ENDPOINT_NOTFOUND: description: The endpoint doesn't exist. content: application/json: schema: '$ref': '#/components/schemas/error_ENDPOINT_NOTFOUND' error_INTERNAL_ERROR: description: An unknown error has occurred. content: application/json: schema: '$ref': '#/components/schemas/error_INTERNAL_ERROR' error_OWLBOT_INVALID: description: You need to provide a question to be answered. content: application/json: schema: '$ref': '#/components/schemas/error_OWLBOT_INVALID' error_OWLBOT_NOT_ENABLED: description: Owlbot isn't enabled on this project. content: application/json: schema: '$ref': '#/components/schemas/error_OWLBOT_NOT_ENABLED' error_OWLBOT_NOT_ENTERPRISE: description: Using the Owlbot API requires an Enterprise plan. content: application/json: schema: '$ref': '#/co