{
"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",
"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": ["total", "data"],
"additionalProperties": false
}
}
}
}
}
}
},
"/branches/{branch}/categories/{section}/{title}": {
"get": {
"operationId": "getCategory",
"summary": "Get a category",
"tags": ["Categories"],
"description": "Get 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).",
"parameters": [
{
"schema": {
"type": "string",
"enum": ["guides", "reference"],
"default": "guides"
},
"in": "path",
"name": "section",
"required": true,
"description": "The section of your documentation where the category resides."
},
{
"schema": {
"type": "string"
},
"in": "path",
"name": "title",
"required": true,
"description": "The category's name."
},
{
"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": {
"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
}
}
}
}
}
},
"delete": {
"operationId": "deleteCategory",
"summary": "Delete a category",
"tags": ["Categories"],
"description": "Delete a category 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",
"enum": ["guides", "reference"],
"default": "guides"
},
"in": "path",
"name": "section",
"required": true,
"description": "The section of your documentation where the category resides."
},
{
"schema": {
"type": "string"
},
"in": "path",
"name": "title",
"required": true,
"description": "The category's name."
},
{
"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"
}
}
},
"patch": {
"operationId": "updateCategory",
"summary": "Update a category",
"tags": ["Categories"],
"description": "Update an existing 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."
},
"position": {
"type": "number",
"description": "The position of the category in your project's sidebar."
}
},
"additionalProperties": false
}
}
}
},
"parameters": [
{
"schema": {
"type": "string",
"enum": ["guides", "reference"],
"default": "guides"
},
"in": "path",
"name": "section",
"required": true,
"description": "The section of your documentation where the category resides."
},
{
"schema": {
"type": "string"
},
"in": "path",
"name": "title",
"required": true,
"description": "The category's name."
},
{
"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": {
"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}/{title}/pages": {
"get": {
"operationId": "getCategoryPages",
"summary": "Get the pages within a category",
"tags": ["Categories"],
"description": "Get a pages that exist within 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).",
"parameters": [
{
"schema": {
"type": "string",
"enum": ["guides", "reference"],
"default": "guides"
},
"in": "path",
"name": "section",
"required": true,
"description": "The section of your documentation where the category resides."
},
{
"schema": {
"type": "string"
},
"in": "path",
"name": "title",
"required": true,
"description": "The category's name."
},
{
"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": {
"category": {
"type": "object",
"properties": {
"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": ["uri"],
"additionalProperties": false
},
"parent": {
"type": "object",
"properties": {
"uri": {
"type": "string",
"pattern": "\\/(versions|branches)\\/((v{0,1})(stable|([0-9]+)(?:\\.([0-9]+))?(?:\\.([0-9]+))?(-.*)?)(_(.*))?)\\/(guides|reference)\\/(([a-z0-9-_ ]|[^\\\\x00-\\\\x7F])+)",
"nullable": true,
"description": "A URI to the parent page resource including the page ID or slug."
}
},
"required": ["uri"],
"additionalProperties": false
},
"slug": {
"allOf": [
{
"type": "string"
},
{
"type": "string",
"minLength": 1
}
],
"description": "The accessible URL slug for the page."
},
"title": {
"type": "string"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "An ISO 8601 formatted date for when the page was updated."
},
"uri": {
"type": "string",
"pattern": "\\/(versions|branches)\\/((v{0,1})(stable|([0-9]+)(?:\\.([0-9]+))?(?:\\.([0-9]+))?(-.*)?)(_(.*))?)\\/(guides|reference)\\/(([a-z0-9-_ ]|[^\\\\x00-\\\\x7F])+)",
"description": "A URI to the page resource."
}
},
"required": ["category", "parent", "slug", "title", "updated_at", "uri"],
"additionalProperties": false
}
}
},
"required": ["total", "data"],
"additionalProperties": false
}
}
}
}
}
}
},
"/changelogs": {
"post": {
"operationId": "createChangelog",
"summary": "Create a changelog entry",
"tags": ["Changelog"],
"description": "Create a new changelog entry in your ReadMe project.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"author": {
"type": "object",
"properties": {
"id": {
"type": "string",
"nullable": true
}
},
"additionalProperties": false
},
"content": {
"type": "object",
"properties": {
"body": {
"type": "string",
"nullable": true
}
},
"additionalProperties": false
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "An ISO 8601 formatted date for when the changelog was created."
},
"metadata": {
"type": "object",
"properties": {
"description": {
"type": "string",
"nullable": true
},
"image": {
"type": "object",
"properties": {
"uri": {
"type": "string",
"pattern": "\\/images\\/([a-f\\d]{24})",
"nullable": true
},
"url": {
"type": "string",
"format": "uri",
"nullable": true
}
},
"additionalProperties": false
},
"keywords": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
}
},
"additionalProperties": false
},
"privacy": {
"type": "object",
"properties": {
"view": {
"type": "string",
"enum": ["public", "anyone_with_link"],
"default": "anyone_with_link",
"description": "The visibility of this changelog."
}
},
"additionalProperties": false
},
"slug": {
"type": "string"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"enum": ["none", "added", "fixed", "improved", "deprecated", "removed"],
"default": "none",
"description": "The type of changelog that this is."
}
},
"required": ["title"],
"additionalProperties": false
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"author": {
"type": "object",
"properties": {
"id": {
"type": "string",
"nullable": true,
"description": "User ID of the changelog author."
},
"name": {
"type": "string",
"nullable": true,
"description": "Full name of the user who created the changelog."
}
},
"required": ["id", "name"],
"additionalProperties": false
},
"content": {
"type": "object",
"properties": {
"body": {
"type": "string",
"nullable": true
}
},
"required": ["body"],
"additionalProperties": false
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "An ISO 8601 formatted date for when the changelog was created."
},
"metadata": {
"type": "object",
"properties": {
"description": {
"type": "string",
"nullable": true
},
"image": {
"type": "object",
"properties": {
"uri": {
"type": "string",
"pattern": "\\/images\\/([a-f\\d]{24})",
"nullable": true,
"description": "A URI to the `getImages` endpoint for this image. If the is a legacy image then this `uri` will be `null`. And if you wish to delete this image then you should set this to `null`."
},
"url": {
"type": "string",
"format": "uri",
"nullable": true
}
},
"required": ["uri", "url"],
"additionalProperties": false
},
"keywords": {
"type": "string",
"nullable": true,
"description": "A comma-separated list of keywords to place into your changelog metadata."
},
"title": {
"type": "string",
"nullable": true
}
},
"required": ["description", "image", "keywords", "title"],
"additionalProperties": false
},
"privacy": {
"type": "object",
"properties": {
"view": {
"type": "string",
"enum": ["public", "anyone_with_link"],
"default": "anyone_with_link",
"description": "The visibility of this changelog."
}
},
"additionalProperties": false
},
"slug": {
"type": "string"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"enum": ["none", "added", "fixed", "improved", "deprecated", "removed"],
"default": "none",
"description": "The type of changelog that this is."
},
"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 changelog belongs to."
}
},
"required": ["project"],
"additionalProperties": false
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "An ISO 8601 formatted date for when the changelog was updated."
},
"uri": {
"type": "string",
"pattern": "\\/changelogs\\/([a-f\\d]{24}|([a-z0-9-_ ]|[^\\\\x00-\\\\x7F])+)"
}
},
"required": [
"author",
"content",
"created_at",
"metadata",
"privacy",
"slug",
"title",
"links",
"updated_at",
"uri"
],
"additionalProperties": false
}
},
"required": ["data"],
"additionalProperties": false
}
}
}
}
}
},
"get": {
"operationId": "getChangelogs",
"summary": "Get all changelog entries",
"tags": ["Changelog"],
"description": "Get all changelog entries from 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",
"enum": ["public", "anyone_with_link", "all"],
"default": "all"
},
"in": "query",
"name": "visibility",
"required": false,
"description": "The visibility setting (`privacy.view`) for the changelog entries you wish to retrieve. Defaults to `all`."
}
],
"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": {
"author": {
"type": "object",
"properties": {
"id": {
"type": "string",
"nullable": true,
"description": "User ID of the changelog author."
},
"name": {
"type": "string",
"nullable": true,
"description": "Full name of the user who created the changelog."
}
},
"required": ["id", "name"],
"additionalProperties": false
},
"content": {
"type": "object",
"properties": {
"body": {
"type": "string",
"nullable": true
}
},
"required": ["body"],
"additionalProperties": false
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "An ISO 8601 formatted date for when the changelog was created."
},
"metadata": {
"type": "object",
"properties": {
"description": {
"type": "string",
"nullable": true
},
"image": {
"type": "object",
"properties": {
"uri": {
"type": "string",
"pattern": "\\/images\\/([a-f\\d]{24})",
"nullable": true,
"description": "A URI to the `getImages` endpoint for this image. If the is a legacy image then this `uri` will be `null`. And if you wish to delete this image then you should set this to `null`."
},
"url": {
"type": "string",
"format": "uri",
"nullable": true
}
},
"required": ["uri", "url"],
"additionalProperties": false
},
"keywords": {
"type": "string",
"nullable": true,
"description": "A comma-separated list of keywords to place into your changelog metadata."
},
"title": {
"type": "string",
"nullable": true
}
},
"required": ["description", "image", "keywords", "title"],
"additionalProperties": false
},
"privacy": {
"type": "object",
"properties": {
"view": {
"type": "string",
"enum": ["public", "anyone_with_link"],
"default": "anyone_with_link",
"description": "The visibility of this changelog."
}
},
"additionalProperties": false
},
"slug": {
"type": "string"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"enum": ["none", "added", "fixed", "improved", "deprecated", "removed"],
"default": "none",
"description": "The type of changelog that this is."
},
"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 changelog belongs to."
}
},
"required": ["project"],
"additionalProperties": false
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "An ISO 8601 formatted date for when the changelog was updated."
},
"uri": {
"type": "string",
"pattern": "\\/changelogs\\/([a-f\\d]{24}|([a-z0-9-_ ]|[^\\\\x00-\\\\x7F])+)"
}
},
"required": [
"author",
"content",
"created_at",
"metadata",
"privacy",
"slug",
"title",
"links",
"updated_at",
"uri"
],
"additionalProperties": false
}
}
},
"required": ["total", "page", "per_page", "paging", "data"],
"additionalProperties": false
}
}
}
}
}
}
},
"/changelogs/{identifier}": {
"get": {
"operationId": "getChangelog",
"summary": "Get a changelog entry",
"tags": ["Changelog"],
"description": "Get a changelog entry from your ReadMe project.",
"parameters": [
{
"schema": {
"anyOf": [
{
"type": "string",
"pattern": "[a-f\\d]{24}",
"description": "A unique identifier for the resource."
},
{
"type": "string",
"pattern": "([a-z0-9-_ ]|[^\\\\x00-\\\\x7F])+",
"description": "A URL-safe representation of the resource."
}
]
},
"in": "path",
"name": "identifier",
"required": true,
"description": "The unique identifier for the resource."
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"author": {
"type": "object",
"properties": {
"id": {
"type": "string",
"nullable": true,
"description": "User ID of the changelog author."
},
"name": {
"type": "string",
"nullable": true,
"description": "Full name of the user who created the changelog."
}
},
"required": ["id", "name"],
"additionalProperties": false
},
"content": {
"type": "object",
"properties": {
"body": {
"type": "string",
"nullable": true
}
},
"required": ["body"],
"additionalProperties": false
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "An ISO 8601 formatted date for when the changelog was created."
},
"metadata": {
"type": "object",
"properties": {
"description": {
"type": "string",
"nullable": true
},
"image": {
"type": "object",
"properties": {
"uri": {
"type": "string",
"pattern": "\\/images\\/([a-f\\d]{24})",
"nullable": true,
"description": "A URI to the `getImages` endpoint for this image. If the is a legacy image then this `uri` will be `null`. And if you wish to delete this image then you should set this to `null`."
},
"url": {
"type": "string",
"format": "uri",
"nullable": true
}
},
"required": ["uri", "url"],
"additionalProperties": false
},
"keywords": {
"type": "string",
"nullable": true,
"description": "A comma-separated list of keywords to place into your changelog metadata."
},
"title": {
"type": "string",
"nullable": true
}
},
"required": ["description", "image", "keywords", "title"],
"additionalProperties": false
},
"privacy": {
"type": "object",
"properties": {
"view": {
"type": "string",
"enum": ["public", "anyone_with_link"],
"default": "anyone_with_link",
"description": "The visibility of this changelog."
}
},
"additionalProperties": false
},
"slug": {
"type": "string"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"enum": ["none", "added", "fixed", "improved", "deprecated", "removed"],
"default": "none",
"description": "The type of changelog that this is."
},
"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 changelog belongs to."
}
},
"required": ["project"],
"additionalProperties": false
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "An ISO 8601 formatted date for when the changelog was updated."
},
"uri": {
"type": "string",
"pattern": "\\/changelogs\\/([a-f\\d]{24}|([a-z0-9-_ ]|[^\\\\x00-\\\\x7F])+)"
}
},
"required": [
"author",
"content",
"created_at",
"metadata",
"privacy",
"slug",
"title",
"links",
"updated_at",
"uri"
],
"additionalProperties": false
}
},
"required": ["data"],
"additionalProperties": false
}
}
}
}
}
},
"delete": {
"operationId": "deleteChangelog",
"summary": "Delete a changelog entry",
"tags": ["Changelog"],
"description": "Delete a changelog entry from your ReadMe project.",
"parameters": [
{
"schema": {
"anyOf": [
{
"type": "string",
"pattern": "[a-f\\d]{24}",
"description": "A unique identifier for the resource."
},
{
"type": "string",
"pattern": "([a-z0-9-_ ]|[^\\\\x00-\\\\x7F])+",
"description": "A URL-safe representation of the resource."
}
]
},
"in": "path",
"name": "identifier",
"required": true,
"description": "The unique identifier for the resource."
}
],
"responses": {
"204": {
"description": "No Content"
}
}
},
"patch": {
"operationId": "updateChangelog",
"summary": "Update a changelog entry",
"tags": ["Changelog"],
"description": "Update an existing changelog entry in your ReadMe project.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"author": {
"type": "object",
"properties": {
"id": {
"type": "string",
"nullable": true
},
"name": {
"type": "string",
"nullable": true
}
},
"additionalProperties": false
},
"content": {
"type": "object",
"properties": {
"body": {
"type": "string",
"nullable": true
}
},
"additionalProperties": false
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "An ISO 8601 formatted date for when the changelog was created."
},
"metadata": {
"type": "object",
"properties": {
"description": {
"type": "string",
"nullable": true
},
"image": {
"type": "object",
"properties": {
"uri": {
"type": "string",
"pattern": "\\/images\\/([a-f\\d]{24})",
"nullable": true
},
"url": {
"type": "string",
"format": "uri",
"nullable": true
}
},
"additionalProperties": false
},
"keywords": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
}
},
"additionalProperties": false
},
"privacy": {
"type": "object",
"properties": {
"view": {
"type": "string",
"enum": ["public", "anyone_with_link"],
"default": "anyone_with_link",
"description": "The visibility of this changelog."
}
},
"additionalProperties": false
},
"slug": {
"type": "string"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"enum": ["none", "added", "fixed", "improved", "deprecated", "removed"],
"default": "none",
"description": "The type of changelog that this is."
}
},
"additionalProperties": false
}
}
}
},
"parameters": [
{
"schema": {
"anyOf": [
{
"type": "string",
"pattern": "[a-f\\d]{24}",
"description": "A unique identifier for the resource."
},
{
"type": "string",
"pattern": "([a-z0-9-_ ]|[^\\\\x00-\\\\x7F])+",
"description": "A URL-safe representation of the resource."
}
]
},
"in": "path",
"name": "identifier",
"required": true,
"description": "The unique identifier for the resource."
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"author": {
"type": "object",
"properties": {
"id": {
"type": "string",
"nullable": true,
"description": "User ID of the changelog author."
},
"name": {
"type": "string",
"nullable": true,
"description": "Full name of the user who created the changelog."
}
},
"required": ["id", "name"],
"additionalProperties": false
},
"content": {
"type": "object",
"properties": {
"body": {
"type": "string",
"nullable": true
}
},
"required": ["body"],
"additionalProperties": false
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "An ISO 8601 formatted date for when the changelog was created."
},
"metadata": {
"type": "object",
"properties": {
"description": {
"type": "string",
"nullable": true
},
"image": {
"type": "object",
"properties": {
"uri": {
"type": "string",
"pattern": "\\/images\\/([a-f\\d]{24})",
"nullable": true,
"description": "A URI to the `getImages` endpoint for this image. If the is a legacy image then this `uri` will be `null`. And if you wish to delete this image then you should set this to `null`."
},
"url": {
"type": "string",
"format": "uri",
"nullable": true
}
},
"required": ["uri", "url"],
"additionalProperties": false
},
"keywords": {
"type": "string",
"nullable": true,
"description": "A comma-separated list of keywords to place into your changelog metadata."
},
"title": {
"type": "string",
"nullable": true
}
},
"required": ["description", "image", "keywords", "title"],
"additionalProperties": false
},
"privacy": {
"type": "object",
"properties": {
"view": {
"type": "string",
"enum": ["public", "anyone_with_link"],
"default": "anyone_with_link",
"description": "The visibility of this changelog."
}
},
"additionalProperties": false
},
"slug": {
"type": "string"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"enum": ["none", "added", "fixed", "improved", "deprecated", "removed"],
"default": "none",
"description": "The type of changelog that this is."
},
"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 changelog belongs to."
}
},
"required": ["project"],
"additionalProperties": false
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "An ISO 8601 formatted date for when the changelog was updated."
},
"uri": {
"type": "string",
"pattern": "\\/changelogs\\/([a-f\\d]{24}|([a-z0-9-_ ]|[^\\\\x00-\\\\x7F])+)"
}
},
"required": [
"author",
"content",
"created_at",
"metadata",
"privacy",
"slug",
"title",
"links",
"updated_at",
"uri"
],
"additionalProperties": false
}
},
"required": ["data"],
"additionalProperties": false
}
}
}
}
}
}
},
"/branches/{branch}/custom_pages": {
"post": {
"operationId": "createCustomPage",
"summary": "Create a custom page",
"tags": ["Custom Pages"],
"description": "Create a custom page 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": {
"appearance": {
"type": "object",
"properties": {
"fullscreen": {
"type": "boolean",
"default": false,
"description": "Whether a html custom page is fullscreen or not."
}
},
"additionalProperties": false
},
"content": {
"type": "object",
"properties": {
"body": {
"type": "string",
"nullable": true
},
"type": {
"type": "string",
"enum": ["markdown", "html"],
"default": "markdown",
"description": "The type of content contained in this custom page."
}
},
"additionalProperties": false
},
"metadata": {
"type": "object",
"properties": {
"description": {
"type": "string",
"nullable": true
},
"image": {
"type": "object",
"properties": {
"uri": {
"type": "string",
"pattern": "\\/images\\/([a-f\\d]{24})",
"nullable": true
},
"url": {
"type": "string",
"format": "uri",
"nullable": true
}
},
"additionalProperties": false
},
"keywords": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
}
},
"additionalProperties": false
},
"privacy": {
"type": "object",
"properties": {
"view": {
"type": "string",
"enum": ["public", "anyone_with_link"],
"default": "anyone_with_link",
"description": "The visibility of this custom page."
}
},
"additionalProperties": false
},
"slug": {
"type": "string",
"pattern": "([a-z0-9-_ ]|[^\\\\x00-\\\\x7F])+"
},
"title": {
"type": "string",
"nullable": true
}
},
"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": {
"appearance": {
"type": "object",
"properties": {
"fullscreen": {
"type": "boolean",
"default": false,
"description": "Whether a html custom page is fullscreen or not."
}
},
"additionalProperties": false
},
"content": {
"type": "object",
"properties": {
"body": {
"type": "string",
"nullable": true
},
"type": {
"type": "string",
"enum": ["markdown", "html"],
"default": "markdown",
"description": "The type of content contained in this custom page."
}
},
"required": ["body"],
"additionalProperties": false
},
"metadata": {
"type": "object",
"properties": {
"description": {
"type": "string",
"nullable": true
},
"image": {
"type": "object",
"properties": {
"uri": {
"type": "string",
"pattern": "\\/images\\/([a-f\\d]{24})",
"nullable": true,
"description": "A URI to the `getImages` endpoint for this image. If the is a legacy image then this `uri` will be `null`. And if you wish to delete this image then you should set this to `null`."
},
"url": {
"type": "string",
"format": "uri",
"nullable": true
}
},
"required": ["uri", "url"],
"additionalProperties": false
},
"keywords": {
"type": "string",
"nullable": true,
"description": "A comma-separated list of keywords to place into your custom page metadata."
},
"title": {
"type": "string",
"nullable": true
}
},
"required": ["description", "image", "keywords", "title"],
"additionalProperties": false
},
"privacy": {
"type": "object",
"properties": {
"view": {
"type": "string",
"enum": ["public", "anyone_with_link"],
"default": "anyone_with_link",
"description": "The visibility of this custom page."
}
},
"additionalProperties": false
},
"slug": {
"type": "string",
"pattern": "([a-z0-9-_ ]|[^\\\\x00-\\\\x7F])+"
},
"title": {
"type": "string",
"nullable": true
},
"links": {
"type": "object",
"properties": {
"project": {
"type": "string",
"pattern": "\\/projects\\/(me|[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)",
"description": "A URI to the project resource."
}
},
"required": ["project"],
"additionalProperties": false
},
"renderable": {
"type": "object",
"properties": {
"status": {
"type": "boolean",
"default": true,
"description": "A flag for if the resource is renderable or not."
},
"error": {
"type": "string",
"nullable": true,
"description": "The rendering error."
},
"message": {
"type": "string",
"nullable": true,
"description": "Additional details about the rendering error."
}
},
"additionalProperties": false
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "An ISO 8601 formatted date for when the custom page was updated.",
"nullable": true
},
"uri": {
"type": "string",
"pattern": "\\/(versions|branches)\\/((v{0,1})(stable|([0-9]+)(?:\\.([0-9]+))?(?:\\.([0-9]+))?(-.*)?)(_(.*))?)\\/custom_pages\\/([a-f\\d]{24}|([a-z0-9-_ ]|[^\\\\x00-\\\\x7F])+)"
}
},
"required": [
"appearance",
"content",
"metadata",
"privacy",
"slug",
"title",
"links",
"renderable",
"updated_at",
"uri"
],
"additionalProperties": false
}
},
"required": ["data"],
"additionalProperties": false
}
}
}
}
}
},
"get": {
"operationId": "getCustomPages",
"summary": "Get all custom pages",
"tags": ["Custom Pages"],
"description": "Get all custom pages 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": {
"appearance": {
"type": "object",
"properties": {
"fullscreen": {
"type": "boolean",
"default": false,
"description": "Whether a html custom page is fullscreen or not."
}
},
"additionalProperties": false
},
"content": {
"type": "object",
"properties": {
"body": {
"type": "string",
"nullable": true
},
"type": {
"type": "string",
"enum": ["markdown", "html"],
"default": "markdown",
"description": "The type of content contained in this custom page."
}
},
"required": ["body"],
"additionalProperties": false
},
"metadata": {
"type": "object",
"properties": {
"description": {
"type": "string",
"nullable": true
},
"image": {
"type": "object",
"properties": {
"uri": {
"type": "string",
"pattern": "\\/images\\/([a-f\\d]{24})",
"nullable": true,
"description": "A URI to the `getImages` endpoint for this image. If the is a legacy image then this `uri` will be `null`. And if you wish to delete this image then you should set this to `null`."
},
"url": {
"type": "string",
"format": "uri",
"nullable": true
}
},
"required": ["uri", "url"],
"additionalProperties": false
},
"keywords": {
"type": "string",
"nullable": true,
"description": "A comma-separated list of keywords to place into your custom page metadata."
},
"title": {
"type": "string",
"nullable": true
}
},
"required": ["description", "image", "keywords", "title"],
"additionalProperties": false
},
"privacy": {
"type": "object",
"properties": {
"view": {
"type": "string",
"enum": ["public", "anyone_with_link"],
"default": "anyone_with_link",
"description": "The visibility of this custom page."
}
},
"additionalProperties": false
},
"slug": {
"type": "string",
"pattern": "([a-z0-9-_ ]|[^\\\\x00-\\\\x7F])+"
},
"title": {
"type": "string",
"nullable": true
},
"links": {
"type": "object",
"properties": {
"project": {
"type": "string",
"pattern": "\\/projects\\/(me|[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)",
"description": "A URI to the project resource."
}
},
"required": ["project"],
"additionalProperties": false
},
"renderable": {
"type": "object",
"properties": {
"status": {
"type": "boolean",
"default": true,
"description": "A flag for if the resource is renderable or not."
},
"error": {
"type": "string",
"nullable": true,
"description": "The rendering error."
},
"message": {
"type": "string",
"nullable": true,
"description": "Additional details about the rendering error."
}
},
"additionalProperties": false
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "An ISO 8601 formatted date for when the custom page was updated.",
"nullable": true
},
"uri": {
"type": "string",
"pattern": "\\/(versions|branches)\\/((v{0,1})(stable|([0-9]+)(?:\\.([0-9]+))?(?:\\.([0-9]+))?(-.*)?)(_(.*))?)\\/custom_pages\\/([a-f\\d]{24}|([a-z0-9-_ ]|[^\\\\x00-\\\\x7F])+)"
}
},
"required": [
"appearance",
"content",
"metadata",
"privacy",
"slug",
"title",
"links",
"renderable",
"updated_at",
"uri"
],
"additionalProperties": false
}
}
},
"required": ["total", "data"],
"additionalProperties": false
}
}
}
}
}
}
},
"/branches/{branch}/custom_pages/{slug}": {
"get": {
"operationId": "getCustomPage",
"summary": "Get a custom page",
"tags": ["Custom Pages"],
"description": "Get a custom page 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."
},
{
"schema": {
"type": "string",
"pattern": "([a-z0-9-_ ]|[^\\\\x00-\\\\x7F])+"
},
"in": "path",
"name": "slug",
"required": true,
"description": "A URL-safe representation of the resource."
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"appearance": {
"type": "object",
"properties": {
"fullscreen": {
"type": "boolean",
"default": false,
"description": "Whether a html custom page is fullscreen or not."
}
},
"additionalProperties": false
},
"content": {
"type": "object",
"properties": {
"body": {
"type": "string",
"nullable": true
},
"type": {
"type": "string",
"enum": ["markdown", "html"],
"default": "markdown",
"description": "The type of content contained in this custom page."
}
},
"required": ["body"],
"additionalProperties": false
},
"metadata": {
"type": "object",
"properties": {
"description": {
"type": "string",
"nullable": true
},
"image": {
"type": "object",
"properties": {
"uri": {
"type": "string",
"pattern": "\\/images\\/([a-f\\d]{24})",
"nullable": true,
"description": "A URI to the `getImages` endpoint for this image. If the is a legacy image then this `uri` will be `null`. And if you wish to delete this image then you should set this to `null`."
},
"url": {
"type": "string",
"format": "uri",
"nullable": true
}
},
"required": ["uri", "url"],
"additionalProperties": false
},
"keywords": {
"type": "string",
"nullable": true,
"description": "A comma-separated list of keywords to place into your custom page metadata."
},
"title": {
"type": "string",
"nullable": true
}
},
"required": ["description", "image", "keywords", "title"],
"additionalProperties": false
},
"privacy": {
"type": "object",
"properties": {
"view": {
"type": "string",
"enum": ["public", "anyone_with_link"],
"default": "anyone_with_link",
"description": "The visibility of this custom page."
}
},
"additionalProperties": false
},
"slug": {
"type": "string",
"pattern": "([a-z0-9-_ ]|[^\\\\x00-\\\\x7F])+"
},
"title": {
"type": "string",
"nullable": true
},
"links": {
"type": "object",
"properties": {
"project": {
"type": "string",
"pattern": "\\/projects\\/(me|[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)",
"description": "A URI to the project resource."
}
},
"required": ["project"],
"additionalProperties": false
},
"renderable": {
"type": "object",
"properties": {
"status": {
"type": "boolean",
"default": true,
"description": "A flag for if the resource is renderable or not."
},
"error": {
"type": "string",
"nullable": true,
"description": "The rendering error."
},
"message": {
"type": "string",
"nullable": true,
"description": "Additional details about the rendering error."
}
},
"additionalProperties": false
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "An ISO 8601 formatted date for when the custom page was updated.",
"nullable": true
},
"uri": {
"type": "string",
"pattern": "\\/(versions|branches)\\/((v{0,1})(stable|([0-9]+)(?:\\.([0-9]+))?(?:\\.([0-9]+))?(-.*)?)(_(.*))?)\\/custom_pages\\/([a-f\\d]{24}|([a-z0-9-_ ]|[^\\\\x00-\\\\x7F])+)"
}
},
"required": [
"appearance",
"content",
"metadata",
"privacy",
"slug",
"title",
"links",
"renderable",
"updated_at",
"uri"
],
"additionalProperties": false
}
},
"required": ["data"],
"additionalProperties": false
}
}
}
}
}
},
"delete": {
"operationId": "deleteCustomPage",
"summary": "Delete a custom page",
"tags": ["Custom Pages"],
"description": "Delete a custom page 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."
},
{
"schema": {
"type": "string",
"pattern": "([a-z0-9-_ ]|[^\\\\x00-\\\\x7F])+"
},
"in": "path",
"name": "slug",
"required": true,
"description": "A URL-safe representation of the resource."
}
],
"responses": {
"204": {
"description": "No Content"
}
}
},
"patch": {
"operationId": "updateCustomPage",
"summary": "Update a custom page",
"tags": ["Custom Pages"],
"description": "Update an existing custom page 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": {
"appearance": {
"type": "object",
"properties": {
"fullscreen": {
"type": "boolean",
"default": false,
"description": "Whether a html custom page is fullscreen or not."
}
},
"additionalProperties": false
},
"content": {
"type": "object",
"properties": {
"body": {
"type": "string",
"nullable": true
},
"type": {
"type": "string",
"enum": ["markdown", "html"],
"default": "markdown",
"description": "The type of content contained in this custom page."
}
},
"additionalProperties": false
},
"metadata": {
"type": "object",
"properties": {
"description": {
"type": "string",
"nullable": true
},
"image": {
"type": "object",
"properties": {
"uri": {
"type": "string",
"pattern": "\\/images\\/([a-f\\d]{24})",
"nullable": true
},
"url": {
"type": "string",
"format": "uri",
"nullable": true
}
},
"additionalProperties": false
},
"keywords": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
}
},
"additionalProperties": false
},
"privacy": {
"type": "object",
"properties": {
"view": {
"type": "string",
"enum": ["public", "anyone_with_link"],
"default": "anyone_with_link",
"description": "The visibility of this custom page."
}
},
"additionalProperties": false
},
"slug": {
"type": "string",
"pattern": "([a-z0-9-_ ]|[^\\\\x00-\\\\x7F])+"
},
"title": {
"type": "string",
"nullable": true
}
},
"additionalProperties": false
}
}
}
},
"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."
},
{
"schema": {
"type": "string",
"pattern": "([a-z0-9-_ ]|[^\\\\x00-\\\\x7F])+"
},
"in": "path",
"name": "slug",
"required": true,
"description": "A URL-safe representation of the resource."
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"appearance": {
"type": "object",
"properties": {
"fullscreen": {
"type": "boolean",
"default": false,
"description": "Whether a html custom page is fullscreen or not."
}
},
"additionalProperties": false
},
"content": {
"type": "object",
"properties": {
"body": {
"type": "string",
"nullable": true
},
"type": {
"type": "string",
"enum": ["markdown", "html"],
"default": "markdown",
"description": "The type of content contained in this custom page."
}
},
"required": ["body"],
"additionalProperties": false
},
"metadata": {
"type": "object",
"properties": {
"description": {
"type": "string",
"nullable": true
},
"image": {
"type": "object",
"properties": {
"uri": {
"type": "string",
"pattern": "\\/images\\/([a-f\\d]{24})",
"nullable": true,
"description": "A URI to the `getImages` endpoint for this image. If the is a legacy image then this `uri` will be `null`. And if you wish to delete this image then you should set this to `null`."
},
"url": {
"type": "string",
"format": "uri",
"nullable": true
}
},
"required": ["uri", "url"],
"additionalProperties": false
},
"keywords": {
"type": "string",
"nullable": true,
"description": "A comma-separated list of keywords to place into your custom page metadata."
},
"title": {
"type": "string",
"nullable": true
}
},
"required": ["description", "image", "keywords", "title"],
"additionalProperties": false
},
"privacy": {
"type": "object",
"properties": {
"view": {
"type": "string",
"enum": ["public", "anyone_with_link"],
"default": "anyone_with_link",
"description": "The visibility of this custom page."
}
},
"additionalProperties": false
},
"slug": {
"type": "string",
"pattern": "([a-z0-9-_ ]|[^\\\\x00-\\\\x7F])+"
},
"title": {
"type": "string",
"nullable": true
},
"links": {
"type": "object",
"properties": {
"project": {
"type": "string",
"pattern": "\\/projects\\/(me|[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)",
"description": "A URI to the project resource."
}
},
"required": ["project"],
"additionalProperties": false
},
"renderable": {
"type": "object",
"properties": {
"status": {
"type": "boolean",
"default": true,
"description": "A flag for if the resource is renderable or not."
},
"error": {
"type": "string",
"nullable": true,
"description": "The rendering error."
},
"message": {
"type": "string",
"nullable": true,
"description": "Additional details about the rendering error."
}
},
"additionalProperties": false
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "An ISO 8601 formatted date for when the custom page was updated.",
"nullable": true
},
"uri": {
"type": "string",
"pattern": "\\/(versions|branches)\\/((v{0,1})(stable|([0-9]+)(?:\\.([0-9]+))?(?:\\.([0-9]+))?(-.*)?)(_(.*))?)\\/custom_pages\\/([a-f\\d]{24}|([a-z0-9-_ ]|[^\\\\x00-\\\\x7F])+)"
}
},
"required": [
"appearance",
"content",
"metadata",
"privacy",
"slug",
"title",
"links",
"renderable",
"updated_at",
"uri"
],
"additionalProperties": false
}
},
"required": ["data"],
"additionalProperties": false
}
}
}
}
}
}
},
"/branches/{branch}/guides": {
"post": {
"operationId": "createGuide",
"summary": "Create a guides page",
"tags": ["Guides"],
"description": "Create a page in the Guides 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": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"allow_crawlers": {
"type": "string",
"enum": ["enabled", "disabled"],
"default": "enabled",
"description": "Allow indexing by robots."
},
"appearance": {
"type": "object",
"properties": {
"icon": {
"type": "object",
"properties": {
"name": {
"type": "string",
"nullable": true
},
"type": {
"type": "string",
"enum": ["icon", "emoji"],
"nullable": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"category": {
"type": "object",
"properties": {
"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": ["uri"],
"additionalProperties": false
},
"content": {
"type": "object",
"properties": {
"body": {
"type": "string",
"nullable": true
},
"excerpt": {
"type": "string",
"nullable": true
},
"link": {
"type": "object",
"properties": {
"url": {
"type": "string",
"nullable": true
},
"new_tab": {
"type": "boolean",
"nullable": true
}
},
"additionalProperties": false,
"description": "Information about where this page should redirect to; only available when `type` is `link`."
},
"next": {
"type": "object",
"properties": {
"description": {
"type": "string",
"nullable": true
},
"pages": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"properties": {
"slug": {
"type": "string"
},
"title": {
"type": "string",
"nullable": true
},
"type": {
"type": "string",
"enum": ["basic", "endpoint"]
}
},
"required": ["slug", "title", "type"],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"title": {
"type": "string",
"nullable": true
},
"type": {
"type": "string",
"enum": ["link"]
},
"url": {
"type": "string"
}
},
"required": ["title", "type", "url"],
"additionalProperties": false
}
]
}
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"metadata": {
"type": "object",
"properties": {
"description": {
"type": "string",
"nullable": true
},
"keywords": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"image": {
"type": "object",
"properties": {
"uri": {
"type": "string",
"pattern": "\\/images\\/([a-f\\d]{24})",
"nullable": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"parent": {
"type": "object",
"properties": {
"uri": {
"type": "string",
"pattern": "\\/(versions|branches)\\/((v{0,1})(stable|([0-9]+)(?:\\.([0-9]+))?(?:\\.([0-9]+))?(-.*)?)(_(.*))?)\\/(guides|reference)\\/(([a-z0-9-_ ]|[^\\\\x00-\\\\x7F])+)",
"nullable": true
}
},
"additionalProperties": false
},
"privacy": {
"type": "object",
"properties": {
"view": {
"type": "string",
"enum": ["public", "anyone_with_link"],
"default": "anyone_with_link"
}
},
"additionalProperties": false
},
"slug": {
"allOf": [
{
"type": "string"
},
{
"type": "string",
"minLength": 1
}
],
"description": "The accessible URL slug for the page."
},
"state": {
"type": "string",
"enum": ["current", "deprecated"],
"default": "current"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"enum": ["api_config", "basic", "endpoint", "link", "webhook"],
"default": "basic"
},
"position": {
"type": "number"
}
},
"required": ["category", "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": {
"allow_crawlers": {
"type": "string",
"enum": ["enabled", "disabled"],
"default": "enabled",
"description": "Allow indexing by robots."
},
"appearance": {
"type": "object",
"properties": {
"icon": {
"type": "object",
"properties": {
"name": {
"type": "string",
"nullable": true
},
"type": {
"type": "string",
"enum": ["icon", "emoji"],
"nullable": true
}
},
"required": ["name", "type"],
"additionalProperties": false
}
},
"required": ["icon"],
"additionalProperties": false
},
"category": {
"type": "object",
"properties": {
"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": ["uri"],
"additionalProperties": false
},
"content": {
"type": "object",
"properties": {
"body": {
"type": "string",
"nullable": true
},
"excerpt": {
"type": "string",
"nullable": true
},
"link": {
"type": "object",
"properties": {
"url": {
"type": "string",
"nullable": true
},
"new_tab": {
"type": "boolean",
"nullable": true,
"description": "Should this URL be opened up in a new tab?"
}
},
"required": ["url", "new_tab"],
"additionalProperties": false,
"description": "Information about where this page should redirect to; only available when `type` is `link`."
},
"next": {
"type": "object",
"properties": {
"description": {
"type": "string",
"nullable": true
},
"pages": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"properties": {
"slug": {
"type": "string"
},
"title": {
"type": "string",
"nullable": true
},
"type": {
"type": "string",
"enum": ["basic", "endpoint"]
}
},
"required": ["slug", "title", "type"],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"title": {
"type": "string",
"nullable": true
},
"type": {
"type": "string",
"enum": ["link"]
},
"url": {
"type": "string"
}
},
"required": ["title", "type", "url"],
"additionalProperties": false
}
]
}
}
},
"required": ["description", "pages"],
"additionalProperties": false
}
},
"required": ["body", "excerpt", "link", "next"],
"additionalProperties": false
},
"metadata": {
"type": "object",
"properties": {
"description": {
"type": "string",
"nullable": true
},
"image": {
"type": "object",
"properties": {
"uri": {
"type": "string",
"pattern": "\\/images\\/([a-f\\d]{24})",
"nullable": true,
"description": "A URI to the `getImages` endpoint for this image. If the is a legacy image then this `uri` will be `null`. And if you wish to delete this image then you should set this to `null`."
},
"url": {
"type": "string",
"format": "uri",
"nullable": true
}
},
"required": ["uri", "url"],
"additionalProperties": false
},
"keywords": {
"type": "string",
"nullable": true,
"description": "A comma-separated list of keywords to place into your page metadata."
},
"title": {
"type": "string",
"nullable": true
}
},
"required": ["description", "image", "keywords", "title"],
"additionalProperties": false
},
"parent": {
"type": "object",
"properties": {
"uri": {
"type": "string",
"pattern": "\\/(versions|branches)\\/((v{0,1})(stable|([0-9]+)(?:\\.([0-9]+))?(?:\\.([0-9]+))?(-.*)?)(_(.*))?)\\/(guides|reference)\\/(([a-z0-9-_ ]|[^\\\\x00-\\\\x7F])+)",
"nullable": true,
"description": "A URI to the parent page resource including the page ID or slug."
}
},
"required": ["uri"],
"additionalProperties": false
},
"privacy": {
"type": "object",
"properties": {
"view": {
"type": "string",
"enum": ["public", "anyone_with_link"],
"default": "anyone_with_link"
}
},
"additionalProperties": false
},
"slug": {
"allOf": [
{
"type": "string"
},
{
"type": "string",
"minLength": 1
}
],
"description": "The accessible URL slug for the page."
},
"state": {
"type": "string",
"enum": ["current", "deprecated"],
"default": "current"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"enum": ["api_config", "basic", "endpoint", "link", "webhook"],
"default": "basic"
},
"href": {
"type": "object",
"properties": {
"dash": {
"type": "string",
"format": "uri",
"description": "A URL to this page in your ReadMe Dash."
},
"hub": {
"type": "string",
"format": "uri",
"description": "A URL to this page on your ReadMe hub."
}
},
"required": ["dash", "hub"],
"additionalProperties": false
},
"links": {
"type": "object",
"properties": {
"project": {
"type": "string",
"pattern": "\\/projects\\/(me|[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)",
"description": "A URI to the project resource."
}
},
"required": ["project"],
"additionalProperties": false
},
"project": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The name of the project."
},
"subdomain": {
"type": "string",
"pattern": "[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*",
"maxLength": 30,
"description": "The subdomain of the project."
},
"uri": {
"type": "string",
"pattern": "\\/projects\\/(me|[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)",
"description": "A URI to the project that this page belongs to."
}
},
"required": ["name", "subdomain", "uri"],
"additionalProperties": false
},
"renderable": {
"type": "object",
"properties": {
"status": {
"type": "boolean",
"default": true,
"description": "A flag for if the resource is renderable or not."
},
"error": {
"type": "string",
"nullable": true,
"description": "The rendering error."
},
"message": {
"type": "string",
"nullable": true,
"description": "Additional details about the rendering error."
}
},
"additionalProperties": false
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "An ISO 8601 formatted date for when the page was updated."
},
"uri": {
"type": "string",
"pattern": "\\/(versions|branches)\\/((v{0,1})(stable|([0-9]+)(?:\\.([0-9]+))?(?:\\.([0-9]+))?(-.*)?)(_(.*))?)\\/(guides|reference)\\/(([a-z0-9-_ ]|[^\\\\x00-\\\\x7F])+)",
"description": "A URI to the page resource."
}
},
"required": [
"appearance",
"category",
"content",
"metadata",
"parent",
"privacy",
"slug",
"title",
"href",
"links",
"project",
"renderable",
"updated_at",
"uri"
],
"additionalProperties": false
}
},
"required": ["data"],
"additionalProperties": false
}
}
}
}
}
}
},
"/branches/{branch}/guides/{slug}": {
"get": {
"operationId": "getGuide",
"summary": "Get a guides page",
"tags": ["Guides"],
"description": "Get a page from the Guides 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": "(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."
},
{
"schema": {
"type": "string",
"pattern": "([a-z0-9-_ ]|[^\\\\x00-\\\\x7F])+"
},
"in": "path",
"name": "slug",
"required": true,
"description": "A URL-safe representation of the resource."
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"allow_crawlers": {
"type": "string",
"enum": ["enabled", "disabled"],
"default": "enabled",
"description": "Allow indexing by robots."
},
"appearance": {
"type": "object",
"properties": {
"icon": {
"type": "object",
"properties": {
"name": {
"type": "string",
"nullable": true
},
"type": {
"type": "string",
"enum": ["icon", "emoji"],
"nullable": true
}
},
"required": ["name", "type"],
"additionalProperties": false
}
},
"required": ["icon"],
"additionalProperties": false
},
"category": {
"type": "object",
"properties": {
"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": ["uri"],
"additionalProperties": false
},
"content": {
"type": "object",
"properties": {
"body": {
"type": "string",
"nullable": true
},
"excerpt": {
"type": "string",
"nullable": true
},
"link": {
"type": "object",
"properties": {
"url": {
"type": "string",
"nullable": true
},
"new_tab": {
"type": "boolean",
"nullable": true,
"description": "Should this URL be opened up in a new tab?"
}
},
"required": ["url", "new_tab"],
"additionalProperties": false,
"description": "Information about where this page should redirect to; only available when `type` is `link`."
},
"next": {
"type": "object",
"properties": {
"description": {
"type": "string",
"nullable": true
},
"pages": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"properties": {
"slug": {
"type": "string"
},
"title": {
"type": "string",
"nullable": true
},
"type": {
"type": "string",
"enum": ["basic", "endpoint"]
}
},
"required": ["slug", "title", "type"],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"title": {
"type": "string",
"nullable": true
},
"type": {
"type": "string",
"enum": ["link"]
},
"url": {
"type": "string"
}
},
"required": ["title", "type", "url"],
"additionalProperties": false
}
]
}
}
},
"required": ["description", "pages"],
"additionalProperties": false
}
},
"required": ["body", "excerpt", "link", "next"],
"additionalProperties": false
},
"metadata": {
"type": "object",
"properties": {
"description": {
"type": "string",
"nullable": true
},
"image": {
"type": "object",
"properties": {
"uri": {
"type": "string",
"pattern": "\\/images\\/([a-f\\d]{24})",
"nullable": true,
"description": "A URI to the `getImages` endpoint for this image. If the is a legacy image then this `uri` will be `null`. And if you wish to delete this image then you should set this to `null`."
},
"url": {
"type": "string",
"format": "uri",
"nullable": true
}
},
"required": ["uri", "url"],
"additionalProperties": false
},
"keywords": {
"type": "string",
"nullable": true,
"description": "A comma-separated list of keywords to place into your page metadata."
},
"title": {
"type": "string",
"nullable": true
}
},
"required": ["description", "image", "keywords", "title"],
"additionalProperties": false
},
"parent": {
"type": "object",
"properties": {
"uri": {
"type": "string",
"pattern": "\\/(versions|branches)\\/((v{0,1})(stable|([0-9]+)(?:\\.([0-9]+))?(?:\\.([0-9]+))?(-.*)?)(_(.*))?)\\/(guides|reference)\\/(([a-z0-9-_ ]|[^\\\\x00-\\\\x7F])+)",
"nullable": true,
"description": "A URI to the parent page resource including the page ID or slug."
}
},
"required": ["uri"],
"additionalProperties": false
},
"privacy": {
"type": "object",
"properties": {
"view": {
"type": "string",
"enum": ["public", "anyone_with_link"],
"default": "anyone_with_link"
}
},
"additionalProperties": false
},
"slug": {
"allOf": [
{
"type": "string"
},
{
"type": "string",
"minLength": 1
}
],
"description": "The accessible URL slug for the page."
},
"state": {
"type": "string",
"enum": ["current", "deprecated"],
"default": "current"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"enum": ["api_config", "basic", "endpoint", "link", "webhook"],
"default": "basic"
},
"href": {
"type": "object",
"properties": {
"dash": {
"type": "string",
"format": "uri",
"description": "A URL to this page in your ReadMe Dash."
},
"hub": {
"type": "string",
"format": "uri",
"description": "A URL to this page on your ReadMe hub."
}
},
"required": ["dash", "hub"],
"additionalProperties": false
},
"links": {
"type": "object",
"properties": {
"project": {
"type": "string",
"pattern": "\\/projects\\/(me|[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)",
"description": "A URI to the project resource."
}
},
"required": ["project"],
"additionalProperties": false
},
"project": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The name of the project."
},
"subdomain": {
"type": "string",
"pattern": "[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*",
"maxLength": 30,
"description": "The subdomain of the project."
},
"uri": {
"type": "string",
"pattern": "\\/projects\\/(me|[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)",
"description": "A URI to the project that this page belongs to."
}
},
"required": ["name", "subdomain", "uri"],
"additionalProperties": false
},
"renderable": {
"type": "object",
"properties": {
"status": {
"type": "boolean",
"default": true,
"description": "A flag for if the resource is renderable or not."
},
"error": {
"type": "string",
"nullable": true,
"description": "The rendering error."
},
"message": {
"type": "string",
"nullable": true,
"description": "Additional details about the rendering error."
}
},
"additionalProperties": false
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "An ISO 8601 formatted date for when the page was updated."
},
"uri": {
"type": "string",
"pattern": "\\/(versions|branches)\\/((v{0,1})(stable|([0-9]+)(?:\\.([0-9]+))?(?:\\.([0-9]+))?(-.*)?)(_(.*))?)\\/(guides|reference)\\/(([a-z0-9-_ ]|[^\\\\x00-\\\\x7F])+)",
"description": "A URI to the page resource."
}
},
"required": [
"appearance",
"category",
"content",
"metadata",
"parent",
"privacy",
"slug",
"title",
"href",
"links",
"project",
"renderable",
"updated_at",
"uri"
],
"additionalProperties": false
}
},
"required": ["data"],
"additionalProperties": false
}
}
}
}
}
},
"delete": {
"operationId": "deleteGuide",
"summary": "Delete a guides page",
"tags": ["Guides"],
"description": "Delete a page from the Guides 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": "(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."
},
{
"schema": {
"type": "string",
"pattern": "([a-z0-9-_ ]|[^\\\\x00-\\\\x7F])+"
},
"in": "path",
"name": "slug",
"required": true,
"description": "A URL-safe representation of the resource."
}
],
"responses": {
"204": {
"description": "No Content"
}
}
},
"patch": {
"operationId": "updateGuide",
"summary": "Update a guides page",
"tags": ["Guides"],
"description": "Updates an existing page in the Guides 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": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"allow_crawlers": {
"type": "string",
"enum": ["enabled", "disabled"],
"default": "enabled",
"description": "Allow indexing by robots."
},
"appearance": {
"type": "object",
"properties": {
"icon": {
"type": "object",
"properties": {
"name": {
"type": "string",
"nullable": true
},
"type": {
"type": "string",
"enum": ["icon", "emoji"],
"nullable": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"category": {
"type": "object",
"properties": {
"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."
}
},
"additionalProperties": false
},
"content": {
"type": "object",
"properties": {
"body": {
"type": "string",
"nullable": true
},
"excerpt": {
"type": "string",
"nullable": true
},
"link": {
"type": "object",
"properties": {
"url": {
"type": "string",
"nullable": true
},
"new_tab": {
"type": "boolean",
"nullable": true
}
},
"additionalProperties": false,
"description": "Information about where this page should redirect to; only available when `type` is `link`."
},
"next": {
"type": "object",
"properties": {
"description": {
"type": "string",
"nullable": true
},
"pages": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"properties": {
"slug": {
"type": "string"
},
"title": {
"type": "string",
"nullable": true
},
"type": {
"type": "string",
"enum": ["basic", "endpoint"]
}
},
"required": ["slug", "title", "type"],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"title": {
"type": "string",
"nullable": true
},
"type": {
"type": "string",
"enum": ["link"]
},
"url": {
"type": "string"
}
},
"required": ["title", "type", "url"],
"additionalProperties": false
}
]
}
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"metadata": {
"type": "object",
"properties": {
"description": {
"type": "string",
"nullable": true
},
"keywords": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"image": {
"type": "object",
"properties": {
"uri": {
"type": "string",
"pattern": "\\/images\\/([a-f\\d]{24})",
"nullable": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"parent": {
"type": "object",
"properties": {
"uri": {
"type": "string",
"pattern": "\\/(versions|branches)\\/((v{0,1})(stable|([0-9]+)(?:\\.([0-9]+))?(?:\\.([0-9]+))?(-.*)?)(_(.*))?)\\/(guides|reference)\\/(([a-z0-9-_ ]|[^\\\\x00-\\\\x7F])+)",
"nullable": true
}
},
"additionalProperties": false
},
"privacy": {
"type": "object",
"properties": {
"view": {
"type": "string",
"enum": ["public", "anyone_with_link"],
"default": "anyone_with_link"
}
},
"additionalProperties": false
},
"slug": {
"allOf": [
{
"type": "string"
},
{
"type": "string",
"minLength": 1
}
],
"description": "The accessible URL slug for the page."
},
"state": {
"type": "string",
"enum": ["current", "deprecated"],
"default": "current"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"enum": ["api_config", "basic", "endpoint", "link", "webhook"],
"default": "basic"
},
"position": {
"type": "number"
}
},
"additionalProperties": false
}
}
}
},
"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."
},
{
"schema": {
"type": "string",
"pattern": "([a-z0-9-_ ]|[^\\\\x00-\\\\x7F])+"
},
"in": "path",
"name": "slug",
"required": true,
"description": "A URL-safe representation of the resource."
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"allow_crawlers": {
"type": "string",
"enum": ["enabled", "disabled"],
"default": "enabled",
"description": "Allow indexing by robots."
},
"appearance": {
"type": "object",
"properties": {
"icon": {
"type": "object",
"properties": {
"name": {
"type": "string",
"nullable": true
},
"type": {
"type": "string",
"enum": ["icon", "emoji"],
"nullable": true
}
},
"required": ["name", "type"],
"additionalProperties": false
}
},
"required": ["icon"],
"additionalProperties": false
},
"category": {
"type": "object",
"properties": {
"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": ["uri"],
"additionalProperties": false
},
"content": {
"type": "object",
"properties": {
"body": {
"type": "string",
"nullable": true
},
"excerpt": {
"type": "string",
"nullable": true
},
"link": {
"type": "object",
"properties": {
"url": {
"type": "string",
"nullable": true
},
"new_tab": {
"type": "boolean",
"nullable": true,
"description": "Should this URL be opened up in a new tab?"
}
},
"required": ["url", "new_tab"],
"additionalProperties": false,
"description": "Information about where this page should redirect to; only available when `type` is `link`."
},
"next": {
"type": "object",
"properties": {
"description": {
"type": "string",
"nullable": true
},
"pages": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"properties": {
"slug": {
"type": "string"
},
"title": {
"type": "string",
"nullable": true
},
"type": {
"type": "string",
"enum": ["basic", "endpoint"]
}
},
"required": ["slug", "title", "type"],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"title": {
"type": "string",
"nullable": true
},
"type": {
"type": "string",
"enum": ["link"]
},
"url": {
"type": "string"
}
},
"required": ["title", "type", "url"],
"additionalProperties": false
}
]
}
}
},
"required": ["description", "pages"],
"additionalProperties": false
}
},
"required": ["body", "excerpt", "link", "next"],
"additionalProperties": false
},
"metadata": {
"type": "object",
"properties": {
"description": {
"type": "string",
"nullable": true
},
"image": {
"type": "object",
"properties": {
"uri": {
"type": "string",
"pattern": "\\/images\\/([a-f\\d]{24})",
"nullable": true,
"description": "A URI to the `getImages` endpoint for this image. If the is a legacy image then this `uri` will be `null`. And if you wish to delete this image then you should set this to `null`."
},
"url": {
"type": "string",
"format": "uri",
"nullable": true
}
},
"required": ["uri", "url"],
"additionalProperties": false
},
"keywords": {
"type": "string",
"nullable": true,
"description": "A comma-separated list of keywords to place into your page metadata."
},
"title": {
"type": "string",
"nullable": true
}
},
"required": ["description", "image", "keywords", "title"],
"additionalProperties": false
},
"parent": {
"type": "object",
"properties": {
"uri": {
"type": "string",
"pattern": "\\/(versions|branches)\\/((v{0,1})(stable|([0-9]+)(?:\\.([0-9]+))?(?:\\.([0-9]+))?(-.*)?)(_(.*))?)\\/(guides|reference)\\/(([a-z0-9-_ ]|[^\\\\x00-\\\\x7F])+)",
"nullable": true,
"description": "A URI to the parent page resource including the page ID or slug."
}
},
"required": ["uri"],
"additionalProperties": false
},
"privacy": {
"type": "object",
"properties": {
"view": {
"type": "string",
"enum": ["public", "anyone_with_link"],
"default": "anyone_with_link"
}
},
"additionalProperties": false
},
"slug": {
"allOf": [
{
"type": "string"
},
{
"type": "string",
"minLength": 1
}
],
"description": "The accessible URL slug for the page."
},
"state": {
"type": "string",
"enum": ["current", "deprecated"],
"default": "current"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"enum": ["api_config", "basic", "endpoint", "link", "webhook"],
"default": "basic"
},
"href": {
"type": "object",
"properties": {
"dash": {
"type": "string",
"format": "uri",
"description": "A URL to this page in your ReadMe Dash."
},
"hub": {
"type": "string",
"format": "uri",
"description": "A URL to this page on your ReadMe hub."
}
},
"required": ["dash", "hub"],
"additionalProperties": false
},
"links": {
"type": "object",
"properties": {
"project": {
"type": "string",
"pattern": "\\/projects\\/(me|[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)",
"description": "A URI to the project resource."
}
},
"required": ["project"],
"additionalProperties": false
},
"project": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The name of the project."
},
"subdomain": {
"type": "string",
"pattern": "[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*",
"maxLength": 30,
"description": "The subdomain of the project."
},
"uri": {
"type": "string",
"pattern": "\\/projects\\/(me|[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)",
"description": "A URI to the project that this page belongs to."
}
},
"required": ["name", "subdomain", "uri"],
"additionalProperties": false
},
"renderable": {
"type": "object",
"properties": {
"status": {
"type": "boolean",
"default": true,
"description": "A flag for if the resource is renderable or not."
},
"error": {
"type": "string",
"nullable": true,
"description": "The rendering error."
},
"message": {
"type": "string",
"nullable": true,
"description": "Additional details about the rendering error."
}
},
"additionalProperties": false
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "An ISO 8601 formatted date for when the page was updated."
},
"uri": {
"type": "string",
"pattern": "\\/(versions|branches)\\/((v{0,1})(stable|([0-9]+)(?:\\.([0-9]+))?(?:\\.([0-9]+))?(-.*)?)(_(.*))?)\\/(guides|reference)\\/(([a-z0-9-_ ]|[^\\\\x00-\\\\x7F])+)",
"description": "A URI to the page resource."
}
},
"required": [
"appearance",
"category",
"content",
"metadata",
"parent",
"privacy",
"slug",
"title",
"href",
"links",
"project",
"renderable",
"updated_at",
"uri"
],
"additionalProperties": false
}
},
"required": ["data"],
"additionalProperties": false
}
}
}
}
}
}
},
"/images": {
"get": {
"operationId": "getImages",
"summary": "Get uploaded images",
"tags": ["Images"],
"description": "Get a collection of images that were uploaded to 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)."
}
],
"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": {
"name": {
"type": "string",
"nullable": true
},
"width": {
"type": "number",
"nullable": true,
"description": "The pixel width of the image. This is not present for SVGs."
},
"height": {
"type": "number",
"nullable": true,
"description": "The pixel height of the image. This is not present for SVGs."
},
"color": {
"type": "string",
"pattern": "^(?:#[0-9a-fA-F]{3}|#[0-9a-fA-F]{4}|#[0-9a-fA-F]{6}|#[0-9a-fA-F]{8})$",
"nullable": true,
"description": "The primary color contained within your image."
},
"links": {
"type": "object",
"properties": {
"original_url": {
"type": "string",
"format": "uri",
"nullable": true,
"description": "If your image was resized upon upload this will be a URL to the original file."
}
},
"required": ["original_url"],
"additionalProperties": false
},
"uri": {
"type": "string",
"pattern": "\\/images\\/([a-f\\d]{24})",
"nullable": true,
"description": "A URI to the `getImages` endpoint for this image. If the is a legacy image then this `uri` will be `null`. And if you wish to delete this image then you should set this to `null`."
},
"url": {
"type": "string",
"format": "uri",
"nullable": true
}
},
"required": ["name", "width", "height", "color", "links", "uri", "url"],
"additionalProperties": false
}
}
},
"required": ["total", "page", "per_page", "paging", "data"],
"additionalProperties": false
}
}
}
}
}
},
"post": {
"operationId": "uploadImage",
"summary": "Upload an image",
"tags": ["Images"],
"description": "Upload an image to your ReadMe project.",
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"properties": {
"file": {}
},
"additionalProperties": false
}
}
}
},
"parameters": [
{
"schema": {
"type": "string"
},
"in": "query",
"name": "resize_height",
"required": false,
"description": "If you wish to resize this image, supply a new height in pixels. Please note that GIFs are exempt and cannot be resized."
}
],
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"name": {
"type": "string",
"nullable": true
},
"width": {
"type": "number",
"nullable": true,
"description": "The pixel width of the image. This is not present for SVGs."
},
"height": {
"type": "number",
"nullable": true,
"description": "The pixel height of the image. This is not present for SVGs."
},
"color": {
"type": "string",
"pattern": "^(?:#[0-9a-fA-F]{3}|#[0-9a-fA-F]{4}|#[0-9a-fA-F]{6}|#[0-9a-fA-F]{8})$",
"nullable": true,
"description": "The primary color contained within your image."
},
"links": {
"type": "object",
"properties": {
"original_url": {
"type": "string",
"format": "uri",
"nullable": true,
"description": "If your image was resized upon upload this will be a URL to the original file."
}
},
"required": ["original_url"],
"additionalProperties": false
},
"uri": {
"type": "string",
"pattern": "\\/images\\/([a-f\\d]{24})",
"nullable": true,
"description": "A URI to the `getImages` endpoint for this image. If the is a legacy image then this `uri` will be `null`. And if you wish to delete this image then you should set this to `null`."
},
"url": {
"type": "string",
"format": "uri",
"nullable": true
}
},
"required": ["name", "width", "height", "color", "links", "uri", "url"],
"additionalProperties": false
}
},
"required": ["data"],
"additionalProperties": false
}
}
}
}
}
}
},
"/images/{identifier}": {
"get": {
"operationId": "getImage",
"summary": "Get an image",
"tags": ["Images"],
"description": "Get an image that was uploaded to your ReadMe project.",
"parameters": [
{
"schema": {
"type": "string",
"pattern": "[a-f\\d]{24}"
},
"in": "path",
"name": "identifier",
"required": true,
"description": "A unique identifier for the image."
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"name": {
"type": "string",
"nullable": true
},
"width": {
"type": "number",
"nullable": true,
"description": "The pixel width of the image. This is not present for SVGs."
},
"height": {
"type": "number",
"nullable": true,
"description": "The pixel height of the image. This is not present for SVGs."
},
"color": {
"type": "string",
"pattern": "^(?:#[0-9a-fA-F]{3}|#[0-9a-fA-F]{4}|#[0-9a-fA-F]{6}|#[0-9a-fA-F]{8})$",
"nullable": true,
"description": "The primary color contained within your image."
},
"links": {
"type": "object",
"properties": {
"original_url": {
"type": "string",
"format": "uri",
"nullable": true,
"description": "If your image was resized upon upload this will be a URL to the original file."
}
},
"required": ["original_url"],
"additionalProperties": false
},
"uri": {
"type": "string",
"pattern": "\\/images\\/([a-f\\d]{24})",
"nullable": true,
"description": "A URI to the `getImages` endpoint for this image. If the is a legacy image then this `uri` will be `null`. And if you wish to delete this image then you should set this to `null`."
},
"url": {
"type": "string",
"format": "uri",
"nullable": true
}
},
"required": ["name", "width", "height", "color", "links", "uri", "url"],
"additionalProperties": false
}
},
"required": ["data"],
"additionalProperties": false
}
}
}
}
}
}
},
"/outbound_ips": {
"get": {
"operationId": "getOutboundIPs",
"summary": "Get ReadMe's outbound IP addresses",
"tags": ["IP Addresses"],
"description": "Get 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.",
"security": [],
"responses": {
"200": {
"description": "List of current IP addresses used for webhook and \"Try It!\" proxy requests.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"ip_address": {
"type": "string",
"description": "The IP address."
}
},
"required": ["ip_address"],
"additionalProperties": false
}
}
},
"required": ["data"],
"additionalProperties": false,
"description": "List of current IP addresses used for webhook and \"Try It!\" proxy requests."
}
}
}
}
}
}
},
"/owlbot/ask": {
"post": {
"operationId": "askOwlbot",
"summary": "Ask Owlbot AI a question",
"tags": ["Owlbot AI"],
"description": "Ask Owlbot a question about the content of your docs.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"question": {
"type": "string",
"description": "The question being asked to Owlbot."
}
},
"required": ["question"],
"additionalProperties": false
}
}
},
"required": true
},
"parameters": [
{
"schema": {
"type": "string",
"enum": ["application/json", "text/event-stream"],
"default": "application/json"
},
"in": "header",
"name": "accept",
"required": false,
"description": "The format the response should be returned in. If `text/event-stream` then the response will be streamed as it is generated."
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"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."
}
},
"required": ["title", "url"],
"additionalProperties": false
}
}
},
"required": ["answer", "sources"],
"additionalProperties": false
}
},
"required": ["data"],
"additionalProperties": false
}
}
}
}
}
}
},
"/projects/me": {
"get": {
"operationId": "getProject",
"summary": "Get project metadata",
"tags": ["Projects"],
"description": "Returns data about your project.",
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"allow_crawlers": {
"type": "string",
"enum": ["enabled", "disabled"],
"default": "enabled",
"description": "Allow indexing by robots."
},
"api_designer": {
"type": "object",
"properties": {
"allow_editing": {
"type": "string",
"enum": ["enabled", "disabled"],
"default": "enabled",
"description": "API Designer is enabled for this project."
}
},
"additionalProperties": false
},
"appearance": {
"type": "object",
"properties": {
"brand": {
"type": "object",
"properties": {
"primary_color": {
"type": "string",
"nullable": true
},
"link_color": {
"type": "string",
"nullable": true
},
"theme": {
"type": "string",
"enum": ["system", "light", "dark"],
"default": "light"
}
},
"required": ["primary_color", "link_color"],
"additionalProperties": false
},
"changelog": {
"type": "object",
"properties": {
"layout": {
"type": "string",
"enum": ["collapsed", "continuous"],
"default": "collapsed"
},
"show_author": {
"type": "boolean",
"default": true,
"description": "Should the changelog author be shown?"
},
"show_exact_date": {
"type": "boolean",
"default": false,
"description": "Should the exact date of the changelog entry be shown, or should it be relative?"
}
},
"additionalProperties": false
},
"custom_code": {
"type": "object",
"properties": {
"css": {
"type": "string",
"nullable": true,
"description": "A chunk of custom CSS that you can use to override default CSS that we provide."
},
"js": {
"type": "string",
"nullable": true,
"description": "A chunk of custom JS that you can use to override or add new behaviors to your documentation. Please note that we do not do any validation on the code that goes in here so you have the potential to negatively impact your users with broken code."
},
"html": {
"type": "object",
"properties": {
"header": {
"type": "string",
"nullable": true,
"description": "A block of custom HTML that will be added to your `` tag. Good for things like `` tags or loading external CSS."
},
"home_footer": {
"type": "string",
"nullable": true,
"description": "A block of custom HTML that will appear in a `