{
    "openapi": "3.1.0",
    "info": {
        "title": "MCJarHub Minecraft Server Jar API",
        "version": "1.1.0",
        "description": "Free, keyless JSON API for Minecraft server software versions: download links, checksums, Java requirements and build history. CORS enabled, responses cacheable for 5 minutes. Please send a descriptive User-Agent and cache responses; attribution appreciated.",
        "termsOfService": "https://mcjarhub.com/terms",
        "contact": {
            "name": "MCJarHub",
            "url": "https://mcjarhub.com/contact",
            "email": "contact@mcjarhub.com"
        }
    },
    "servers": [
        {
            "url": "https://mcjarhub.com"
        }
    ],
    "paths": {
        "/api/v1/types": {
            "get": {
                "summary": "List server types",
                "responses": {
                    "200": {
                        "description": "All server types",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/TypeList"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                }
            }
        },
        "/api/v1/types/{type}": {
            "get": {
                "summary": "Server type details incl. latest version",
                "parameters": [
                    {
                        "name": "type",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "vanilla",
                                "snapshots",
                                "paper",
                                "spigot",
                                "craftbukkit",
                                "purpur",
                                "folia",
                                "pufferfish",
                                "leaves",
                                "leaf",
                                "fabric",
                                "quilt",
                                "forge",
                                "neoforge",
                                "sponge",
                                "mohist",
                                "arclight",
                                "magma",
                                "bungeecord",
                                "waterfall",
                                "velocity",
                                "pocketmine",
                                "powernukkitx"
                            ]
                        },
                        "example": "paper"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Type",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/TypeEnvelope"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                }
            }
        },
        "/api/v1/types/{type}/versions": {
            "get": {
                "summary": "Versions of a type, newest first",
                "parameters": [
                    {
                        "name": "type",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "vanilla",
                                "snapshots",
                                "paper",
                                "spigot",
                                "craftbukkit",
                                "purpur",
                                "folia",
                                "pufferfish",
                                "leaves",
                                "leaf",
                                "fabric",
                                "quilt",
                                "forge",
                                "neoforge",
                                "sponge",
                                "mohist",
                                "arclight",
                                "magma",
                                "bungeecord",
                                "waterfall",
                                "velocity",
                                "pocketmine",
                                "powernukkitx"
                            ]
                        },
                        "example": "paper"
                    },
                    {
                        "name": "channel",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "release",
                                "snapshot"
                            ]
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 1000
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Versions",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/VersionList"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                }
            }
        },
        "/api/v1/types/{type}/versions/{version}": {
            "get": {
                "summary": "One version",
                "parameters": [
                    {
                        "name": "type",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "vanilla",
                                "snapshots",
                                "paper",
                                "spigot",
                                "craftbukkit",
                                "purpur",
                                "folia",
                                "pufferfish",
                                "leaves",
                                "leaf",
                                "fabric",
                                "quilt",
                                "forge",
                                "neoforge",
                                "sponge",
                                "mohist",
                                "arclight",
                                "magma",
                                "bungeecord",
                                "waterfall",
                                "velocity",
                                "pocketmine",
                                "powernukkitx"
                            ]
                        },
                        "example": "paper"
                    },
                    {
                        "name": "version",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "example": "1.21.11"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Version",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/VersionEnvelope"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                }
            }
        },
        "/api/v1/types/{type}/versions/{version}/builds": {
            "get": {
                "summary": "Build history (newest ~20 builds) with commits and checksums",
                "parameters": [
                    {
                        "name": "type",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "vanilla",
                                "snapshots",
                                "paper",
                                "spigot",
                                "craftbukkit",
                                "purpur",
                                "folia",
                                "pufferfish",
                                "leaves",
                                "leaf",
                                "fabric",
                                "quilt",
                                "forge",
                                "neoforge",
                                "sponge",
                                "mohist",
                                "arclight",
                                "magma",
                                "bungeecord",
                                "waterfall",
                                "velocity",
                                "pocketmine",
                                "powernukkitx"
                            ]
                        },
                        "example": "paper"
                    },
                    {
                        "name": "version",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "example": "1.21.11"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Builds",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/BuildList"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                }
            }
        },
        "/api/v1/types/{type}/versions/{version}/download": {
            "get": {
                "summary": "Counted 302 redirect to the file",
                "parameters": [
                    {
                        "name": "type",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "vanilla",
                                "snapshots",
                                "paper",
                                "spigot",
                                "craftbukkit",
                                "purpur",
                                "folia",
                                "pufferfish",
                                "leaves",
                                "leaf",
                                "fabric",
                                "quilt",
                                "forge",
                                "neoforge",
                                "sponge",
                                "mohist",
                                "arclight",
                                "magma",
                                "bungeecord",
                                "waterfall",
                                "velocity",
                                "pocketmine",
                                "powernukkitx"
                            ]
                        },
                        "example": "paper"
                    },
                    {
                        "name": "version",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "example": "1.21.11"
                    }
                ],
                "responses": {
                    "302": {
                        "description": "Redirect to the upstream file"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                }
            }
        },
        "/api/v1/latest/{type}": {
            "get": {
                "summary": "Newest release with a stable build (newest snapshot for \"snapshots\"); ?channel=experimental for the newest release regardless of build channel",
                "parameters": [
                    {
                        "name": "type",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "vanilla",
                                "snapshots",
                                "paper",
                                "spigot",
                                "craftbukkit",
                                "purpur",
                                "folia",
                                "pufferfish",
                                "leaves",
                                "leaf",
                                "fabric",
                                "quilt",
                                "forge",
                                "neoforge",
                                "sponge",
                                "mohist",
                                "arclight",
                                "magma",
                                "bungeecord",
                                "waterfall",
                                "velocity",
                                "pocketmine",
                                "powernukkitx"
                            ]
                        },
                        "example": "paper"
                    },
                    {
                        "name": "channel",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "experimental"
                            ]
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Version",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/VersionEnvelope"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                }
            }
        },
        "/api/v1/search": {
            "get": {
                "summary": "Search versions",
                "parameters": [
                    {
                        "name": "q",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "type",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "vanilla",
                                "snapshots",
                                "paper",
                                "spigot",
                                "craftbukkit",
                                "purpur",
                                "folia",
                                "pufferfish",
                                "leaves",
                                "leaf",
                                "fabric",
                                "quilt",
                                "forge",
                                "neoforge",
                                "sponge",
                                "mohist",
                                "arclight",
                                "magma",
                                "bungeecord",
                                "waterfall",
                                "velocity",
                                "pocketmine",
                                "powernukkitx"
                            ]
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Versions",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/VersionList"
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                }
            }
        },
        "/api/v1/lookup": {
            "get": {
                "summary": "Identify a file by checksum",
                "parameters": [
                    {
                        "name": "sha256",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "pattern": "^[0-9a-f]{64}$"
                        }
                    },
                    {
                        "name": "sha1",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "pattern": "^[0-9a-f]{40}$"
                        }
                    },
                    {
                        "name": "md5",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "pattern": "^[0-9a-f]{32}$"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Matches (possibly empty)"
                    },
                    "400": {
                        "description": "No or malformed hash"
                    }
                }
            }
        },
        "/api/v1/minecraft/{version}": {
            "get": {
                "summary": "Mojang data for a Minecraft version and which software supports it",
                "parameters": [
                    {
                        "name": "version",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "example": "26.3"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Minecraft version"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                }
            }
        },
        "/api/v1/badge/{type}": {
            "get": {
                "summary": "shields.io endpoint badge JSON (latest stable version)",
                "parameters": [
                    {
                        "name": "type",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "vanilla",
                                "snapshots",
                                "paper",
                                "spigot",
                                "craftbukkit",
                                "purpur",
                                "folia",
                                "pufferfish",
                                "leaves",
                                "leaf",
                                "fabric",
                                "quilt",
                                "forge",
                                "neoforge",
                                "sponge",
                                "mohist",
                                "arclight",
                                "magma",
                                "bungeecord",
                                "waterfall",
                                "velocity",
                                "pocketmine",
                                "powernukkitx"
                            ]
                        },
                        "example": "paper"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "shields.io endpoint schema"
                    }
                }
            }
        },
        "/api/v1/stats": {
            "get": {
                "summary": "Instance statistics",
                "responses": {
                    "200": {
                        "description": "Counters"
                    }
                }
            }
        },
        "/api/fetchJar/{category_type}/{category}/{version}": {
            "get": {
                "summary": "ServerJars-compatible: download a jar (302)",
                "tags": [
                    "ServerJars compatibility"
                ],
                "parameters": [
                    {
                        "name": "category_type",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "vanilla",
                                "servers",
                                "modded",
                                "proxies",
                                "bedrock"
                            ]
                        }
                    },
                    {
                        "name": "category",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "version",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "302": {
                        "description": "Redirect to the file"
                    }
                }
            }
        }
    },
    "components": {
        "responses": {
            "NotFound": {
                "description": "Not found",
                "content": {
                    "application/json": {
                        "schema": {
                            "type": "object",
                            "properties": {
                                "success": {
                                    "type": "boolean"
                                },
                                "error": {
                                    "type": "string"
                                }
                            }
                        }
                    }
                }
            }
        },
        "schemas": {
            "Version": {
                "type": "object",
                "properties": {
                    "type": {
                        "type": "string"
                    },
                    "version": {
                        "type": "string"
                    },
                    "build": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "build_channel": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "description": "stable, beta, alpha, recommended, latest"
                    },
                    "channel": {
                        "type": "string",
                        "enum": [
                            "release",
                            "snapshot"
                        ]
                    },
                    "java": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "description": "Minimum Java major version"
                    },
                    "file_name": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "size_bytes": {
                        "type": [
                            "integer",
                            "null"
                        ]
                    },
                    "size_human": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "sha256": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "sha1": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "md5": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "checksum_source": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "enum": [
                            "upstream",
                            "mcjarhub",
                            "mixed",
                            null
                        ]
                    },
                    "released_at": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "description": "Date of this build (UTC, Y-m-d H:i:s)"
                    },
                    "minecraft": {
                        "type": [
                            "object",
                            "null"
                        ],
                        "properties": {
                            "version": {
                                "type": "string"
                            },
                            "released_at": {
                                "type": [
                                    "string",
                                    "null"
                                ]
                            }
                        }
                    },
                    "loader_version": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "source": {
                        "type": "object",
                        "properties": {
                            "host": {
                                "type": "string"
                            },
                            "label": {
                                "type": "string"
                            },
                            "official": {
                                "type": "boolean"
                            }
                        }
                    },
                    "downloads": {
                        "type": "integer"
                    },
                    "links": {
                        "type": "object",
                        "properties": {
                            "html": {
                                "type": "string"
                            },
                            "download": {
                                "type": "string"
                            },
                            "direct": {
                                "type": "string"
                            }
                        }
                    }
                }
            },
            "VersionEnvelope": {
                "type": "object",
                "properties": {
                    "success": {
                        "type": "boolean"
                    },
                    "count": {
                        "type": "integer"
                    },
                    "data": {
                        "$ref": "#/components/schemas/Version"
                    }
                }
            },
            "VersionList": {
                "type": "object",
                "properties": {
                    "success": {
                        "type": "boolean"
                    },
                    "count": {
                        "type": "integer"
                    },
                    "data": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/Version"
                        }
                    }
                }
            },
            "Type": {
                "type": "object",
                "properties": {
                    "slug": {
                        "type": "string"
                    },
                    "name": {
                        "type": "string"
                    },
                    "tagline": {
                        "type": "string"
                    },
                    "category": {
                        "type": "string"
                    },
                    "website": {
                        "type": "string"
                    },
                    "versions": {
                        "type": "integer"
                    }
                }
            },
            "TypeEnvelope": {
                "type": "object",
                "properties": {
                    "success": {
                        "type": "boolean"
                    },
                    "count": {
                        "type": "integer"
                    },
                    "data": {
                        "$ref": "#/components/schemas/Type"
                    }
                }
            },
            "TypeList": {
                "type": "object",
                "properties": {
                    "success": {
                        "type": "boolean"
                    },
                    "count": {
                        "type": "integer"
                    },
                    "data": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/Type"
                        }
                    }
                }
            },
            "BuildList": {
                "type": "object",
                "properties": {
                    "success": {
                        "type": "boolean"
                    },
                    "count": {
                        "type": "integer"
                    },
                    "data": {
                        "type": "array",
                        "items": {
                            "type": "object"
                        }
                    }
                }
            }
        }
    }
}