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.

The legacy API is HungerBridge’s original, minimal interface. Both endpoints accept a plain-text request body — not JSON — and return a small JSON object on success. They were designed for simple shell-script integrations and intentionally offer no output capture or log-level control. Both are disabled by default and controlled through the legacy-endpoints section of config.yaml.
These endpoints are preserved for backward compatibility only. For all new integrations, use the v2 endpoints, which accept JSON, capture command output, support log levels, and are enabled by default.
Both legacy endpoints are disabled by default. You must set legacy-endpoints.run: true and/or legacy-endpoints.log: true in config.yaml before sending requests, otherwise the server returns 403 Forbidden.

​
Authentication

Both legacy endpoints require the X-Auth-Key header to match the auth.key value configured in config.yaml. A missing or incorrect key returns 401 Unauthorized. 
# config.yaml — enable legacy endpoints
legacy-endpoints:
  run: true
  log: true

​
POST /run

Dispatches a server command as a fire-and-forget operation. The request body is read as raw plain text — no JSON wrapping. The server executes the command and immediately responds with {"ok":true} without capturing or returning any output. Config toggle: legacy-endpoints.run Auth required: Yes — X-Auth-Key header

​
Request body

​
(plain text)
string
required
The raw command string to execute on the Minecraft server. Send the command directly as the request body with no JSON encoding. An empty or whitespace-only body returns a 400 error.

​
Response fields

​
ok
boolean
Always true on success. No output is captured or returned — this endpoint is strictly fire-and-forget.

​
Example

curl -s -X POST http://localhost:30007/run \
  -H "Content-Type: text/plain" \
  -H "X-Auth-Key: your-auth-key" \
  --data-raw "say Server restart in 5 minutes!"

{
  "ok": true
}

​
Example — run a command from a shell variable

CMD="time set day"

curl -s -X POST http://localhost:30007/run \
  -H "Content-Type: text/plain" \
  -H "X-Auth-Key: your-auth-key" \
  --data-raw "$CMD"

{
  "ok": true
}
POST /run does not return command output. If you need to read what a command produced, use POST /v2/run with "silent": false instead.

​
Error responses

HTTP Statuserror fieldCause
400bad_requestRequest body is empty or contains only whitespace
401unauthorizedX-Auth-Key header missing or incorrect
403forbiddenEndpoint disabled (legacy-endpoints.run: false)
405method_not_allowedRequest method is not POST

​
POST /log

Writes a message to the Minecraft server log. The request body is read as raw plain text. The message is always logged at the INFO level — there is no way to select a different severity with this endpoint. Config toggle: legacy-endpoints.log Auth required: Yes — X-Auth-Key header

​
Request body

​
(plain text)
string
required
The raw message string to write to the server log. Send the text directly as the request body with no JSON encoding. The message is always emitted at INFO level. An empty or whitespace-only body returns a 400 error.

​
Response fields

​
ok
boolean
Always true on success.

​
Example

curl -s -X POST http://localhost:30007/log \
  -H "Content-Type: text/plain" \
  -H "X-Auth-Key: your-auth-key" \
  --data-raw "Nightly backup completed successfully."

{
  "ok": true
}

​
Example — log from a script

MSG="Player count threshold reached: $(date -u +%Y-%m-%dT%H:%M:%SZ)"

curl -s -X POST http://localhost:30007/log \
  -H "Content-Type: text/plain" \
  -H "X-Auth-Key: your-auth-key" \
  --data-raw "$MSG"

{
  "ok": true
}
POST /log always logs at INFO. To log at WARN or ERROR, use POST /v2/log with the "level" field in a JSON body.

​
Error responses

HTTP Statuserror fieldCause
400bad_requestRequest body is empty or contains only whitespace
401unauthorizedX-Auth-Key header missing or incorrect
403forbiddenEndpoint disabled (legacy-endpoints.log: false)
405method_not_allowedRequest method is not POST

Build docs developers (and LLMs) love

Get started for freeTalk to us