rdme
Version:
ReadMe's official CLI and GitHub Action.
838 lines • 743 kB
JavaScript
/**
* This is a snapshot of the OpenAPI description for ReadMe APIv2.
*
* This is used both for typechecking as well as for runtime validation.
* We use ajv to validate the user data against schemas in this document.
*
* @see {@link https://docs.readme.com/main/openapi/readme-api-v2-beta.json}
*/
const document = {
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.428.0',
termsOfService: 'https://readme.com/tos',
contact: {
name: 'API Support',
url: 'https://docs.readme.com/main/docs/need-more-support',
email: 'support@readme.io',
},
},
components: {
securitySchemes: {
bearer: {
type: 'http',
scheme: 'bearer',
description: 'A bearer token that will be supplied within an `Authentication` header as `bearer <token>`.',
},
},
schemas: {},
},
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