rdme
Version:
ReadMe's official CLI and GitHub Action.
778 lines • 526 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-beta',
title: 'ReadMe API v2 🦉 (BETA)',
'x-readme-deploy': '5.344.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.\n\n>🚧 ReadMe's API v2 is currently in beta.\n >This API and its documentation are a work in progress. While we don't expect any major breaking changes, you may encounter occasional issues as we work toward a stable release. Make sure to [check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide), and [feel free to reach out](mailto:support@readme.io) if you have any questions or feedback!",
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.\n\n>🚧 ReadMe's API v2 is currently in beta.\n >This API and its documentation are a work in progress. While we don't expect any major breaking changes, you may encounter occasional issues as we work toward a stable release. Make sure to [check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide), and [feel free to reach out](mailto:support@readme.io) if you have any questions or feedback!",
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.\n\n>🚧 ReadMe's API v2 is currently in beta.\n >This API and its documentation are a work in progress. While we don't expect any major breaking changes, you may encounter occasional issues as we work toward a stable release. Make sure to [check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide), and [feel free to reach out](mailto:support@readme.io) if you have any questions or feedback!",
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.\n\n>🚧 ReadMe's API v2 is currently in beta.\n >This API and its documentation are a work in progress. While we don't expect any major breaking changes, you may encounter occasional issues as we work toward a stable release. Make sure to [check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide), and [feel free to reach out](mailto:support@readme.io) if you have any questions or feedback!",
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.\n\n>🚧 ReadMe's API v2 is currently in beta.\n >This API and its documentation are a work in progress. While we don't expect any major breaking changes, you may encounter occasional issues as we work toward a stable release. Make sure to [check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide), and [feel free to reach out](mailto:support@readme.io) if you have any questions or feedback!",
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).\n\n>🚧 ReadMe's API v2 is currently in beta.\n >This API and its documentation are a work in progress. While we don't expect any major breaking changes, you may encounter occasional issues as we work toward a stable release. Make sure to [check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide), and [feel free to reach out](mailto:support@readme.io) if you have any questions or feedback!",
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.',
},
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', '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).\n\n>🚧 ReadMe's API v2 is currently in beta.\n >This API and its documentation are a work in progress. While we don't expect any major breaking changes, you may encounter occasional issues as we work toward a stable release. Make sure to [check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide), and [feel free to reach out](mailto:support@readme.io) if you have any questions or feedback!",
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,
},
},
},
},
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).\n\n>🚧 ReadMe's API v2 is currently in beta.\n >This API and its documentation are a work in progress. While we don't expect any major breaking changes, you may encounter occasional issues as we work toward a stable release. Make sure to [check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide), and [feel free to reach out](mailto:support@readme.io) if you have any questions or feedback!",
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.',
},
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: { type: 'object', additionalProperties: {}, description: 'The API schema.' },
},
required: ['created_at', 'filename', 'source', 'type', 'updated_at', 'upload', 'uri', 'schema'],
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).\n\n>🚧 ReadMe's API v2 is currently in beta.\n >This API and its documentation are a work in progress. While we don't expect any major breaking changes, you may encounter occasional issues as we work toward a stable release. Make sure to [check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide), and [feel free to reach out](mailto:support@readme.io) if you have any questions or feedback!",
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).\n\n>🚧 ReadMe's API v2 is currently in beta.\n >This API and its documentation are a work in progress. While we don't expect any major breaking changes, you may encounter occasional issues as we work toward a stable release. Make sure to [check out our API migration guide](https://docs.readme.com/main/reference/api-migration-guide), and [feel free to reach out](mailto:support@readme.io) if you have any questions or feedback!",
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,
},
},
},
},
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'],
additio