PaperMC download API: stahování Paper, Velocity a Folia ze skriptu

Pokud tvůj skript pořád stahuje Paper z api.papermc.io/v2/..., je rozbitý: API v2 bylo 1. července 2026 vypnuto a každý požadavek na něj dnes vrací 410 Gone. Náhradou je Fill API na https://fill.papermc.io/v3/ a změna je malá, když víš, co dělat. Zavoláš /v3/projects/paper/versions/<version>/builds?channel=STABLE, vezmeš první build v seznamu a JSON ti vrátí hotovou adresu ke stažení na fill-data.papermc.io spolu s kontrolním součtem sha256. Pošli User-Agent, který pojmenuje tvůj skript a obsahuje kontakt, ověř kontrolní součet a připni build, který jsi otestoval, místo toho, abys honil ten nejnovější. Zbytek článku jsou podrobnosti: všechny endpointy, které potřebuješ, co znamenají kanály, kompletní update skript a chyby, po kterých zůstane na serveru napůl stažený jar.

Co se stalo s api.papermc.io/v2#

Adresa ke stažení jaru Paperu měla léta jeden známý tvar a tisíce skriptů, souborů Dockerfile a návodů ho měly zadrátovaný:

https://api.papermc.io/v2/projects/paper/versions/<ver>/builds/<build>/downloads/<file>.jar

Skládala se ze tří částí - verze Minecraftu, čísla buildu a názvu souboru, který byl vždy paper-<ver>-<build>.jar - a pokud jsi build znal, mohl jsi soubor stáhnout, aniž ses API na cokoli ptal. Tohle pohodlí je pryč. PaperMC nahradil starou službu zvanou Bibliothek novou zvanou Fill a endpointy v2 zrušil. Dnes na metadata i na staré adresy ke stažení přijde tohle:

HTTP/1.1 410 Gonesunset: Wed, 1 Jul 2026 00:00:00 GMT{"ok":false,"error":"sunset","message":"This API version has been sunset and isno longer available. To continue using the service, please upgrade to a supportedAPI version."}

Žádné přesměrování ani odkladná lhůta už nezbyly. Pokud start skript serveru stahuje jar při každém startu, nebo kontejnerový image stahuje Paper při buildu, projeví se to tak, že se stahování přes wget nebo obyčejný curl "povede" a ty skončíš se 176bajtovým souborem JSON s názvem server.jar. Java ho pak odmítne s Error: Invalid or corrupt jarfile server.jar, což lidi pošle kontrolovat verze Javy místo adresy. Přepínač curl -f (selhat při chybě HTTP) z toho udělá jasnou chybu už při stahování a skript níže ho používá hned na začátku.

Všimni si také, že api.papermc.io/v3 neexistuje. Nové API běží na jiném hostiteli, fill.papermc.io, a samotné jary na třetím, fill-data.papermc.io. Pokud má tvůj firewall nebo proxy seznam povolených odchozích spojení, změnily se všechna tři jména.

Endpointy Fill v3#

API v3 je malý strom REST s tím samým tvarem jako dřív - projekty, verze, buildy - a všude JSON. Tohle jsou požadavky, které skript opravdu potřebuje:

Všechny začínají na https://fill.papermc.io. Id projektů jsou paper, folia a velocity. Ukončené proxy waterfall a travertine jsou kvůli starým buildům pořád v seznamu, ale nic nového se pro ně nevydává.

Endpoint projektu seskupuje verze podle řady, nejnovější řada první a v každé řadě nejnovější verze první:

{"project":{"id":"paper","name":"Paper"}, "versions":{"26.3":["26.3","26.3-rc-3"],             "26.2":["26.2","26.2-rc-2"],             "26.1":["26.1.2","26.1.1"],             "1.21":["1.21.11","1.21.11-rc3", "...", "1.21"]}}

Dvě věci stojí za povšimnutí. Číslování verzí Minecraftu se v roce 2026 změnilo na schéma podle roku, takže seznam jde od 26.3 zpátky k 1.21.11 a dál a cokoli, co řadí verze jako řetězce, je seřadí špatně. A release candidates a pre-release verze (26.3-rc-3, 1.21.11-pre5) jsou ve stejném seznamu jako opravdová vydání. Skript, který vezme "první verzi v seznamu", jednou sáhne po release candidate. Pokud chceš nejnovější vydání automaticky, odfiltruj id obsahující - - i když, jak je uvedeno níže, vybírat verzi Minecraftu automaticky je stejně špatný nápad.

Endpoint verze lidé přehlížejí, a přitom je pro pečlivý skript nejužitečnější:

{"version":{"id":"1.21.4",            "support":{"status":"UNSUPPORTED","end":"2025-07-17"},            "java":{"version":{"minimum":21},                    "flags":{"recommended":["-XX:+UseG1GC", "..."]}}}, "builds":[232, 231, "..."]}

support.status říká, jestli PaperMC tu verzi ještě udržuje (SUPPORTED nebo UNSUPPORTED s datem konce) a java.version.minimum říká, jakou Javu jar potřebuje - 21 pro řadu 1.21, 25 pro vydání 26.x. Skript může odmítnout nainstalovat jar, který Java na daném stroji nespustí, což je mnohem příjemnější než UnsupportedClassVersionError, který dostaneš při startu jinak. Doporučené přepínače jsou známá sada pro G1. Přepínače JVM pro Minecraft a verze Javy vysvětlují, co každý z nich dělá.

Objekt buildu obsahuje všechno, co je potřeba ke stažení a kontrole jaru:

{"id":189, "time":"2026-10-14T20:17:18Z", "channel":"STABLE", "commits":[{"sha":"a48059a2...","message":"Correctly serialise decorated pod ..."}], "downloads":{"server:default":{    "name":"paper-26.3-189.jar",    "checksums":{"sha256":"3a90c2ea79a81cd0ce641c9954c616828be6d32255385aef3b2022f80b91e8b5"},    "size":55150184,    "url":"https://fill-data.papermc.io/v1/objects/3a90c2ea.../paper-26.3-189.jar"}}}

Klíč ke stažení je server:default u všech tří projektů (v2 používalo application) a protože klíč obsahuje dvojtečku, musí se v jq dát do uvozovek: .downloads."server:default".url. Samotná adresa je adresovaná obsahem - cesta obsahuje sha256 jaru - takže se pro daný build nikdy nezmění a dá se bezpečně cachovat. Adresu si neskládej sám, přečti ji z API. To je hlavní rozdíl oproti v2, kde bylo běžné skládat adresu z verze a buildu.

Chyby přicházejí jako JSON s kódem error a správným stavem HTTP: build, který neexistuje, dá 404 s build_not_found, neznámá verze dá version_not_found. API nabízí také koncový bod GraphQL na https://fill.papermc.io/graphql pro ty, kdo ho preferují. Vše v tomto článku používá REST, protože curl a jq jsou na každém linuxovém stroji.

Kanály: ALPHA, BETA a STABLE#

V2 mělo dva kanály, default a experimental. Fill má tři a každý build jeden nese:

Nové vydání Minecraftu začíná jako řada buildů ALPHA, přejde do BETA, když je použitelné, a stane se STABLE, až je s ním PaperMC spokojený. U 26.3 bylo v době psaní 48 alfa buildů, 38 beta buildů a 15 stabilních, což dává představu, jak dlouho nestabilní období trvá. Release candidates jako 26.3-rc-3 nemusí stabilní build dostat nikdy.

Vlastní dokumentace PaperMC je v tom přímá: používej stabilní buildy a nespouštěj v produkci nestabilní buildy ani automatické updatery, protože experimentální buildy jsou náchylné k chybám a nedostávají podporu. Tohle stojí za to brát doslova. Hlášení na Discordu, které začíná "jedu na alpha buildu", dostane jedinou odpověď.

Filtr channel u seznamu buildů přijímá i několik hodnot (?channel=STABLE&channel=BETA), což se hodí pro testovací server, který má zkoušet bety dřív, než se dostanou do produkce.

Slušnost s User-Agentem a proč je to teď pravidlo#

U v2 byl User-Agent otázkou slušnosti. U Fillu je povinný. Dokumentace stahování PaperMC uvádí, že každý požadavek musí nést User-Agent, který jasně identifikuje tvůj software nebo organizaci, není obecnou výchozí hodnotou jako curl/8.5.0 nebo Wget/1.21 a obsahuje kontaktní URL nebo e-mailovou adresu. Jejich vlastní příklad je ten, který používá oblíbený obraz pro Docker:

mc-image-helper/1.39.11 (https://github.com/itzg/docker-minecraft-server)

Požadavek bez něj může dnes klidně fungovat, zvlášť u odpovědí servírovaných z cache - ale spoléhat na to znamená stavět na něčem, co provozovatelé výslovně nepovolují, a zablokovaný skript selže stejně matoucím způsobem jako vypnutí v2. Formát, který pravidlo splňuje, je název/verze (kontakt):

$ curl -A "smp-updater/1.2 (admin@example.net)" \    https://fill.papermc.io/v3/projects/paper

Zbytek slušného chování vychází ze stejné myšlenky: API je bezplatná služba provozovaná dobrovolníky a skript, který ji zahlcuje, je důvodem, proč taková pravidla vznikají.

• Nedělej polling. Stačí kontrolovat jednou denně nebo jednou před každým plánovaným restartem. Paper může za jeden večer vydat několik buildů, nepotřebuješ každý z nich během pár minut.
• Nestahuj, co už máš. Porovnej id buildu (nebo sha256) s nainstalovaným a pokud se shodují, skonči. Skript níže to dělá.
• Respektuj hlavičky cache. Odpovědi s metadaty nesou cache-control: max-age=1800. Když se ptáš častěji než každou půlhodinu, dostaneš stejnou odpověď.
• Jar stahuj jednou na stroj, ne při každém startu serveru. Síť, která provozuje osm backendů z jednoho stroje, by měla stáhnout jeden jar a zkopírovat ho.

Připnutí buildu, nebo sledování nejnovějšího#

"Aktualizovat Paper" může znamenat dvě dost odlišné věci a skript by měl automatizovat jen jednu z nich.

Buildy v rámci jedné verze Minecraftu jsou většinou opravy chyb a práce na výkonu. Přechod z buildu 187 na 189 verze 26.3 nepřevádí svět ani nemění API pluginů a skript, který sleduje nejnovější stabilní build pevně dané verze, je pro mnoho serverů rozumný. I tady občas některý build změní chování, na které se plugin spoléhal, nebo utáhne něco, co se zneužívalo - nedávný build 26.3, který zabránil pluginům resetovat recepty vaření mimo hlavní vlákno, je přesně taková změna. Pro malý server pro partu přátel je sledování stabilních buildů jednou týdně v pořádku. U serveru s desítkami pluginů připni build, který jsi otestoval, a posouvej ho vpřed vědomě.

Nová verze Minecraftu je úplně jiná událost. Svět se při prvním načtení převede a starší verze ho už nikdy neotevře, pluginy zkompilované pro starou verzi se často rozbijí a musí sedět i klienti. To se nikdy nesmí stát jen proto, že skript zaznamenal nový záznam na vrcholu seznamu verzí. Verzi Minecraftu měj jako pevné nastavení, které volí člověk, a když ji měníš, projdi si upgrady verzí Minecraftu.

Připnutí v praxi znamená zapsat si build. Buď drž přesné id buildu v konfiguračním souboru a nech skript instalovat právě to id, nebo nech skript sledovat stabilní buildy, ale každou instalaci zapisuj do logu, abys věděl, na který build se vrátit. Endpoint verze vypisuje všechna existující id buildů, takže připnuté id zůstává stažitelné. Předchozí jar měj vedle toho aktuálního. Návrat o build zpět v rámci stejné verze Minecraftu je přejmenování souboru, pokud svět nebyl převeden.

Update skript v curlu a jq#

Tento skript nainstaluje nejnovější stabilní build jedné pevně dané verze Minecraftu, nebo připnutý build, pokud ho zadáš. Před zásahem do živého jaru ověří kontrolní součet, předchozí jar si ponechá pro návrat a pokud je nainstalovaný build už aktuální, neudělá vůbec nic. Potřebuje bash, curl, jq a sha256sum.

#!/usr/bin/env bash# Usage: update-paper.sh <minecraft-version> [build]set -euo pipefailPROJECT="${PROJECT:-paper}"            # paper, folia or velocityVERSION="${1:?usage: $0 <minecraft-version> [build]}"PIN="${2:-}"                           # optional exact build idDIR="${DIR:-/home/mc/server}"JAR="$DIR/server.jar"STATE="$DIR/.${PROJECT}-build"UA="smp-updater/1.2 (admin@example.net)"API="https://fill.papermc.io/v3/projects/$PROJECT/versions/$VERSION"if [[ -n "$PIN" ]]; then  build=$(curl -fsS -A "$UA" "$API/builds/$PIN")else  build=$(curl -fsS -A "$UA" "$API/builds?channel=STABLE" | jq -e '.[0]') \    || { echo "No stable $PROJECT build for $VERSION" >&2; exit 1; }fiid=$(jq -r '.id' <<<"$build")url=$(jq -r '.downloads."server:default".url' <<<"$build")sha=$(jq -r '.downloads."server:default".checksums.sha256' <<<"$build")name=$(jq -r '.downloads."server:default".name' <<<"$build")if [[ -f "$STATE" && "$(cat "$STATE")" == "$id" ]]; then  echo "$PROJECT $VERSION build $id already installed"; exit 0fitmp=$(mktemp "$DIR/.download.XXXXXX")trap 'rm -f "$tmp"' EXITcurl -fsS -A "$UA" -o "$tmp" "$url"echo "$sha  $tmp" | sha256sum -c --quiet -[[ -f "$JAR" ]] && cp -p "$JAR" "$JAR.prev"mv "$tmp" "$JAR"echo "$id" > "$STATE"echo "$(date -Is) installed $name" >> "$DIR/update.log"

Spusť ho jako ./update-paper.sh 1.21.11, abys sledoval stabilní buildy verze 1.21.11, nebo jako ./update-paper.sh 1.21.11 132, abys nainstaloval přesně build 132. Stejný skript zvládne Velocity i Folia přes proměnnou PROJECT:

$ PROJECT=velocity DIR=/home/mc/proxy ./update-paper.sh 4.2.0$ PROJECT=folia ./update-paper.sh 26.3

Proč tam jednotlivé části jsou:

• curl -f změní chybu HTTP na nenulový návratový kód, takže 410, 404 nebo zablokovaný požadavek skript zastaví, místo aby vznikl soubor JSON pojmenovaný jako jar. -sS potlačí běžný výstup, ale skutečné chyby pořád vypíše.
• jq -e '.[0]' skončí s nenulovým kódem, když je pole prázdné - verze, která ještě nemá stabilní build - takže se skript zastaví se zprávou, místo aby požadoval adresu null.
• Stahování jde do dočasného souboru ve stejném adresáři a živý jar nahradí až po úspěšné kontrole součtu. Zápis rovnou přes server.jar znamená, že přerušené spojení zanechá useknutý jar a server, který nenastartuje. Dočasný soubor na stejném souborovém systému zajišťuje, že závěrečné mv je atomické.
• sha256sum -c čeká mezi hashem a názvem souboru dvě mezery. S jednou mezerou ohlásí chybu formátu místo neshody, což je častá chyba při kopírování.
• Stavový soubor drží id nainstalovaného buildu, takže při druhém spuštění hned po prvním se nestáhne nic.

Spouštěj ho, když je server zastavený, nebo alespoň hned potom restartuj: JVM má starý jar otevřený a Paper čte své opatchované třídy z adresáře cache, který vytvoří při prvním startu. Nový build se projeví při dalším startu, kdy Paperclip zjistí nový jar a znovu ho opatchuje, což první start o pár sekund prodlouží.

Na macOS sha256sum nemusí existovat. shasum -a 256 -c bere stejný vstup. Na Windows je ekvivalentní kontrolou Get-FileHash -Algorithm SHA256 v PowerShellu, porovnaný s polem sha256.

Specifika Folie a Velocity#

API je pro oba další projekty stejné, ale co s výsledkem uděláš, stejné není.

Velocity má vlastní čísla verzí proxy, ne verze Minecraftu. Projekt uvádí řady 4.0.0 a 3.0.0 se záznamy jako 4.2.0, 3.5.0 a 3.6.0-SNAPSHOT. Verze snapshot mají buildů mnoho, vydané verze jen velmi málo - 4.2.0 měla v době psaní jediný build, číslo 30, a některá starší vydání jako 3.5.0 neuvádějí buildy vůbec, takže před připnutím to zkontroluj. Verze proxy je nezávislá na verzi backendu a jeden build Velocity obvykle podporuje rozsah verzí klienta, takže jeho aktualizace je méně riskantní než aktualizace Paperu - ale update proxy přesto přeruší hru všem hráčům v síti najednou. Naplánuj ho, nenech ho proběhnout na časovači večer. Všimni si také, že řada 4.x vyžaduje Javu 25. Budování sítě s proxy Velocity popisuje, jak proxy a backendy zapadají dohromady.

Folia má mnohem méně verzí a buildů než Paper, a to jen u verzí, na které ji PaperMC portoval. Skutečným omezením je kompatibilita pluginů: aktualizace Folie je důležitá méně než to, jestli tvoje pluginy vůbec deklarují podporu Folie. Buildy Folie připínej a testuj, jak podrobněji vysvětluje regionální multithreading ve Folii.

Forky jako Purpur a Pufferfish nejsou součástí API PaperMC. Mají vlastní služby ke stažení s vlastními schématy adres. Forky Purpur a Pufferfish popisují, co mění a proč by ses po nich mohl poohlédnout.

Spouštění podle plánu bez rozbití čehokoli#

Samotný skript je bezpečný. Nebezpečné na automatizaci je to, kdy běží a co se stane potom. Rozumné uspořádání na samostatně spravovaném linuxovém stroji vypadá takhle:

1. Nejdřív proběhne záloha světa, pokaždé. Build, který poškodí chunk, je vzácný, ale vzácný neznamená nikdy a záloha je levná. Záloha a obnova světa Minecraftu popisuje, co zahrnout.
2. Spustí se update skript s pevnou verzí Minecraftu a stabilním kanálem.
3. Server se restartuje v klidné hodině, po upozornění v chatu.
4. Něco zkontroluje, že se server vrátil - řádek v logu Done (...)! For help, type "help" během několika minut od startu - a pokud ne, upozorní člověka.

# 04:30 daily: back up, update within 1.21.11, restart30 4 * * * /home/mc/backup.sh && /home/mc/update-paper.sh 1.21.11 && systemctl restart minecraft

Řetězení pomocí && je důležité: bez zálohy žádný update, a po neúspěšném stažení nebo kontrole součtu žádný restart. Automatizace aktualizací herních serverů probírá obecné zásady - které servery se smějí aktualizovat samy a které ne - a restartovací plány, které pomáhají pokrývají stranu restartu.

Na RE:NODE se servery Minecraft instalují s Paperem a odpovídající verzí Javy, s přijatou EULA a vygenerovaným světem, takže první stažení je hotové za tebe. Pozdější výměna jaru je souborová operace: nahraj zkontrolovaný build přes správce souborů nebo SFTP (SFTP a správce souborů má podrobnosti) a záložka Schedules umí za sebe zřetězit zálohu, upozornění v chatu a restart se zpožděním mezi nimi. Sloty pro zálohy jsou součástí každého tarifu Minecraftu, takže krok před aktualizací je jedno tlačítko.

Řešení chyb, na které lidé opravdu narážejí#

`Error: Invalid or corrupt jarfile server.jar`. Soubor není jar. Spusť head -c 200 server.jar: pokud začíná {"ok":false, adresa ke stažení byla stará z v2 nebo byl požadavek odmítnut. Přepni na endpointy v3 a přidej k curl přepínač -f, aby se to už nemohlo stát potichu.

`410 Gone` s `"error":"sunset"`. Jsi na api.papermc.io/v2. Jiná oprava než přechod na fill.papermc.io/v3 neexistuje. Zkontroluj skripty, soubory Dockerfile, role Ansible a každý start skript, který stahuje při startu - bývají zapomenuté, protože léta fungovaly.

`jq: error: Cannot index array with "downloads"`. Zavolal jsi seznam buildů, ale výsledek bereš jako jeden build. Seznam je pole, nejdřív vezmi .[0]. Endpointy jednoho buildu (builds/189, builds/latest) vracejí objekt.

Skript nainstaloval alfu. Použil builds/latest, které kanály ignoruje. Použij builds?channel=STABLE a první prvek.

Prázdné pole z `?channel=STABLE`. Verze ještě nemá stabilní buildy - to je běžné týden i déle po vydání Minecraftu a u release candidates trvalé. Počkej, nebo zůstaň na předchozí verzi. Automaticky nepřecházej na alfu.

`sha256sum: WARNING: 1 computed checksum did NOT match`. Stahování bylo přerušeno nebo cestou pozměněno. Neinstaluj ho, soubor smaž a stáhni znovu. Pokud to opakovaně selhává, porovnej velikost souboru s polem size v JSON buildu - obvyklou příčinou je proxy nebo captive portal po cestě.

`UnsupportedClassVersionError` po aktualizaci. Přešel jsi na verzi Minecraftu, jejíž jar potřebuje novější Javu - 26.x potřebuje Javu 25. Před instalací si z endpointu verze přečti java.version.minimum.

FAQ#

Funguje stará adresa api.papermc.io v2 pro staré buildy pořád?

Ne. Každá cesta v2, včetně přímého stahování jarů buildů vydaných před lety, vrací 410 Gone. Staré buildy jsou pořád dostupné přes v3: endpoint verze vypisuje všechna id buildů a JSON každého buildu má adresu ke stažení.

Je User-Agent opravdu povinný, nebo jen doporučený?

Dokumentace PaperMC říká, že každý požadavek musí obsahovat User-Agent, který pojmenuje tvůj software a uvede kontakt, a že obecné výchozí hodnoty jako curl/... nejsou přijatelné. Některé požadavky mohou být zodpovězeny i bez něj, ale na tom skript stavět nemá smysl.

Má skript vybírat nejnovější verzi Minecraftu automaticky?

Ne. Nová verze Minecraftu nevratně převede svět, rozbije pluginy a vyžaduje, aby si všichni hráči aktualizovali klienta. Automatizuj buildy v rámci verze, kterou sis zvolil, a verzi měň sám, se zálohou.

Jak získám odkaz ke stažení konkrétního staršího buildu Paperu?

Zavolej https://fill.papermc.io/v3/projects/paper/versions/<version>/builds/<build> a přečti .downloads."server:default".url. Adresu se nesnaž skládat z verze a čísla buildu - ve v3 cesta obsahuje kontrolní součet souboru, takže ji nelze uhodnout.

Sleduje Velocity čísla verzí Minecraftu?

Ne. Verze Velocity (3.5.0, 4.2.0 a tak dále) jsou vlastní vydání proxy a každá podporuje rozsah verzí klienta. Rozsah si přečti v poznámkách k vydání, nesrovnávej čísla.

Stojí kontrola kontrolního součtu za ten řádek navíc?

Ano. Je to rozdíl mezi serverem, který se odmítne aktualizovat, a serverem, který odmítne nastartovat. Useknuté stažení je mnohem častější než manipulace a obojí zachytí tentýž řádek.