@readme/oas-examples
Version:
A collection of example OpenAPI 3.x and Swagger 2.0 documents.
1,300 lines (1,299 loc) • 561 kB
JSON
{
"openapi": "3.1.0",
"info": {
"description": "Create beautiful product and API documentation with our developer friendly platform.",
"version": "2.0.0",
"title": "ReadMe API",
"x-readme-deploy": "5.427.1",
"termsOfService": "https://readme.com/tos",
"contact": {
"name": "API Support",
"url": "https://docs.readme.com/main/docs/need-more-support",
"email": "support@readme.io"
}
},
"servers": [
{
"url": "https://api.readme.com/v2",
"description": "The ReadMe API"
}
],
"tags": [
{
"name": "API Keys"
},
{
"name": "API Reference"
},
{
"name": "APIs"
},
{
"name": "Apply to ReadMe"
},
{
"name": "Branches"
},
{
"name": "Categories"
},
{
"name": "Changelog"
},
{
"name": "Custom Pages"
},
{
"name": "Guides"
},
{
"name": "Images"
},
{
"name": "IP Addresses"
},
{
"name": "Owlbot AI"
},
{
"name": "Projects"
},
{
"name": "Recipes"
},
{
"name": "Search"
}
],
"paths": {
"/projects/{subdomain}/apikeys": {
"post": {
"operationId": "createAPIKey",
"summary": "Create an API key",
"tags": ["API Keys"],
"description": "Create an API key for your ReadMe project.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"label": {
"allOf": [
{
"type": "string"
},
{
"type": "string",
"minLength": 1
}
]
}
},
"required": ["label"],
"additionalProperties": false
}
}
},
"required": true
},
"parameters": [
{
"schema": {
"type": "string",
"pattern": "(me|[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)",
"maxLength": 30
},
"in": "path",
"name": "subdomain",
"required": true,
"description": "The subdomain of your project."
}
],
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"token": {
"type": "string",
"pattern": "rdme_\\w+"
},
"label": {
"type": "string",
"nullable": true
},
"last_accessed_on": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "An ISO 8601 formatted date for when the API key was last accessed."
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "An ISO 8601 formatted date for when the API key was created."
},
"uri": {
"type": "string",
"pattern": "\\/projects\\/(me|[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)\\/apikeys\\/[a-f\\d]{24}"
}
},
"required": ["token", "label", "last_accessed_on", "created_at", "uri"],
"additionalProperties": false
}
},
"required": ["data"],
"additionalProperties": false
}
}
}
}
}
},
"get": {
"operationId": "getAPIKeys",
"summary": "Get your API keys",
"tags": ["API Keys"],
"description": "Get the API keys for your ReadMe project.",
"parameters": [
{
"schema": {
"type": "number",
"minimum": 1,
"default": 1
},
"in": "query",
"name": "page",
"required": false,
"description": "Used to specify further pages (starts at 1)."
},
{
"schema": {
"type": "number",
"minimum": 1,
"maximum": 100,
"default": 10
},
"in": "query",
"name": "per_page",
"required": false,
"description": "Number of items to include in pagination (up to 100, defaults to 10)."
},
{
"schema": {
"type": "string",
"pattern": "(me|[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)",
"maxLength": 30
},
"in": "path",
"name": "subdomain",
"required": true,
"description": "The subdomain of your project."
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"total": {
"type": "number"
},
"page": {
"type": "number"
},
"per_page": {
"type": "number"
},
"paging": {
"type": "object",
"properties": {
"next": {
"type": "string",
"nullable": true
},
"previous": {
"type": "string",
"nullable": true
},
"first": {
"type": "string",
"nullable": true
},
"last": {
"type": "string",
"nullable": true
}
},
"required": ["next", "previous", "first", "last"],
"additionalProperties": false
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"token": {
"type": "string",
"pattern": "rdme_\\w+"
},
"label": {
"type": "string",
"nullable": true
},
"last_accessed_on": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "An ISO 8601 formatted date for when the API key was last accessed."
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "An ISO 8601 formatted date for when the API key was created."
},
"uri": {
"type": "string",
"pattern": "\\/projects\\/(me|[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)\\/apikeys\\/[a-f\\d]{24}"
}
},
"required": ["token", "label", "last_accessed_on", "created_at", "uri"],
"additionalProperties": false
}
}
},
"required": ["total", "page", "per_page", "paging", "data"],
"additionalProperties": false
}
}
}
}
}
}
},
"/projects/{subdomain}/apikeys/{api_key_id}": {
"delete": {
"operationId": "deleteAPIKey",
"summary": "Delete an API key",
"tags": ["API Keys"],
"description": "Delete an API key from your ReadMe project.",
"parameters": [
{
"schema": {
"type": "string",
"pattern": "[a-f\\d]{24}"
},
"in": "path",
"name": "api_key_id",
"required": true,
"description": "The unique identifier for your API key."
},
{
"schema": {
"type": "string",
"pattern": "(me|[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)",
"maxLength": 30
},
"in": "path",
"name": "subdomain",
"required": true,
"description": "The subdomain of your project."
}
],
"responses": {
"204": {
"description": "No Content"
}
}
},
"get": {
"operationId": "getAPIKey",
"summary": "Get an API key",
"tags": ["API Keys"],
"description": "Get an API key for your ReadMe project.",
"parameters": [
{
"schema": {
"type": "string",
"pattern": "[a-f\\d]{24}"
},
"in": "path",
"name": "api_key_id",
"required": true,
"description": "The unique identifier for your API key."
},
{
"schema": {
"type": "string",
"pattern": "(me|[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)",
"maxLength": 30
},
"in": "path",
"name": "subdomain",
"required": true,
"description": "The subdomain of your project."
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"token": {
"type": "string",
"pattern": "rdme_\\w+"
},
"label": {
"type": "string",
"nullable": true
},
"last_accessed_on": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "An ISO 8601 formatted date for when the API key was last accessed."
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "An ISO 8601 formatted date for when the API key was created."
},
"uri": {
"type": "string",
"pattern": "\\/projects\\/(me|[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)\\/apikeys\\/[a-f\\d]{24}"
}
},
"required": ["token", "label", "last_accessed_on", "created_at", "uri"],
"additionalProperties": false
}
},
"required": ["data"],
"additionalProperties": false
}
}
}
}
}
},
"patch": {
"operationId": "updateAPIKey",
"summary": "Update an API key",
"tags": ["API Keys"],
"description": "Update an API key on your ReadMe project.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"label": {
"allOf": [
{
"type": "string"
},
{
"type": "string",
"minLength": 1
}
]
}
},
"required": ["label"],
"additionalProperties": false
}
}
},
"required": true
},
"parameters": [
{
"schema": {
"type": "string",
"pattern": "[a-f\\d]{24}"
},
"in": "path",
"name": "api_key_id",
"required": true,
"description": "The unique identifier for your API key."
},
{
"schema": {
"type": "string",
"pattern": "(me|[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)",
"maxLength": 30
},
"in": "path",
"name": "subdomain",
"required": true,
"description": "The subdomain of your project."
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"token": {
"type": "string",
"pattern": "rdme_\\w+"
},
"label": {
"type": "string",
"nullable": true
},
"last_accessed_on": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "An ISO 8601 formatted date for when the API key was last accessed."
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "An ISO 8601 formatted date for when the API key was created."
},
"uri": {
"type": "string",
"pattern": "\\/projects\\/(me|[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)\\/apikeys\\/[a-f\\d]{24}"
}
},
"required": ["token", "label", "last_accessed_on", "created_at", "uri"],
"additionalProperties": false
}
},
"required": ["data"],
"additionalProperties": false
}
}
}
}
}
}
},
"/branches/{branch}/apis": {
"get": {
"operationId": "getAPIs",
"summary": "Get all API definitions",
"tags": ["APIs"],
"description": "Get all API definitions from your ReadMe project.\n\n>📘\n> This route is only available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored).",
"parameters": [
{
"schema": {
"type": "string",
"pattern": "(v{0,1})(stable|([0-9]+)(?:\\.([0-9]+))?(?:\\.([0-9]+))?(-.*)?)(_(.*))?"
},
"in": "path",
"name": "branch",
"required": true,
"description": "Project version number, `stable` for your project's stable version, or a valid branch name."
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"total": {
"type": "number"
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"created_at": {
"type": "string",
"format": "date-time",
"description": "An ISO 8601 formatted date for when the API definition was created."
},
"filename": {
"type": "string",
"description": "This is the unique identifier, its filename, for the API definition."
},
"legacy_id": {
"type": "string",
"pattern": "[a-f\\d]{24}",
"nullable": true,
"description": "The legacy ID of your API definition. This is only used for legacy rdme CLI workflows and only applies if your project, and this API definition, predates ReadMe Refactored. We consider this value to be deprecated and recommend against relying on it going forward."
},
"source": {
"type": "object",
"properties": {
"current": {
"type": "string",
"enum": [
"api",
"apidesigner",
"apieditor",
"bidi",
"form",
"postman",
"rdme",
"rdme_github",
"url"
]
},
"original": {
"type": "string",
"enum": [
"api",
"apidesigner",
"apieditor",
"bidi",
"form",
"postman",
"rdme",
"rdme_github",
"url"
]
}
},
"required": ["current", "original"],
"additionalProperties": false,
"description": "The sources by which this API definition was ingested."
},
"type": {
"type": "string",
"enum": ["openapi", "postman", "swagger", "unknown"],
"description": "The type of API definition. This will be `unknown` if the API definition has either not yet been processed or failed with validation errors."
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "An ISO 8601 formatted date for when the API definition was last updated."
},
"upload": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": ["pending", "failed", "done", "pending_update", "failed_update"],
"description": "The status of the API definition upload."
},
"reason": {
"type": "string",
"nullable": true,
"description": "The reason for the upload failure if it failed."
},
"warnings": {
"type": "string",
"nullable": true,
"description": "Any fixable warnings that may exist within the API definition if the upload was ingested without errors."
}
},
"required": ["status", "reason", "warnings"],
"additionalProperties": false
},
"uri": {
"type": "string",
"pattern": "\\/(versions|branches)\\/((v{0,1})(stable|([0-9]+)(?:\\.([0-9]+))?(?:\\.([0-9]+))?(-.*)?)(_(.*))?)\\/apis\\/((([a-z0-9-_ ]|[^\\\\x00-\\\\x7F])+.(json|yaml|yml)))",
"description": "A URI to the API definition resource."
}
},
"required": [
"created_at",
"filename",
"legacy_id",
"source",
"type",
"updated_at",
"upload",
"uri"
],
"additionalProperties": false
}
}
},
"required": ["total", "data"],
"additionalProperties": false
}
}
}
}
}
},
"post": {
"operationId": "createAPI",
"summary": "Create an API definition",
"tags": ["APIs"],
"description": "Create an API definition in the API Reference section of your ReadMe project.\n\n>📘\n> This route is only available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored).",
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"properties": {
"schema": {
"description": "The API definition."
},
"upload_source": {
"default": "form",
"description": "The source that the API definition is being uploaded through."
},
"url": {
"description": "The URL where the API definition is hosted."
}
},
"additionalProperties": false,
"description": "The API definition to upload. We provide full support for OpenAPI 3.x and Swagger 2.0 and experimental support for Postman collections."
}
}
},
"description": "The API definition to upload. We provide full support for OpenAPI 3.x and Swagger 2.0 and experimental support for Postman collections."
},
"parameters": [
{
"schema": {
"type": "string",
"pattern": "(v{0,1})(stable|([0-9]+)(?:\\.([0-9]+))?(?:\\.([0-9]+))?(-.*)?)(_(.*))?"
},
"in": "path",
"name": "branch",
"required": true,
"description": "Project version number, `stable` for your project's stable version, or a valid branch name."
}
],
"responses": {
"202": {
"description": "Accepted",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"upload": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": ["pending", "failed", "done", "pending_update", "failed_update"],
"description": "The status of the API definition upload."
}
},
"required": ["status"],
"additionalProperties": false
},
"uri": {
"type": "string",
"pattern": "\\/(versions|branches)\\/((v{0,1})(stable|([0-9]+)(?:\\.([0-9]+))?(?:\\.([0-9]+))?(-.*)?)(_(.*))?)\\/apis\\/((([a-z0-9-_ ]|[^\\\\x00-\\\\x7F])+.(json|yaml|yml)))",
"description": "A URI to the API definition resource."
}
},
"required": ["upload", "uri"],
"additionalProperties": false
}
},
"required": ["data"],
"additionalProperties": false
}
}
}
}
}
}
},
"/branches/{branch}/apis/{filename}": {
"get": {
"operationId": "getAPI",
"summary": "Get an API definition",
"tags": ["APIs"],
"description": "Get an API definition from your ReadMe project.\n\n>📘\n> This route is only available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored).",
"parameters": [
{
"schema": {
"type": "string",
"pattern": "(([a-z0-9-_ ]|[^\\\\x00-\\\\x7F])+.(json|yaml|yml))"
},
"in": "path",
"name": "filename",
"required": true,
"description": "The filename of the API definition to retrieve."
},
{
"schema": {
"type": "string",
"pattern": "(v{0,1})(stable|([0-9]+)(?:\\.([0-9]+))?(?:\\.([0-9]+))?(-.*)?)(_(.*))?"
},
"in": "path",
"name": "branch",
"required": true,
"description": "Project version number, `stable` for your project's stable version, or a valid branch name."
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"created_at": {
"type": "string",
"format": "date-time",
"description": "An ISO 8601 formatted date for when the API definition was created."
},
"filename": {
"type": "string",
"description": "This is the unique identifier, its filename, for the API definition."
},
"legacy_id": {
"type": "string",
"pattern": "[a-f\\d]{24}",
"nullable": true,
"description": "The legacy ID of your API definition. This is only used for legacy rdme CLI workflows and only applies if your project, and this API definition, predates ReadMe Refactored. We consider this value to be deprecated and recommend against relying on it going forward."
},
"source": {
"type": "object",
"properties": {
"current": {
"type": "string",
"enum": [
"api",
"apidesigner",
"apieditor",
"bidi",
"form",
"postman",
"rdme",
"rdme_github",
"url"
]
},
"original": {
"type": "string",
"enum": [
"api",
"apidesigner",
"apieditor",
"bidi",
"form",
"postman",
"rdme",
"rdme_github",
"url"
]
}
},
"required": ["current", "original"],
"additionalProperties": false,
"description": "The sources by which this API definition was ingested."
},
"type": {
"type": "string",
"enum": ["openapi", "postman", "swagger", "unknown"],
"description": "The type of API definition. This will be `unknown` if the API definition has either not yet been processed or failed with validation errors."
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "An ISO 8601 formatted date for when the API definition was last updated."
},
"upload": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": ["pending", "failed", "done", "pending_update", "failed_update"],
"description": "The status of the API definition upload."
},
"reason": {
"type": "string",
"nullable": true,
"description": "The reason for the upload failure if it failed."
},
"warnings": {
"type": "string",
"nullable": true,
"description": "Any fixable warnings that may exist within the API definition if the upload was ingested without errors."
}
},
"required": ["status", "reason", "warnings"],
"additionalProperties": false
},
"uri": {
"type": "string",
"pattern": "\\/(versions|branches)\\/((v{0,1})(stable|([0-9]+)(?:\\.([0-9]+))?(?:\\.([0-9]+))?(-.*)?)(_(.*))?)\\/apis\\/((([a-z0-9-_ ]|[^\\\\x00-\\\\x7F])+.(json|yaml|yml)))",
"description": "A URI to the API definition resource."
},
"schema": {
"nullable": true,
"description": "The API schema."
}
},
"required": [
"created_at",
"filename",
"legacy_id",
"source",
"type",
"updated_at",
"upload",
"uri"
],
"additionalProperties": false
}
},
"required": ["data"],
"additionalProperties": false
}
}
}
}
}
},
"delete": {
"operationId": "deleteAPI",
"summary": "Delete an API definition",
"tags": ["APIs"],
"description": "Delete an API definition from the API Reference section of your ReadMe project.\n\n>📘\n> This route is only available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored).",
"parameters": [
{
"schema": {
"type": "string",
"pattern": "(([a-z0-9-_ ]|[^\\\\x00-\\\\x7F])+.(json|yaml|yml))"
},
"in": "path",
"name": "filename",
"required": true,
"description": "The filename of the API definition to retrieve."
},
{
"schema": {
"type": "string",
"pattern": "(v{0,1})(stable|([0-9]+)(?:\\.([0-9]+))?(?:\\.([0-9]+))?(-.*)?)(_(.*))?"
},
"in": "path",
"name": "branch",
"required": true,
"description": "Project version number, `stable` for your project's stable version, or a valid branch name."
}
],
"responses": {
"204": {
"description": "No Content"
}
}
},
"put": {
"operationId": "updateAPI",
"summary": "Update an API definition",
"tags": ["APIs"],
"description": "Updates an API definition in the API Reference section of your ReadMe project.\n\n>📘\n> This route is only available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored).",
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"properties": {
"schema": {
"description": "The API definition."
},
"upload_source": {
"default": "form",
"description": "The source that the API definition is being uploaded through."
},
"url": {
"description": "The URL where the API definition is hosted."
}
},
"additionalProperties": false,
"description": "The API definition to upload. We provide full support for OpenAPI 3.x and Swagger 2.0 and experimental support for Postman collections."
}
}
},
"description": "The API definition to upload. We provide full support for OpenAPI 3.x and Swagger 2.0 and experimental support for Postman collections."
},
"parameters": [
{
"schema": {
"type": "string",
"pattern": "(([a-z0-9-_ ]|[^\\\\x00-\\\\x7F])+.(json|yaml|yml))"
},
"in": "path",
"name": "filename",
"required": true,
"description": "The filename of the API definition to retrieve."
},
{
"schema": {
"type": "string",
"pattern": "(v{0,1})(stable|([0-9]+)(?:\\.([0-9]+))?(?:\\.([0-9]+))?(-.*)?)(_(.*))?"
},
"in": "path",
"name": "branch",
"required": true,
"description": "Project version number, `stable` for your project's stable version, or a valid branch name."
}
],
"responses": {
"202": {
"description": "Accepted",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"upload": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": ["pending", "failed", "done", "pending_update", "failed_update"],
"description": "The status of the API definition upload."
}
},
"required": ["status"],
"additionalProperties": false
},
"uri": {
"type": "string",
"pattern": "\\/(versions|branches)\\/((v{0,1})(stable|([0-9]+)(?:\\.([0-9]+))?(?:\\.([0-9]+))?(-.*)?)(_(.*))?)\\/apis\\/((([a-z0-9-_ ]|[^\\\\x00-\\\\x7F])+.(json|yaml|yml)))",
"description": "A URI to the API definition resource."
}
},
"required": ["upload", "uri"],
"additionalProperties": false
}
},
"required": ["data"],
"additionalProperties": false
}
}
}
}
}
}
},
"/apply": {
"get": {
"operationId": "getOpenRoles",
"summary": "Get open roles",
"tags": ["Apply to ReadMe"],
"description": "Returns all the roles we're hiring for at ReadMe!",
"security": [],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"total": {
"type": "number"
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"slug": {
"type": "string"
},
"title": {
"type": "string"
},
"description": {
"type": "string",
"description": "The description for this open position. This content is formatted as HTML."
},
"pullquote": {
"type": "string",
"description": "A short pullquote for the open position."
},
"location": {
"type": "string",
"description": "Where this position is located at."
},
"department": {
"type": "string",
"description": "The internal organization you'll be working in."
},
"url": {
"type": "string",
"format": "uri",
"description": "The place where you can apply for the position!"
}
},
"required": ["slug", "title", "description", "pullquote", "location", "department", "url"],
"additionalProperties": false
}
}
},
"required": ["total", "data"],
"additionalProperties": false
}
}
}
}
}
},
"post": {
"operationId": "applyToReadMe",
"summary": "Submit your application!",
"tags": ["Apply to ReadMe"],
"description": "This endpoint will let you apply to a job at ReadMe programatically, without having to go through our UI!",
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"description": "Your full name"
},
"email": {
"type": "string",
"format": "email",
"default": "you@example.com",
"description": "A valid email we can reach you at."
},
"job": {
"type": "string",
"description": "The job you're looking to apply for (https://readme.com/careers)."
},
"pronouns": {
"type": "string",
"description": "Learn more at https://lgbtlifecenter.org/pronouns/"
},
"linkedin": {
"type": "string",
"format": "uri",
"description": "What have you been up to the past few years?"
},
"github": {
"type": "string",
"format": "uri",
"description": "Or Bitbucket, GitLab or anywhere else your code is hosted!"
},
"coverLetter": {
"type": "string",
"description": "What should we know about you?"
},
"dont_really_apply": {
"type": "boolean",
"default": false,
"description": "If you set this to true, we will not actually apply you to the job."
}
},
"required": ["name", "job"],
"additionalProperties": false
}
}
},
"required": true
},
"security": [],
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string"
},
"keyvalues": {
"type": "string"
},
"careers": {
"type": "string"
},
"questions?": {
"type": "string"
},
"poem": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": ["message", "keyvalues", "careers", "questions?", "poem"],
"additionalProperties": false
}
}
}
}
}
}
},
"/branches/{branch}/categories": {
"post": {
"operationId": "createCategory",
"summary": "Create a category",
"tags": ["Categories"],
"description": "Create a category in your ReadMe project.\n\n>📘\n> This route is only available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored).",
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "The category's name."
},
"section": {
"type": "string",
"enum": ["guide", "reference"],
"default": "guide",
"description": "The section of your documentation where the category resides."
}
},
"required": ["title"],
"additionalProperties": false
}
}
},
"required": true
},
"parameters": [
{
"schema": {
"type": "string",
"pattern": "(v{0,1})(stable|([0-9]+)(?:\\.([0-9]+))?(?:\\.([0-9]+))?(-.*)?)(_(.*))?"
},
"in": "path",
"name": "branch",
"required": true,
"description": "Project version number, `stable` for your project's stable version, or a valid branch name."
}
],
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "The category's name."
},
"section": {
"type": "string",
"enum": ["guide", "reference"],
"default": "guide",
"description": "The section of your documentation where the category resides."
},
"links": {
"type": "object",
"properties": {
"project": {
"type": "string",
"pattern": "\\/projects\\/(me|[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)",
"description": "A URI to the project that this category belongs to."
}
},
"required": ["project"],
"additionalProperties": false
},
"uri": {
"type": "string",
"pattern": "\\/(versions|branches)\\/((v{0,1})(stable|([0-9]+)(?:\\.([0-9]+))?(?:\\.([0-9]+))?(-.*)?)(_(.*))?)\\/categories\\/(guides|reference)\\/((.*))",
"description": "A URI to the category resource."
}
},
"required": ["title", "links", "uri"],
"additionalProperties": false
}
},
"required": ["data"],
"additionalProperties": false
}
}
}
}
}
}
},
"/branches/{branch}/categories/{section}": {
"get": {
"operationId": "getCategories",
"summary": "Get all categories",
"tags": ["Categories"],
"description": "Get all categories within a section of your ReadMe project.\n\nThe sorting of this data is dependent upon the order of the categories in your sidebar.\n\n>📘\n> This route is only available to projects that are using [ReadMe Refactored](https://docs.readme.com/main/docs/welcome-to-readme-refactored).",
"parameters": [
{
"schema": {
"type": "string",
"enum": ["guides", "reference"]
},
"in": "path",
"name": "section",
"required": true,
"description": "The section of your documentation to get categories from."
},
{
"schema": {
"type": "string",
"pattern": "(v{0,1})(stable|([0-9]+)(?:\\.([0-9]+))?(?:\\.([0-9]+))?(-.*)?)(_(.*))?"
},
"in": "path",
"name": "branch",
"required": true,
"description": "Project version number, `stable` for your project's stable version, or a valid branch name."
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"total": {
"type": "number"
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"title": {
"type": "string",