Add support for the new Fill API

[amirparsadd]

As riley (PaperMC leadership team) posted in the announcements channel of PaperMC's discord, there's a new api for downloading binaries and the old api will soon be discontinued. From now on all downloads related to Paper, Folia, and Velocity should be done with the new Fill api

Post contents:
@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)
nodecraft/packifier/1.0.0 (staff@nodecraft.com)

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 <t:1767168000:R>
• July 1, 2026: the v2 API will be disabled and no longer accessible in <t:1782889200:R>

[itzg]

Thanks for passing that along. Will get that prioritized.