Skip to main content
All POST routes require the X-API-Key header. Include your configured secret key with every write request. 
-H "X-API-Key: your_secret_key_here"
See Authentication for details on generating and configuring the key.

​
Error responses

These error responses apply to every write endpoint:
StatusMeaning
401Missing or incorrect X-API-Key header
400Bad request — missing field, invalid value, or disallowed input
500Internal server error
{ "ok": false, "error": "Unauthorized — X-API-Key required for write endpoints." }

{ "ok": false, "error": "<description of what was wrong>" }

{ "ok": false, "error": "Internal server error" }

​
POST /api/server/start

Starts the Minecraft server by issuing serv start.
The start, stop, and restart endpoints send a command to the serv CLI and return immediately. A successful response means the command was issued — not that the server has finished starting or stopping. Poll GET /api/status to confirm the resulting state.
curl -X POST http://your-server:6767/api/server/start \
  -H "X-API-Key: your_key"
Response 
{
  "ok": true,
  "message": "Server start command issued."
}
​
ok
boolean
required
true on success.
​
message
string
required
Confirmation that the command was issued.

​
POST /api/server/stop

Stops the Minecraft server by issuing serv stop.
The start, stop, and restart endpoints send a command to the serv CLI and return immediately. A successful response means the command was issued — not that the server has fully stopped. Poll GET /api/status to confirm the resulting state.
curl -X POST http://your-server:6767/api/server/stop \
  -H "X-API-Key: your_key"
Response 
{
  "ok": true,
  "message": "Server stop command issued."
}
​
ok
boolean
required
true on success.
​
message
string
required
Confirmation that the command was issued.

​
POST /api/server/restart

Restarts the Minecraft server by issuing serv restart.
The start, stop, and restart endpoints send a command to the serv CLI and return immediately. A successful response means the command was issued — not that the restart has completed. Poll GET /api/status to confirm the resulting state.
curl -X POST http://your-server:6767/api/server/restart \
  -H "X-API-Key: your_key"
Response 
{
  "ok": true,
  "message": "Server restart command issued."
}
​
ok
boolean
required
true on success.
​
message
string
required
Confirmation that the command was issued.

​
POST /api/command

Sends a command directly to the Minecraft server console via tmux.
​
command
string
required
The console command to send (e.g. "say hello", "op PlayerName", "difficulty hard").
Commands containing shell special characters — ;, &, |, `, $, (, ), {, }, [, ], <, >, \ — are rejected with a 400 error. These characters are blocked to prevent shell injection, since commands are forwarded directly to the server console over tmux.
curl -X POST http://your-server:6767/api/command \
  -H "X-API-Key: your_key" \
  -H "Content-Type: application/json" \
  -d '{"command": "say hello"}'
Response 
{
  "ok": true,
  "message": "Command sent: say hello"
}
​
ok
boolean
required
true on success.
​
message
string
required
Confirmation including the command that was sent.

​
POST /api/whitelist/add

Adds a player to the Minecraft server whitelist.
​
player
string
required
The player’s username. Must match [a-zA-Z0-9_]{1,16} — alphanumeric characters and underscores only, between 1 and 16 characters.
curl -X POST http://your-server:6767/api/whitelist/add \
  -H "X-API-Key: your_key" \
  -H "Content-Type: application/json" \
  -d '{"player": "NewPlayer"}'
Response 
{
  "ok": true,
  "message": "NewPlayer added to whitelist."
}
​
ok
boolean
required
true on success.
​
message
string
required
Confirmation including the player name that was added.

​
POST /api/whitelist/remove

Removes a player from the Minecraft server whitelist.
​
player
string
required
The player’s username. Must match [a-zA-Z0-9_]{1,16} — alphanumeric characters and underscores only, between 1 and 16 characters.
curl -X POST http://your-server:6767/api/whitelist/remove \
  -H "X-API-Key: your_key" \
  -H "Content-Type: application/json" \
  -d '{"player": "OldPlayer"}'
Response 
{
  "ok": true,
  "message": "OldPlayer removed from whitelist."
}
​
ok
boolean
required
true on success.
​
message
string
required
Confirmation including the player name that was removed.

​
POST /api/backup

Triggers a background backup by running serv backup -s. The backup runs silently in the background — the endpoint returns immediately without waiting for it to finish. 
curl -X POST http://your-server:6767/api/backup \
  -H "X-API-Key: your_key"
Response 
{
  "ok": true,
  "message": "Backup triggered. Check /api/backups shortly."
}
​
ok
boolean
required
true when the backup process was launched successfully.
​
message
string
required
Confirmation that the backup was triggered. Poll GET /api/backups to see when the new archive appears.