Write endpoints

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:

Status	Meaning
`401`	Missing or incorrect `X-API-Key` header
`400`	Bad request — missing field, invalid value, or disallowed input
`500`	Internal 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."
}

boolean

required

true on success.

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."
}

boolean

required

true on success.

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."
}

boolean

required

true on success.

string

required

Confirmation that the command was issued.

POST /api/command

Sends a command directly to the Minecraft server console via tmux.

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"
}

boolean

required

true on success.

string

required

Confirmation including the command that was sent.

POST /api/whitelist/add

Adds a player to the Minecraft server whitelist.

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."
}

boolean

required

true on success.

string

required

Confirmation including the player name that was added.

POST /api/whitelist/remove

Removes a player from the Minecraft server whitelist.

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."
}

boolean

required

true on success.

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."
}

boolean

required

true when the backup process was launched successfully.

string

required

Confirmation that the backup was triggered. Poll GET /api/backups to see when the new archive appears.

Overview

Endpoints

Integrations

Error responses

POST /api/server/start

POST /api/server/stop

POST /api/server/restart

POST /api/command

POST /api/whitelist/add

POST /api/whitelist/remove

POST /api/backup

​Error responses

​POST /api/server/start

​POST /api/server/stop

​POST /api/server/restart

​POST /api/command

​POST /api/whitelist/add

​POST /api/whitelist/remove

​POST /api/backup

Error responses

POST /api/server/start

POST /api/server/stop

POST /api/server/restart

POST /api/command

POST /api/whitelist/add

POST /api/whitelist/remove

POST /api/backup