@readme/oas-examples
Version:
A collection of example OpenAPI 3.x and Swagger 2.0 documents.
1,408 lines • 104 kB
JSON
{
"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.\n\n>❗\n> 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.\n\n>❗\n> 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.\n\n>❗\n> 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.\n\n>❗\n> 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.\n\n>❗\n> 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.\n\n>❗\n> 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.\n\n>❗\n> 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.\n\n>❗\n> 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.\n\n>❗\n> 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.\n\n>❗\n> 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.\n\n>❗\n> 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.\n\n>❗\n> 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.\n\n>❗\n> 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.\n\n>❗\n> 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.\n\n>❗\n> 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.\n\n>❗\n> 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.\n\n>❗\n> 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.\n\n>❗\n> 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.\n\n>❗\n> 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.\n\n>❗\n> 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.\n\n>❗\n> 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.\n\n>❗\n> 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.\n\n>❗\n> 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.\n\n>❗\n> 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.\n\n>❗\n> 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.\n\n>❗\n> 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.\n\n>❗\n> 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.\n\nAlthough 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.\n",
"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.\n\n>❗\n> 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.\n\n>❗\n> 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.\n\n>❗\n> 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"
},