Downloads API

PaperMC provides a downloads API to facilitate automated downloads access. Full documentation can be found on the Downloads API Docs.

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)

Some examples:

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

REST API examples

Getting the latest version

#!/usr/bin/env sh

PROJECT="paper"
USER_AGENT="cool-project/1.0.0 ([email protected])"

LATEST_VERSION=$(curl -s -H "User-Agent: $USER_AGENT" https://fill.papermc.io/v3/projects/${PROJECT} | \
    jq -r '.versions | to_entries[0] | .value[0]')

echo "Latest version is $LATEST_VERSION"

This will get the latest available Minecraft version for the given project.

Getting the latest stable build number

#!/usr/bin/env sh

PROJECT="paper"
MINECRAFT_VERSION="1.21.7"
USER_AGENT="cool-project/1.0.0 ([email protected])"

LATEST_BUILD=$(curl -s -H "User-Agent: $USER_AGENT" https://fill.papermc.io/v3/projects/${PROJECT}/versions/${MINECRAFT_VERSION}/builds | \
  jq -r 'map(select(.channel == "STABLE")) | .[0] | .id')

if [ "$LATEST_BUILD" != "null" ]; then
  echo "Latest stable build is $LATEST_BUILD"
else
  echo "No stable build for version $MINECRAFT_VERSION found :("
fi

This will get the latest stable build for the given project and Minecraft version, if it’s available.

Downloading the latest stable build

#!/usr/bin/env sh

PROJECT="paper"
MINECRAFT_VERSION="1.21.7"
USER_AGENT="cool-project/1.0.0 ([email protected])"

# First check if the version exists
VERSION_CHECK=$(curl -s -H "User-Agent: $USER_AGENT" https://fill.papermc.io/v3/projects/${PROJECT}/versions/${MINECRAFT_VERSION}/builds)

# Check if the API returned an error
if echo "$VERSION_CHECK" | jq -e '.ok == false' > /dev/null 2>&1; then
  ERROR_MSG=$(echo "$VERSION_CHECK" | jq -r '.message // "Unknown error"')
  echo "Error: $ERROR_MSG"
  exit 1
fi

# Get the download URL directly, or null if no stable build exists
PAPERMC_URL=$(curl -s -H "User-Agent: $USER_AGENT" https://fill.papermc.io/v3/projects/${PROJECT}/versions/${MINECRAFT_VERSION}/builds | \
  jq -r 'first(.[] | select(.channel == "STABLE") | .downloads."server:default".url) // "null"')

if [ "$PAPERMC_URL" != "null" ]; then
  # Download the latest Paper version
  curl -o server.jar $PAPERMC_URL
  echo "Download completed"
else
  echo "No stable build for version $MINECRAFT_VERSION found :("
fi

This is the most common use case for the API. It will download the latest stable build for the given project and Minecraft version. You should always serve & use the stable builds. Experimental builds are prone to error and do not receive support.

GraphQL API examples

Fill also supports a GraphQL API, which can be accessed at https://fill.papermc.io/graphql.

A built-in GraphQL playground is available at https://fill.papermc.io/graphiql?path=/graphql. Common API tools such as Postman will introspect the API and provide a UI for building queries.

Getting the latest version

query LatestVersion {
    project(id: "paper") {
        versions(last: 1) {
            id
        }
    }
}

Example response

{
    "data": {
        "project": {
            "versions": [
                {
                    "id": "1.21.6"
                }
            ]
        }
    }
}

Getting the latest stable build number

query LatestStableBuild {
    project(id: "paper") {
        versions(last: 1) {
            builds(filterBy: { channel: STABLE }, last: 1) {
                id
            }
        }
    }
}

Example response

{
    "data": {
        "project": {
            "versions": [
                {
                    "builds": [
                        {
                            "id": 46
                        }
                    ]
                }
            ]
        }
    }
}

Getting the latest stable build download URL

query LatestStableBuildDownloadURL {
    project(id: "paper") {
        versions(last: 1) {
            builds(filterBy: { channel: STABLE }, last: 1) {
                download(name: "server:default") {
                    url
                }
            }
        }
    }
}

Example response

{
    "data": {
        "project": {
            "versions": [
                {
                    "builds": [
                        {
                            "download": {
                                "url": "https://fill-data.papermc.io/v1/objects/bfca155b4a6b45644bfc1766f4e02a83c736e45fcc060e8788c71d6e7b3d56f6/paper-1.21.6-46.jar"
                            }
                        }
                    ]
                }
            ]
        }
    }
}