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 /v2/run endpoint executes a Minecraft console command on the server’s main thread and optionally returns the log output it generates. Output is captured using a log4j appender that is temporarily injected into the root logger while the command runs, making it compatible with both Fabric and Paper/Purpur platforms.

​
Request

Method: POST
Path: /v2/run
Content-Type: application/json

​
Headers

HeaderRequiredDescription
X-Auth-KeyYesAuthentication key from config.yaml → auth.key
Content-TypeRecommendedShould be application/json

​
Configuration

This endpoint can be disabled in config.yaml under v2-endpoints.run. It is enabled by default. 
v2-endpoints:
  run: true

​
Request Body

​
command
string
required
The console command to execute. Do not include a leading /. For example, use "say Hello" rather than "/say Hello". The command is dispatched on the server main thread using the console sender (Fabric: server.createCommandSourceStack(); Paper: server.getConsoleSender()).
​
silent
boolean
default:"false"
When true, the output field is omitted from the response and only {"ok": true} is returned. Use this when you do not need to inspect command output and want to minimise response size.
​
show_console
boolean
default:"false"
Controls whether command output is also printed to the server’s own console during capture. When false (the default), all existing log appenders are temporarily removed from the root logger so that captured output stays silent on the server side. When true, both the capture appender and the original appenders run concurrently, so output appears in the server console and in the API response.
Setting show_console: false (the default) temporarily removes all log4j appenders from the root logger for the duration of the command. This is intentional and safe for short-lived commands, but means that any other log messages produced concurrently on the main thread during that window will also be suppressed from the console.

​
Response

​
ok
boolean
required
true on success.
​
output
string[]
An array of trimmed log lines generated by the command. Present only when silent is false and the platform returns non-null output. Each element is a single formatted log message with leading/trailing whitespace removed. Empty lines are excluded.The field is absent entirely when silent: true. When silent is false, the field is included as long as the executor returns a non-null list (which is the normal case on both platforms).

​
Example Response — Default (silent: false)

{
  "ok": true,
  "output": [
    "[Server] Hello from the console",
    "There are 3 of a max of 20 players online"
  ]
}

​
Example Response — Silent Mode (silent: true)

{
  "ok": true
}

​
Error Responses

Statuserror fieldmessage fieldCause
400bad_requestMissing field: commandRequest body is missing or does not contain the command field
401unauthorizedInvalid X-Auth-KeyMissing or incorrect X-Auth-Key header
403forbiddenv2 run disabledEndpoint disabled via v2-endpoints.run: false
405method_not_allowedUse POSTRequest method was not POST
{
  "ok": false,
  "error": "bad_request",
  "message": "Missing field: command"
}

​
curl Examples

​
Run a command and capture output

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

​
Run silently (fire-and-forget)

curl -s -X POST http://localhost:30007/v2/run \
  -H "X-Auth-Key: your-auth-key" \
  -H "Content-Type: application/json" \
  -d '{"command": "say Server restarting in 5 minutes", "silent": true}'

​
Run with console output visible on the server

curl -s -X POST http://localhost:30007/v2/run \
  -H "X-Auth-Key: your-auth-key" \
  -H "Content-Type: application/json" \
  -d '{"command": "weather clear", "show_console": true}'
Commands are always dispatched on the server main thread and the HTTP request blocks until the command and output capture are complete. For commands that produce a lot of output or take time to complete, be aware that the HTTP request will hold open for that duration.

Build docs developers (and LLMs) love

Get started for freeTalk to us