Modern Advancements Screen

ModernAdvancements exposes a read-only JSON API that lets you build external websites or dashboards displaying your server's advancement data. This guide covers everything from first-time configuration to making the API accessible from the internet.

If you reading this, I'll assume you know what you are doing in the first place. I won't take any responsability for issues outside of my control. This mod simply does "hard" part of collecting the in-game information for you.

Requirements

• A running Fabric Minecraft server running Minecraft 26.1 or newer
• Java 25 or newer (required by Minecraft 26.1+)
• Access to your server's control panel or console

Mod Installation

1. Download the latest mod jar from the releases page. The file will be named something like ModernAdvancementsScreen-1.3.0-1.26.1.jar.
2. Place the .jar file into your server's mods/ folder.
3. Also install the matching Fabric API version into mods/ if it is not already present.
4. Start or restart your server. The mod generates its config file on first launch.

Configuration

After the first server start, a config file is created at:

config/modern-advancements/modern-advancements_config.json

Open it with any text editor. The relevant fields are:

{
  "httpApiEnabled": true,
  "httpApiHost": "0.0.0.0",
  "httpApiPort": 25580,
  "httpApiKey": ""
}

Field Descriptions

Starting the API

The API starts automatically alongside the Minecraft server as long as httpApiEnabled is true. Look for this line in your server console to confirm it started successfully:

[ModernAdvancements] Advancement API listening on 0.0.0.0:25580

If you see an error instead, check the Troubleshooting section.

Verifying It Works

If you have console or SSH access to the server machine, run:

curl http://127.0.0.1:25580/api/advancements

With an API key configured:

curl -H "Authorization: Bearer your-api-key-here" http://127.0.0.1:25580/api/advancements

You should get back a JSON response listing all advancements the server knows about. If you get connection refused, the API has not started or the port is wrong.

Making the API Public

Using a Minecraft Hosting Provider (Recommended)

Most Minecraft hosting providers run your server in an isolated environment where only ports they explicitly open are reachable from the internet. To expose the API, you need to allocate an additional port through your provider's control panel, then set that port in the mod config.

The process is the same across most providers:

1. Log into your hosting panel.
2. Find the Ports or Network section.
3. Allocate a new port. The panel will assign you a number - take note of it.
4. Open config/modern-advancements/modern-advancements_config.json and set httpApiPort to that number.
5. Set httpApiHost to 0.0.0.0.
6. Restart your Minecraft server.

The API will then be accessible at http://your-server-ip:that-port/api/advancements.

Below are the exact steps for supported providers.

Kinetic Hosting

Log into the Kinetic Panel and navigate to your server. On the left-hand side, click the Network tab and select Network & Ports. Click the Open Port button - a new port will be generated and listed. You can add a note to it (such as "ModernAdvancements API") so you remember what it is for.

Set httpApiPort in the config to that port number and restart the server.

Kinetic also has a built-in reverse proxy that lets you map a domain to your API port without exposing the raw IP. See Using a Domain Instead of an IP for details.

If you need a specific port number rather than a randomly assigned one, you will need a dedicated IP. Open a support ticket with Kinetic and they can set this up.

Shockbyte

Navigate to your server in the Shockbyte Panel, then go to the Ports tab in the left-hand menu and click Add Additional Port. Give it a name and description (these are just for your own reference), then click the button. The new port number will appear and is immediately ready to use.

Set httpApiPort in the config to that port number and restart the server.

Bearded Hosting

Bearded Host uses a custom panel with reverse proxy and protocol selector support built in. Log into the Bearded Panel and navigate to your server's Network settings to allocate an additional port.

If you cannot find the port allocation option or need help getting the API exposed via their reverse proxy, reach out to the Bearded Host team directly via their Discord - their support team typically responds within 10–30 minutes.

Other Providers

If your provider is not listed here, look for any of the following in their panel or knowledge base:

• "Additional Ports"
• "Port Allocation"
• "Network" settings
• "Port Manager"

If none of those exist, contact their support team and ask: "I need an additional TCP port opened for an HTTP API running on my Minecraft server. How do I set this up?" All major providers support this in some form - it is a common requirement for plugins like Dynmap.

Self-Hosted / VPS

If you run the server yourself on a VPS or dedicated machine, the API port just needs to be open in your firewall.

# Ubuntu / Debian (ufw)
sudo ufw allow 25580/tcp

# CentOS / RHEL (firewalld)
sudo firewall-cmd --add-port=25580/tcp --permanent && sudo firewall-cmd --reload

Also check your VPS provider's network firewall (sometimes called "Security Groups" or "Inbound Rules" in their web dashboard) and make sure port 25580 TCP is allowed there too.

Set httpApiHost to 0.0.0.0 in the config, and the API will be accessible at http://your-server-ip:25580.

Using a Domain Instead of an IP

Pointing a domain or subdomain at the API is the cleanest way to share it - it hides the raw IP address and makes the URL easier to remember and use. For example, instead of http://123.45.67.89:25580/api/players, your website can call https://api.yourserver.com/api/players.

There are two approaches depending on your setup.

Kinetic Hosting Built-in Reverse Proxy

If you use Kinetic Hosting, they have a reverse proxy tool built directly into the panel that handles this for you.

1. Make sure the API port is already allocated and working (see the Kinetic section above).
2. In the Kinetic Panel, go to Advanced -> Reverse Proxy.
3. Click Add Proxy.
4. Set the Domain field to the subdomain you want, for example api.yourserver.com.
5. Set IP to your server's IP address (found on the Overview page).
6. Set Port to the port you allocated for the API.
7. Press Create.
8. In your DNS provider (e.g. Cloudflare), add an A record pointing api.yourserver.com to your server IP.

Once DNS propagates (up to 24 hours, usually much faster), the API will be available at http://api.yourserver.com/api/advancements with no port number in the URL. You can also add an SSL certificate in the same panel screen by pasting in a cert and key - Cloudflare's free SSL is the easiest way to generate one.

Cloudflare DNS + Proxy (Any Provider)

This works with any hosting provider and also gives you Cloudflare's free DDoS protection and HTTPS. Your server IP remains hidden behind Cloudflare's network.

Prerequisites: A domain name registered anywhere, and a free Cloudflare account with your domain added to it.

Steps:

1. Log into Cloudflare and select your domain.
2. Go to the DNS tab and click Add record.
3. Set the following:
   • Type: A
   • Name: the subdomain you want, e.g. api (this creates api.yourserver.com)
   • IPv4 address: your server's IP address
   • Proxy status: set to Proxied (orange cloud icon) - this hides your real IP
4. Click Save.
5. Go to the Rules tab -> Page Rules (or Rules -> Origin Rules in newer Cloudflare) and create a rule that rewrites the port, or alternatively use a Cloudflare Worker if your API port is non-standard.

Simpler alternative without Workers: If you have a VPS (not a shared hosting panel), set httpApiHost to 127.0.0.1 and put Caddy in front of it. Point api.yourserver.com to your server IP in Cloudflare (Proxied), and use this two-line Caddyfile:

api.yourserver.com {
    reverse_proxy /api/* 127.0.0.1:25580
}

Caddy handles HTTPS automatically. Your API is then at https://api.yourserver.com with no port.

DNS CNAME Without Hiding the Port

If you do not need to hide the port and just want a cleaner URL than a raw IP address, you can point a subdomain at your server with a CNAME or A record and still include the port in the URL. For example http://api.yourserver.com:25580/api/advancements. This requires no proxy setup - just the DNS record pointing at your server IP.

Authentication

If your API is reachable from the internet, set an API key so that only your website can query it.

Generate a strong random key, you can use the command below or just go ask an AI:

# Windows (PowerShell)
[System.Convert]::ToBase64String((1..32 | ForEach-Object { Get-Random -Maximum 256 }))

Paste the result into httpApiKey in config/modern-advancements/modern-advancements_config.json and restart the server.

Using the key in requests:

Every request must include the key as a Bearer token in the Authorization header:

Authorization: Bearer your-api-key-here

Example with curl:

curl -H "Authorization: Bearer your-api-key-here" http://your-server-ip:25580/api/advancements

Example in JavaScript:

const response = await fetch('http://your-server-ip:25580/api/advancements', {
  headers: { 'Authorization': 'Bearer your-api-key-here' }
});

If no key is configured, the API is open to anyone who can reach it.

API Reference

All endpoints are read-only GET requests. All responses are application/json.

GET /api/players

Returns all players the server has seen, ordered by advancement completion.

Example response:

{
  "players": [
    {
      "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
      "name": "ThighHugger",
      "completed": 42,
      "total": 95,
      "percentage": 44.2,
      "tabs": [
        {
          "id": "minecraft:story/root",
          "title": "Minecraft",
          "completed": 10,
          "total": 16,
          "completedIds": ["minecraft:story/mine_stone", "..."]
        }
      ]
    }
  ]
}

GET /api/player?name=PlayerName

Returns detailed advancement data for a single player.

Error responses: 400 if name is missing, 404 if the player was not found.

GET /api/advancements

Returns every advancement the server knows about with its metadata.

Example response:

{
  "advancements": [
    {
      "id": "minecraft:story/mine_stone",
      "tab": "minecraft:story/root",
      "parent": "minecraft:story/root",
      "title": "Stone Age",
      "description": "Mine Stone, Granite, Diorite or Andesite",
      "type": "TASK"
    }
  ]
}

type is one of TASK, GOAL, or CHALLENGE.

GET /api/stats

Returns server-wide statistics including most and least completed advancements.

Example response:

{
  "totalPlayers": 12,
  "totalAdvancements": 95,
  "averageCompletion": 38.4,
  "mostCompleted": [
    {
      "id": "minecraft:story/mine_stone",
      "title": "Stone Age",
      "count": 11,
      "percentage": 91.7
    }
  ],
  "leastCompleted": [...]
}

GET /api/feed

Returns a chronological list of recent advancement completions.

Example response:

{
  "events": [
    {
      "playerName": "ThighHugger",
      "advancementId": "minecraft:nether/find_fortress",
      "advancementTitle": "A Terrible Fortress",
      "tabTitle": "Nether",
      "timestamp": 1714000000000
    }
  ],
  "total": 243
}

total is the full event count before any limit is applied. timestamp is Unix time in milliseconds.

Connecting a Website

Here is a minimal working example that fetches and displays the advancement list:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Server Advancements</title>
</head>
<body>
  <h1>Server Advancements</h1>
  <ul id="advancements">Loading...</ul>

  <script>
     // Replace with your server IP/domain and port. 
     // To test locally this locally set the config ip to 0.0.0.0 or 127.0.0.1 then change below to http://localhost:25580
    const API_BASE = 'http://your-server-ip:25580';
     // Paste your API key here if you set one
     // In an actual version you'd want to hide this if you don't want it public
    const API_KEY  = '';

    const headers = API_KEY ? { 'Authorization': `Bearer ${API_KEY}` } : {};

    fetch(`${API_BASE}/api/advancements`, { headers })
      .then(res => res.json())
      .then(data => {
        const list = document.getElementById('advancements');
        list.innerHTML = '';
        for (const adv of data.advancements) {
          const item = document.createElement('li');
          item.textContent = `[${adv.type}] ${adv.title} - ${adv.description}`;
          list.appendChild(item);
        }
      })
      .catch(() => {
        document.getElementById('advancements').textContent = 'Failed to load data.';
      });
  </script>
</body>
</html>

Note on CORS: The API already includes Access-Control-Allow-Origin: * on every response, so browser requests from any domain work without any extra configuration on the hosting side.

Troubleshooting

connection refused when testing the API The API either failed to start, is bound to the wrong interface, or the port is wrong. Check the server console for Advancement API listening on .... If that line is absent, re-check your config and make sure httpApiEnabled is true.

address already in use The configured port is already taken by another process. Change httpApiPort to a different value in the config and restart. If on a hosting provider, request a new port from their panel.

401 Unauthorized The API key in your request does not match the one in the config. Keys are case-sensitive.

API responds locally but is not reachable from the internet On a hosting provider, the port may not have been properly allocated in the panel. Double-check that the allocated port matches httpApiPort exactly. If using a VPS, make sure both the OS firewall and the provider's network firewall allow the port.

503 Server not ready The Minecraft server is still starting. Wait for the world to finish loading and try again.

Empty advancement list The advancement tree is populated once the server fully starts and a player loads into the world. If /api/advancements returns an empty list, try again after a player has joined.

Empty player list The API only has data for players who have joined the server at least once since the mod was installed. There is no backfill from offline player files.