HungerBridge v1 API Reference: JSON Endpoint Overview

The v1 API is HungerBridge’s first-generation JSON interface. It accepts and returns application/json payloads and introduces per-field control over command execution — including optional output capture and log-level selection. Every v1 endpoint is gated behind a dedicated config toggle and all are disabled by default in config.yaml under the v1-endpoints section.

The v1 endpoints are available but not recommended for new integrations. Use the v2 endpoints instead — they offer richer responses, more capabilities, and are enabled by default.

All v1 endpoints are disabled by default. Set the corresponding key under v1-endpoints in config.yaml to true before sending requests, otherwise the server returns 403 Forbidden.

Authentication

All v1 endpoints that require authentication expect the X-Auth-Key header to match the auth.key value from config.yaml. A missing or incorrect key returns 401 Unauthorized. GET /v1/status and GET /v1/version do not perform an auth check — they are open to any caller once their config toggle is enabled.

# config.yaml — enable individual v1 endpoints
v1-endpoints:
  run: true
  log: true
  status: true
  version: true

POST /v1/run

Runs a Minecraft server command and optionally returns its captured output. This endpoint accepts a JSON body, gives you control over output visibility, and returns the full command output as a list of strings unless silent is set to true. Config toggle: v1-endpoints.run Auth required: Yes — X-Auth-Key header

Request fields

command

string

required

The server command to execute. Must be a non-empty string. Omitting this field returns a 400 error.

silent

boolean

When true, the output field is omitted from the response even if the command produces output. Defaults to false.

show_console

boolean

When true, the command output is also printed to the server console in addition to being captured. Defaults to false.

Response fields

boolean

Always true on success.

output

array of strings

Lines of output produced by the command. Omitted entirely when silent is true or when the command produces no output.

Example — run a command and capture output

curl -s -X POST http://localhost:30007/v1/run \
  -H "Content-Type: application/json" \
  -H "X-Auth-Key: your-auth-key" \
  -d '{"command": "list", "silent": false, "show_console": false}'

{
  "ok": true,
  "output": ["There are 3 of a max of 20 players online: Alice, Bob, Carol"]
}

Example — fire and forget (silent)

curl -s -X POST http://localhost:30007/v1/run \
  -H "Content-Type: application/json" \
  -H "X-Auth-Key: your-auth-key" \
  -d '{"command": "say Hello world!", "silent": true}'

{
  "ok": true
}

Error responses

HTTP Status	`error` field	Cause
`400`	`bad_request`	`command` field missing from request body
`401`	`unauthorized`	`X-Auth-Key` header missing or incorrect
`403`	`forbidden`	Endpoint disabled (`v1-endpoints.run: false`)
`405`	`method_not_allowed`	Request method is not `POST`

POST /v1/log

Writes a message to the server log at a specified severity level. Unlike the legacy /log endpoint, POST /v1/log accepts a JSON body and lets callers choose the log level. Config toggle: v1-endpoints.log Auth required: Yes — X-Auth-Key header

Request fields

message

string

required

The text to write to the server log. Omitting this field returns a 400 error.

level

string

The log severity level. Passed to the logger as level.toUpperCase(). Defaults to "info" when omitted. Common values: "info", "warn", "error".

Response fields

boolean

Always true on success.

Example — log at INFO level

curl -s -X POST http://localhost:30007/v1/log \
  -H "Content-Type: application/json" \
  -H "X-Auth-Key: your-auth-key" \
  -d '{"message": "Backup started by external script."}'

{
  "ok": true
}

Example — log at WARN level

curl -s -X POST http://localhost:30007/v1/log \
  -H "Content-Type: application/json" \
  -H "X-Auth-Key: your-auth-key" \
  -d '{"message": "Disk usage above 80%.", "level": "warn"}'

{
  "ok": true
}

Error responses

HTTP Status	`error` field	Cause
`400`	`bad_request`	`message` field missing from request body
`401`	`unauthorized`	`X-Auth-Key` header missing or incorrect
`403`	`forbidden`	Endpoint disabled (`v1-endpoints.log: false`)
`405`	`method_not_allowed`	Request method is not `POST`

GET /v1/status

Returns a brief health snapshot of the HungerBridge server, including the bridge version, the hosting platform (Fabric or Paper/Purpur), and the running Minecraft version. This endpoint does not require authentication. Config toggle: v1-endpoints.status Auth required: No

Response fields

boolean

Always true on success.

bridge

string

The HungerBridge plugin version, read from version.yaml at startup.

platform

string

The server platform — e.g. "fabric" or "paper". Set at runtime by the platform module.

minecraft

string

The Minecraft server version string — e.g. "1.21.1". Set at runtime by the platform module.

Example

curl -s http://localhost:30007/v1/status

{
  "ok": true,
  "bridge": "1.2.0",
  "platform": "paper",
  "minecraft": "1.21.1"
}

Error responses

HTTP Status	`error` field	Cause
`403`	`forbidden`	Endpoint disabled (`v1-endpoints.status: false`)

GET /v1/version

Returns version information for the bridge, platform, and Minecraft server. Functionally similar to GET /v1/status but omits the ok field. This endpoint also does not require authentication. Config toggle: v1-endpoints.version Auth required: No

Response fields

bridge

string

The HungerBridge plugin version, read from version.yaml at startup.

platform

string

The server platform — e.g. "fabric" or "paper".

minecraft

string

The Minecraft server version string — e.g. "1.21.1".

Example

curl -s http://localhost:30007/v1/version

{
  "bridge": "1.2.0",
  "platform": "fabric",
  "minecraft": "1.21.4"
}

Error responses

HTTP Status	`error` field	Cause
`403`	`forbidden`	Endpoint disabled (`v1-endpoints.version: false`)

Overview

v2 Endpoints

Legacy Endpoints

HungerBridge v1 API Reference: JSON Endpoint Overview

Authentication

POST /v1/run

Request fields

Response fields

Example — run a command and capture output

Example — fire and forget (silent)

Error responses

POST /v1/log

Request fields

Response fields

Example — log at INFO level

Example — log at WARN level

Error responses

GET /v1/status

Response fields

Example

Error responses

GET /v1/version

Response fields

Example

Error responses

Build docs developers (and LLMs) love

Overview

v2 Endpoints

Legacy Endpoints

Documentation Index

​Authentication

​POST /v1/run

​Request fields

​Response fields

​Example — run a command and capture output

​Example — fire and forget (silent)

​Error responses

​POST /v1/log

​Request fields

​Response fields

​Example — log at INFO level

​Example — log at WARN level

​Error responses

​GET /v1/status

​Response fields

​Example

​Error responses

​GET /v1/version

​Response fields

​Example

​Error responses

Build docs developers (and LLMs) love

Authentication

POST /v1/run

Request fields

Response fields

Example — run a command and capture output

Example — fire and forget (silent)

Error responses

POST /v1/log

Request fields

Response fields

Example — log at INFO level

Example — log at WARN level

Error responses

GET /v1/status

Response fields

Example

Error responses

GET /v1/version

Response fields

Example

Error responses