NoxAeApi

Getting Started

Quickstart

Get NoxAeApi running on your Minecraft server and make your first request in a few minutes.

Install the plugin

NoxAeApi is a standard server plugin. Download the latest NoxAeApi.jar, place it in your server's plugins/ directory, and restart to generate the default configuration.

Installation
# 1. Download NoxAeApi.jar
# 2. Drop it into your server's plugins/ folder
server/
└── plugins/
    └── NoxAeApi.jar

# 3. Restart the server to generate the config
NoxAeApi requires Java 17+ and a compatible Minecraft server.

Configure an API key

Open plugins/NoxAeApi/config.yml. For any server exposed to the internet, set require-key to true and choose a long, random key.

config.yml
# plugins/NoxAeApi/config.yml
server:
  port: 8080
  # Require an API key for every request
  require-key: true
  key: "REPLACE_WITH_A_LONG_RANDOM_STRING"
  # IP whitelist (optional)
  ip-whitelist:
    - "203.0.113.10"

Keep your key secret

The API key grants full control of your server. Never commit it to source control or ship it in client-side code. See Authentication

Your first request

With the server running, confirm connectivity with the health check. Every endpoint is versioned under /v1.

GET /v1/ping
curl https://mc.example.com/v1/ping \
  -H "key: YOUR_API_KEY"

A healthy server responds with:

Response
"pong!"

Now try reading live server info:

GET /v1/server
curl https://mc.example.com/v1/server \
  -H "key: YOUR_API_KEY"

Frequently Asked Questions

Find solutions to common network issues, connection refused errors, firewall rules, and permission setup.

This error indicates your client could not establish a TCP handshake with the specified IP and port.

Troubleshooting steps:

  1. Server logs: Check console logs for [NoxAeApi] HTTP server listening on port 8080.
  2. Host Binding: Set server.host: "0.0.0.0" in plugins/NoxAeApi/config.yml.
  3. Java Runtime: Ensure Java 17 or Java 21+ (java -version).
Terminal
# Test connectivity locally from the server console
curl -I http://127.0.0.1:8080/v1/ping

Next steps

You're connected. From here you can explore the rest of the API.

AuthenticationExamplesAPI Reference