PaperMC のダウンロード API に破壊的変更が入るそうです

はじめに

2025/06/27 日本時間午前 5 時に Paper 公式 Discord にて PaperMC のダウンロード API 周りの変更がアナウンスされました。
アナウンス URL (Discord)

アナウンス全文(長いので折りたたみ)

@everyone

📦 Fill v3 — New Version of the Download Service

We've launched a new version of Fill, formerly known as Bibliothek — the download service powering our website, server panels, and various download scripts.

👥 Who Is Affected?

These changes primarily affect:

• Server hosts
• Tooling developers (e.g. launchers, pack installers, CI scripts)

If you're downloading from our website, you are not affected - and if you're using a server host, they will handle the migration for you.

🎁 What's New

🌏 New API Domain

The primary API domain has changed:

api.papermc.io ➜ fill.papermc.io

• The old domain (api.papermc.io) will remain available for Fill v2 until it is sunset.
• Fill v3 and the new GraphQL endpoint are **only **available via fill.papermc.io

Make sure to update your tooling and scripts accordingly.

🏷️ As seen with the release of Paper 1.21.6, we’ve started tracking select non-release versions of Minecraft. To support this, we’ve overhauled the build channel system:

• ALPHA — Early, unstable builds
• BETA — Feature-complete, may have bugs
• STABLE — Production-ready builds
• RECOMMENDED — Latest stable version recommended for general use

  ⚠️ Heads up: Some projects may not use all the available channels. The RECOMMENDED channel replaces the promoted status from v2, and is currently only used by Velocity. 

📁 Download URLs are now embedded directly in API responses and point to our new domain: fill-data.papermc.io.
You no longer need to manually construct URLs — and we advise against doing so, as the format may change.

📜 We’ve also added new version-level metadata, especially useful for server hosts:

• Support status (SUPPORTED, DEPRECATED, UNSUPPORTED)
• Support end date (ISO-8601 format: YYYY-MM-DD)
• Minimum required Java version
• Recommended JVM flags

📘 API Documentation (Swagger)
You can explore the full Fill v3 REST API using our Swagger UI:
🔗 https://fill.papermc.io/swagger-ui/index.html

🔎 GraphQL Support
Fill now includes an optional GraphQL endpoint for advanced queries. Try it out here: https://fill.papermc.io/graphiql

⚠️ Heads up: GraphQL support is experimental and subject to change at any time.

🔨 Breaking Changes

🔁  Download key changes
Some download keys have changed in Fill v3 and GraphQL responses:

• application -> server:default
• mojang-mappings -> server:mojang

🔐 Required User-Agent Header
All requests must now include a valid User-Agent header that:

• Clearly identifies your software or company
• Is not generic (e.g. curl, wget, or similar defaults)
• Includes a contact URL or email address (e.g. a homepage, bot info page, or support email)

Examples of valid headers:

mc-image-helper/1.39.11 ([https://github.com/itzg/docker-minecraft-server](https://github.com/itzg/docker-minecraft-server))
nodecraft/packifier/1.0.0 ([e-mail])

Requests without a valid User-Agent may be rejected or rate-limited.

🌅 Fill v2 Sunsetting Timeline

• December 31, 2025: the v2 API will stop receiving new builds at the end of this year, in
• July 1, 2026: the v2 API will be disabled and no longer accessible in

色々あるっぽいですね。

何がおきるの

普通に Web サイトからダウンロードする分には今までと変わりありません。
影響があるのは自動でサーバー jar をダウンロードするスクリプトやツールになります。

具体的には以下の内容がアナウンスされています。

• API のドメインが api.papermc.io から fill.papermc.io に変更
  • api.paper.io も現在の API v2 終了まで使用可
  • API v3 からは fill.paper.io でしか提供されない
• Minecraft のリリースなしバージョン(原文: non-release version)のサポート開始
  • 1.21.6 からサポート開始
  • これによりビルドチャンネルに変更あり(下記は変更後)
  • ALPHA: 早期リリース(不安定≒開発版)
  • BETA: 新機能を含むリリース(バグを含む恐れあり)
  • STABLE: 安定リリース
  • RECOMMENDED: 最新の STABLE リリース
• API 応答に新たなメタデータ付加を開始
  • サポート状態
    • SUPPORTED
    • DEPRECATED
    • UNSUPPORTED
  • サポート終了日 (ISO-8601 フォーマット)
  • 利用可能な最小の Java バージョン
  • 利用を推奨する JVM フラグのリスト
• ダウンロードの URL が fill-data.papermc.io に変更
  • fill.papermc.io のレスポンスにダウンロード URL が含まれるよう変更
  • 手動でダウンロード URL を組み立てるのは非推奨
• GraphQL エンドポイントのサポート開始
• API を利用したコンテンツダウンロード要求リクエストに User-Agent 必須化
  • wget, curl 等ツールのデフォルトはダメ
  • コンタクト URL もしくは E-mail アドレスをリクエストのヘッダーに含めなければならない
  • UA を含まないリクエストは拒否される (かレートリミットに引っかかる?)
• v2 (現在の仕様)は今年 2025 年の 12/31 まで有効
  • 2026/01/01 から v2 は無効、 v3 に一本化

個人的にはダウンロード要求に UA 必須が少し面倒かなと思っています。
(とは言っても頻繁に実行するスクリプトなどは書き足すだけなので底まででもないかもしれない......)

新しいダウンロード方法 (curl)

新しいエンドポイントにリクエストを飛ばしてみたところ、返送データ内のダウンロード URL には jar の sha256sum が含まれていました。
どうやら新しいダウンロード API はバージョンとビルド番号だけでは直接落としてこれないようになっている模様です。

以下のようなスクリプトでダウンロードできると思います。

PROJECT="paper"
VERSION="1.21.3"
E_MAIL_ADDRESS="[e-mail]" # 実際のメールアドレスに置き換えてください

# jqがインストールされているか確認
if ! command -v jq &> /dev/null
then
    echo "jq がインストールされていません。インストールしてください（例: sudo apt install jq または brew install jq）"
    exit 1
fi

DOWNLOAD_URL=$(curl -s -H "User-Agent: Easy Latest version getter (${E_MAIL_ADDRESS})" https://fill.papermc.io/v3/projects/${PROJECT}/versions/${VERSION}/builds/latest | jq -r .downloads.'["server:default"]'.url)

if [ -z "${DOWNLOAD_URL}" ]; then
    echo "ダウンロードURLの取得に失敗しました。プロジェクト名、バージョン、またはメールアドレスを確認してください。"
    exit 1
fi

echo "ダウンロードURL: ${DOWNLOAD_URL}"
curl -o paper.jar "${DOWNLOAD_URL}"

それでは。