Downloads Service

PaperMC provides a downloads service to facilitate automated downloads access. Full documentation can be found on the Downloads Service 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 (staff@nodecraft.com)

REST API examples

Getting the latest version

#!/usr/bin/env sh

PROJECT="paper"
USER_AGENT="cool-project/1.0.0 (contact@me.com)"

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.11"
USER_AGENT="cool-project/1.0.0 (contact@me.com)"

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.11"
USER_AGENT="cool-project/1.0.0 (contact@me.com)"

# First check if the requested version has a stable build
BUILDS_RESPONSE=$(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 "$BUILDS_RESPONSE" | jq -e '.ok == false' > /dev/null 2>&1; then
  ERROR_MSG=$(echo "$BUILDS_RESPONSE" | jq -r '.message // "Unknown error"')
  echo "Error: $ERROR_MSG"
  exit 1
fi

# Try to get a stable build URL for the requested version
PAPERMC_URL=$(echo "$BUILDS_RESPONSE" | jq -r 'first(.[] | select(.channel == "STABLE") | .downloads."server:default".url) // "null"')
FOUND_VERSION="$MINECRAFT_VERSION"

# If no stable build for requested version, find the latest version with a stable build
if [ "$PAPERMC_URL" == "null" ]; then
  echo "No stable build for version $MINECRAFT_VERSION, searching for latest version with stable build..."

  # Get all versions for the project (using the same endpoint structure as the "Getting the latest version" example)
  # The versions are organized by version group, so we need to extract all versions from all groups
  # Then sort them properly as semantic versions (newest first)
  VERSIONS=$(curl -s -H "User-Agent: $USER_AGENT" https://fill.papermc.io/v3/projects/${PROJECT} | \
    jq -r '.versions | to_entries[] | .value[]' | \
    sort -V -r)

  # Iterate through versions to find one with a stable build
  for VERSION in $VERSIONS; do
    VERSION_BUILDS=$(curl -s -H "User-Agent: $USER_AGENT" https://fill.papermc.io/v3/projects/${PROJECT}/versions/${VERSION}/builds)

    # Check if this version has a stable build
    STABLE_URL=$(echo "$VERSION_BUILDS" | jq -r 'first(.[] | select(.channel == "STABLE") | .downloads."server:default".url) // "null"')

    if [ "$STABLE_URL" != "null" ]; then
      PAPERMC_URL="$STABLE_URL"
      FOUND_VERSION="$VERSION"
      echo "Found stable build for version $VERSION"
      break
    fi
  done
fi

if [ "$PAPERMC_URL" != "null" ]; then
  # Download the latest Paper version
  curl -o server.jar $PAPERMC_URL
  echo "Download completed (version: $FOUND_VERSION)"
else
  echo "No stable builds available for any version :("
  exit 1
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. Fill’s GraphQL API uses standard pagination, which you can learn more about here.

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(key: "paper") {
        key
        versions(first: 1, orderBy: {direction: DESC}) {
            edges {
                node {
                    key
                }
            }
        }
    }
}

Example response

{
    "data": {
        "project": {
            "key": "paper",
            "versions": {
                "edges": [
                    {
                        "node": {
                            "key": "1.21.11"
                        }
                    }
                ]
            }
        }
    }
}

Getting the latest stable build number

query LatestStableBuild {
    project(key: "paper") {
        key
        versions(first: 1, orderBy: {direction: DESC}) {
            edges {
                node {
                    key
                    builds(filterBy: { channel: STABLE }, first: 1, orderBy: { direction: DESC }) {
                        edges {
                            node {
                                number
                            }
                        }
                    }
                }
            }
        }
    }
}

Example response

{
    "data": {
        "project": {
            "key": "paper",
            "versions": {
                "edges": [
                    {
                        "node": {
                            "key": "1.21.10",
                            "builds": {
                                "edges": [
                                    {
                                        "node": {
                                            "number": 48
                                        }
                                    }
                                ]
                            }
                        }
                    }
                ]
            }
        }
    }
}

Getting the latest stable build download URL

query LatestStableBuildDownloadURL {
    project(key: "paper") {
        key
        versions(first: 1, orderBy: {direction: DESC}) {
            edges {
                node {
                    key
                    builds(filterBy: { channel: STABLE }, first: 1, orderBy: { direction: DESC }) {
                        edges {
                            node {
                                number
                                download(key: "server:default") {
                                    name
                                    url
                                    checksums {
                                        sha256
                                    }
                                    size
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}

Example response

{
    "data": {
        "project": {
            "key": "paper",
            "versions": {
                "edges": [
                    {
                        "node": {
                            "key": "1.21.10",
                            "builds": {
                                "edges": [
                                    {
                                        "node": {
                                            "number": 48,
                                            "download": {
                                                "name": "paper-1.21.10-48.jar",
                                                "url": "https://fill-data.papermc.io/v1/objects/bfca155b4a6b45644bfc1766f4e02a83c736e45fcc060e8788c71d6e7b3d56f6/paper-1.21.10-48.jar",
                                                "checksums": {
                                                    "sha256": "bfca155b4a6b45644bfc1766f4e02a83c736e45fcc060e8788c71d6e7b3d56f6"
                                                },
                                                "size": 54185955
                                            }
                                        }
                                    }
                                ]
                            }
                        }
                    }
                ]
            }
        }
    }
}