api-docs.json

{
	"$schema": "https://spec.openapis.org/oas/3.1/dialect/base",
	"openapi": "3.1.0",
	"servers": [
		{
			"description": "Sh0rt.zip API",
			"url": "https://sh0rt.zip/"
		}
	],
	"info": {
		"description": "This API lets you create short URLs and get information about them.",
		"version": "1.5.0",
		"title": "Short URL API",
		"contact": {
			"url": "https://discord.gg/ZqzFUC8qe9"
		}
	},
	"paths": {
		"/{url}": {
			"get": {
				"summary": "Redirect to target",
				"description": "Searches for a short URL with the given name and redirects to the target URL. Appended path and query parameters are preserved.",
				"parameters": [
					{
						"in": "path",
						"name": "url",
						"description": "The short URL name to redirect to",
						"required": true,
						"schema": {
							"type": "string",
							"example": "bundbot"
						}
					}
				],
				"responses": {
					"302": {
						"description": "Redirect to target URL"
					},
					"404": {
						"description": "Short URL does not exist",
						"content": {
							"text/plain": {
								"schema": {
									"type": "string",
									"example": "Unknown short URL"
								}
							}
						}
					}
				}
			}
		},
		"/api/{url}": {
			"get": {
				"summary": "Short URL target",
				"description": "Returns the target URL of a shortened URL",
				"parameters": [
					{
						"in": "path",
						"name": "url",
						"description": "The short URL name",
						"required": true,
						"schema": {
							"type": "string",
							"example": "bundbot"
						}
					}
				],
				"responses": {
					"200": {
						"description": "The short URL target URL",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"required": [
										"url"
									],
									"properties": {
										"url": {
											"description": "The target URL of the short URL, can also be a data URL if the target is a file",
											"type": "string",
											"format": "url",
											"example": "https://github.com/DEVTomatoCake/Bundbot"
										}
									}
								}
							}
						}
					},
					"404": {
						"description": "The requested short URL doesn't exist"
					}
				}
			}
		},
		"/qr/{url}": {
			"get": {
				"summary": "Short URL target",
				"description": "Returns a QR code image of a shortened URL",
				"parameters": [
					{
						"in": "path",
						"name": "url",
						"description": "The short URL name",
						"required": true,
						"schema": {
							"type": "string",
							"example": "bundbot"
						}
					}
				],
				"responses": {
					"200": {
						"description": "The generated QR code",
						"content": {
							"image/gif": {
								"schema": {
									"type": "image"
								}
							}
						}
					},
					"404": {
						"description": "Unknown short URL"
					}
				}
			}
		},
		"/{eslint-plugin}/{rule}": {
			"get": {
				"summary": "ESLint plugin rule",
				"description": "Redirects to the rule documentation of the given ESLint plugin",
				"parameters": [
					{
						"in": "path",
						"name": "eslint-plugin",
						"description": "The ESLint plugin name",
						"required": true,
						"schema": {
							"type": "string",
							"enum": [
								"angular",
								"ava",
								"cypress",
								"es",
								"eslint",
								"stylistic",
								"stylisticjs",
								"stylisticts",
								"eslint-comments",
								"eslint-plugin",
								"typescript",
								"security",
								"node",
								"jest",
								"stylelint",
								"react",
								"import",
								"jasmine",
								"mocha",
								"svelte",
								"redux-saga",
								"jsx-a11y",
								"lodash",
								"testing-library",
								"html",
								"promise",
								"nuxt",
								"vue-a11y",
								"fp",
								"lit",
								"jquery",
								"sonarjs",
								"unicorn",
								"ember",
								"react-native",
								"jsonc",
								"flowtype",
								"vue",
								"wc",
								"xss",
								"yml"
							],
							"example": "eslint"
						}
					},
					{
						"in": "path",
						"name": "rule",
						"description": "The rule name",
						"required": true,
						"schema": {
							"type": "string",
							"example": "no-dupe-keys"
						}
					}
				],
				"responses": {
					"302": {
						"description": "Redirects to the documentation of the given ESLint plugin, regardless of whether the rule exists there or not."
					}
				}
			}
		},
		"/": {
			"post": {
				"summary": "Creates a short URL",
				"description": "Creates a short URL to the given target",
				"requestBody": {
					"content": {
						"application/json": {
							"schema": {
								"type": "object",
								"required": [
									"url"
								],
								"properties": {
									"url": {
										"type": "string",
										"format": "url",
										"example": "https://github.com/DEVTomatoCake/Bundbot"
									},
									"files": {
										"description": "The files to upload",
										"type": "array",
										"items": {
											"type": "object",
											"required": [
												"content"
											],
											"properties": {
												"name": {
													"description": "Name of the file (including the extension), randomly generated if not provided",
													"type": "string",
													"example": "index.js"
												},
												"content": {
													"description": "Base64 encoded file content",
													"type": "string",
													"example": "data:application/text;base64,<base64 encoded content>"
												}
											}
										}
									},
									"name": {
										"description": "Name of the short URL to use after https://sh0rt.zip/",
										"type": "string",
										"example": "bundbot",
										"default": "<4 random characters>"
									},
									"date": {
										"description": "When to delete the short URL. Must be parseable using JavaScripts `Date()` function.",
										"type": "string",
										"format": "date-time",
										"example": "2024-05-24T14:58:26.710Z",
										"default": "<five days from now>"
									}
								}
							}
						}
					}
				},
				"responses": {
					"201": {
						"description": "Short URL was created successfully at the given name.",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"required": [
										"name"
									],
									"properties": {
										"uri": {
											"description": "Full URL of the created short URL, if a URL was provided",
											"type": "string",
											"example": "https://sh0rt.zip/bundbot"
										},
										"name": {
											"description": "Name of the created short URL to use after https://sh0rt.zip/",
											"type": "string",
											"example": "bundbot"
										},
										"files": {
											"description": "The uploaded files",
											"type": "array",
											"items": {
												"description": "The file path of a file that was uploaded",
												"type": "object",
												"required": [
													"uri",
													"name",
													"expires"
												],
												"properties": {
													"uri": {
														"description": "The full URI to the file",
														"type": "string",
														"example": "file/bundbot/index.js"
													},
													"name": {
														"description": "The file name of the file",
														"type": "string",
														"example": "index.js"
													},
													"expires": {
														"description": "When the file will be deleted",
														"type": "string",
														"format": "date-time",
														"example": "2024-05-24T14:58:26.710Z"
													}
												}
											}
										}
									}
								}
							}
						}
					},
					"400": {
						"description": "Invalid input which prevents the short URL from being created, in this case a missing url.",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"required": [
										"error"
									],
									"properties": {
										"error": {
											"type": "string",
											"enum": [
												"missingurlbody"
											]
										}
									}
								}
							}
						}
					},
					"409": {
						"description": "There is already a short URL with that name.",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"required": [
										"error"
									],
									"properties": {
										"error": {
											"type": "string",
											"enum": [
												"name_alreadyexists"
											]
										}
									}
								}
							}
						}
					},
					"413": {
						"description": "The total file size or the one of a single file in the payload is too large.",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"required": [
										"error",
										"limit"
									],
									"properties": {
										"error": {
											"type": "string",
											"enum": [
												"file_too_large",
												"files_too_large"
											]
										},
										"limit": {
											"description": "The maximum file/total size in bytes, depending on the error.",
											"type": "number",
											"example": 5242880
										}
									}
								}
							}
						}
					},
					"422": {
						"description": "Invalid input which prevents the short URL from being created, such as an invalid URL or a redirect loop.",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"required": [
										"error"
									],
									"properties": {
										"error": {
											"type": "string",
											"enum": [
												"name_invalid",
												"name_blacklisted",
												"url_invalid"
											]
										}
									}
								}
							}
						}
					}
				}
			}
		}
	}
}