Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/iFamishedX/HungerBridge/llms.txt

Use this file to discover all available pages before exploring further.

HungerBridge exposes a lightweight HTTP API that lets HungerLib — and any other authorized client — execute server commands, write log entries, and query live server status without relying on RCON. The server is implemented with Java’s built-in com.sun.net.httpserver.HttpServer backed by a cached thread pool, so it starts quickly and adds no heavy external dependencies to your server.
HungerBridge serves plain HTTP only — there is no built-in TLS/HTTPS support. Never expose the API port directly to the public internet. Place it behind a firewall, restrict access to trusted IPs, or route traffic through a VPN or SSH tunnel before using the API in production.

​
Base URL

Every request targets the host running your Minecraft server on the configured port. The default port is 30007. 
http://<server-host>:<port>
Example: 
http://127.0.0.1:30007
The port can be changed via the port key in config.yaml. See the configuration guide for details.

​
Authentication

Most endpoints require the X-Auth-Key request header containing the shared secret defined in config.yaml under auth.key. A missing or incorrect key returns a 401 Unauthorized response. Two endpoints — GET /v1/status and GET /v1/version — do not perform an auth check and respond regardless of whether the header is present. See the Authentication page for the full reference.

​
Response Format

Every response from HungerBridge — success or error — is a JSON object with Content-Type: application/json. All responses include an ok boolean field that indicates whether the request succeeded. 
// Successful response
{ "ok": true, ... }

// Error response
{ "ok": false, "error": "<code>", "message": "<human-readable detail>" }
See the Errors page for the complete list of error codes and status codes.

​
API Generations

HungerBridge supports three generations of endpoints. Use v2 for all new integrations; the older generations exist for backward compatibility only.

v2 — Current

Structured JSON endpoints enabled by default. All seven endpoints — ping, info, status, run, log, tps, and players — are available out of the box. Recommended for all new HungerLib integrations.

v1 — Compatibility

Structured JSON endpoints that mirror v2 capability but follow an older response shape. Disabled by default (v1-endpoints section in config.yaml). Includes run, log, status, and version.

Legacy — Plain Text

Original endpoints that accept a plain-text request body instead of JSON. Disabled by default (legacy-endpoints section in config.yaml). Includes /run and /log only.
Enable or disable any individual endpoint in config.yaml. Calling a disabled endpoint returns 403 Forbidden with "error": "forbidden".

​
v2 Endpoints

All v2 endpoints live under the /v2/ prefix and are enabled by default.
MethodPathDescription
GET/v2/pingLiveness check; returns current server time in milliseconds.
GET/v2/infoReturns HungerBridge version, platform, and Minecraft version.
GET/v2/statusConfirms the bridge is running and reachable.
POST/v2/runExecutes a server command; optionally returns console output.
POST/v2/logWrites a message to the server log at a specified level.
GET/v2/tpsReturns current TPS and 1m / 5m / 15m averages plus tick time.
GET/v2/playersReturns the online player count and a capped list of names.

​
v1 Endpoints

v1 endpoints share the same JSON request/response structure as v2 but use the /v1/ prefix and are disabled by default.
MethodPathDescription
POST/v1/runExecute a command with optional output capture.
POST/v1/logWrite a log message with an optional level.
GET/v1/statusReturns bridge, platform, and Minecraft version as flat fields. Auth is not checked.
GET/v1/versionReturns version metadata (no ok field in response). Auth is not checked.
/v1/status and /v1/version do not perform an auth check — they respond to any caller that can reach the port, as long as the endpoint is enabled. /v1/status returns bridge, platform, and minecraft as top-level fields alongside ok, whereas /v2/info nests them under a bridge object.

​
Legacy Endpoints

Legacy endpoints accept a raw plain-text request body and are disabled by default.
MethodPathDescription
POST/runExecute a command; body is the command string.
POST/logWrite a log entry; body is the message string.
Even though the legacy endpoints accept plain-text bodies, their responses are still JSON ({"ok": true} on success).

Build docs developers (and LLMs) love

Get started for freeTalk to us