Bedrock Server Manager - HTTP API Documentation

POST /api/login - API Login

Authenticates using username and password provided in the JSON body and returns a JWT access token upon success. Credentials must match the BEDROCK_SERVER_MANAGER_USERNAME and BEDROCK_SERVER_MANAGER_PASSWORD environment variables (password must be the hashed value).

This endpoint is exempt from CSRF protection.

Authentication:

None required for this endpoint.

Request Body (application/json):

{
    "username": "your_web_ui_username",
    "password": "your_web_ui_password"
}

• username(string)(Required): The username configured via the BEDROCK_SERVER_MANAGER_USERNAME environment variable.
• password(string)(Required): The plain-text password corresponding to the hashed password configured via the BEDROCK_SERVER_MANAGER_PASSWORD environment variable.

Success Response (`200 OK`):

Returns a JSON object containing the JWT access token.

{
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Error Responses:

• 400 Bad Request:
  • If the request body is not valid JSON:

    {"message": "Request must be JSON"}

  • If the username or password field is missing:

    {"message": "Missing username or password parameter"}

• 401 Unauthorized:
  • If the provided username or password does not match:

    {"message": "Bad username or password"}

• 500 Internal Server Error:
  • If the server is missing necessary configuration (env vars not set):

    {"message": "Server configuration error prevents login."}

curl Example (Bash):

curl -X POST -H "Content-Type: application/json" \
     -d '{"username": "your_username", "password": "your_password"}' \
     http://<your-manager-host>:<port>/api/login

PowerShell Example:

$body = @{ username = 'your_username'; password = 'your_password' } | ConvertTo-Json
Invoke-RestMethod -Method Post -Uri "http://<your-manager-host>:<port>/api/login" -Body $body -ContentType 'application/json'

GET /api/server/{server_name}/world_name - Get World Name

Gets the configured world name (level-name property) from the server.properties file for the specified server.

This endpoint is exempt from CSRF protection but requires authentication.

Authentication:

Required (JWT via Authorization: Bearer <token> header, or active Web UI session).

Path Parameters:

• server_name(string)(Required): The unique name of the server instance.

Request Body:

None.

Success Response (`200 OK`):

Returns the world name if found successfully.

{
    "status": "success",
    "world_name": "Bedrock level"
}

• status: Always "success".
• world_name: The value of the level-name property from the server's server.properties file.

Error Responses:

• 400 Bad Request:
  • If the server_name is invalid (e.g., empty). Message comes from the exception (e.g.,

    {"status": "error", "message": "Server name cannot be empty."}

    ).
• 401 Unauthorized:
  • Authentication missing or invalid (e.g.,

    {"error": "Unauthorized", "message": "Authentication required."}

    ).
• 500 Internal Server Error:
  • If server.properties not found/readable or level-name missing:

    {
        "status": "error",
        "message": "Failed to get world name: File not found: /path/to/servers/MyServer/server.properties"
    }

    or

    {
        "status": "error",
        "message": "Failed to get world name: Property 'level-name' not found in /path/to/servers/MyServer/server.properties"
    }

  • If base directory configuration is invalid/inaccessible:

    {
        "status": "error",
        "message": "Failed to get world name: Base directory '/invalid/path' not found or accessible."
    }

  • If an unexpected error occurs:

    {"status": "error", "message": "Unexpected error getting world name."}

curl Example (Bash):

curl -X GET -H "Authorization: Bearer YOUR_JWT_TOKEN" \
     http://<your-manager-host>:<port>/api/server/<server_name>/world_name

PowerShell Example:

$headers = @{ Authorization = 'Bearer YOUR_JWT_TOKEN' }
Invoke-RestMethod -Method Get -Uri "http://<your-manager-host>:<port>/api/server/<server_name>/world_name" -Headers $headers

GET /api/server/{server_name}/running_status - Get Running Status

Checks if the Bedrock server process for the specified server instance is currently running.

This endpoint is exempt from CSRF protection but requires authentication.

Authentication:

Required (JWT via Authorization: Bearer <token> header, or active Web UI session).

Path Parameters:

• server_name(string)(Required): The unique name of the server instance.

Request Body:

None.

Success Response (`200 OK`):

Returns the running status of the server.

{
    "status": "success",
    "is_running": true
}

or

{
    "status": "success",
    "is_running": false
}

• status: Always "success".
• is_running: Boolean indicating whether the server process was found.

Error Responses:

• 400 Bad Request:
  • If the server_name is invalid (e.g., empty):

    {"status": "error", "message": "Server name cannot be empty."}

    .
• 401 Unauthorized:
  • Authentication missing or invalid.
• 500 Internal Server Error:
  • If configuration issue prevents check (e.g., invalid BASE_DIR):

    {"status": "error", "message": "Configuration error: Base directory '/invalid/path' not found or accessible."}

    .
  • If an unexpected error occurs during the process check (e.g., permissions, psutil errors):

    {"status": "error", "message": "Unexpected error checking running status."}

    .

curl Example (Bash):

curl -X GET -H "Authorization: Bearer YOUR_JWT_TOKEN" \
     http://<your-manager-host>:<port>/api/server/<server_name>/running_status

PowerShell Example:

$headers = @{ Authorization = 'Bearer YOUR_JWT_TOKEN' }
Invoke-RestMethod -Method Get -Uri "http://<your-manager-host>:<port>/api/server/<server_name>/running_status" -Headers $headers

GET /api/server/{server_name}/config_status - Get Config Status

Gets the status string stored within the server's specific configuration file (config/{server_name}.json). Reflects the server's intended or last known state (e.g., "Installed", "Stopped").

This endpoint is exempt from CSRF protection but requires authentication.

Authentication:

Required (JWT or active Web UI session).

Path Parameters:

• server_name(string)(Required): The unique name of the server instance.

Request Body:

None.

Success Response (`200 OK`):

Returns the status string from the configuration file.

{
    "status": "success",
    "config_status": "Installed"
}

• status: Always "success".
• config_status: The string value from the server's JSON configuration file (might be "UNKNOWN" if missing).

Error Responses:

• 400 Bad Request:
  • If server_name is invalid:

    {"status": "error", "message": "Server name cannot be empty."}

    .
• 401 Unauthorized:
  • Authentication missing or invalid.
• 500 Internal Server Error:
  • If error accessing/reading config file (permissions, not found, invalid JSON):

    {"status": "error", "message": "Error retrieving config status: File not found: /path/to/config/MyServer.json"}

    or

    {"status": "error", "message": "Error retrieving config status: Permission denied accessing /path/to/config/MyServer.json"}

    .
  • If unexpected error occurs:

    {"status": "error", "message": "Unexpected error getting config status."}

    .

curl Example (Bash):

curl -X GET -H "Authorization: Bearer YOUR_JWT_TOKEN" \
     http://<your-manager-host>:<port>/api/server/<server_name>/config_status

PowerShell Example:

$headers = @{ Authorization = 'Bearer YOUR_JWT_TOKEN' }
Invoke-RestMethod -Method Get -Uri "http://<your-manager-host>:<port>/api/server/<server_name>/config_status" -Headers $headers

GET /api/server/{server_name}/version - Get Installed Version

Gets the installed Bedrock server version string stored within the server's specific configuration file (config/{server_name}.json).

This endpoint is exempt from CSRF protection but requires authentication.

Authentication:

Required (JWT or active Web UI session).

Path Parameters:

• server_name(string)(Required): The unique name of the server instance.

Request Body:

None.

Success Response (`200 OK`):

Returns the installed version string from the configuration file.

{
    "status": "success",
    "installed_version": "1.20.81.01"
}

• status: Always "success".
• installed_version: The string value from the server's JSON configuration file (might be "UNKNOWN").

Error Responses:

• 400 Bad Request:
  • If server_name is invalid:

    {"status": "error", "message": "Server name cannot be empty."}

    .
• 401 Unauthorized:
  • Authentication missing or invalid.
• 500 Internal Server Error:
  • If error accessing/reading config file:

    {"status": "error", "message": "Error retrieving installed version: File not found: /path/to/config/MyServer.json"}

    or

    {"status": "error", "message": "Error retrieving installed version: Permission denied accessing /path/to/config/MyServer.json"}

    .
  • If unexpected error occurs:

    {"status": "error", "message": "Unexpected error getting installed version."}

    .

curl Example (Bash):

curl -X GET -H "Authorization: Bearer YOUR_JWT_TOKEN" \
     http://<your-manager-host>:<port>/api/server/<server_name>/version

PowerShell Example:

$headers = @{ Authorization = 'Bearer YOUR_JWT_TOKEN' }
Invoke-RestMethod -Method Get -Uri "http://<your-manager-host>:<port>/api/server/<server_name>/version" -Headers $headers

GET /api/server/{server_name}/validate - Validate Server Existence

Validates if the server directory and the main executable (bedrock_server) exist for the specified server name within the configured BASE_DIR.

This endpoint is exempt from CSRF protection but requires authentication.

Authentication:

Required (JWT or active Web UI session).

Path Parameters:

• server_name(string)(Required): The unique name of the server instance to validate.

Request Body:

None.

Success Response (`200 OK`):

Returned when both the server directory and the executable are found.

{
    "status": "success",
    "message": "Server '<server_name>' exists and is valid."
}

Error Responses:

• 400 Bad Request:
  • If server_name is invalid:

    {"status": "error", "message": "Server name cannot be empty."}

    .
• 401 Unauthorized:
  • Authentication missing or invalid.
• 404 Not Found:
  • Returned specifically when validation *fails* (directory or executable not found):

    {"status": "error", "message": "Server directory '/path/to/servers/MyServer' not found."}

    or

    {"status": "error", "message": "Server executable '/path/to/servers/MyServer/bedrock_server' not found."}

    .
• 500 Internal Server Error:
  • If configuration issue prevents validation (e.g., invalid BASE_DIR):

    {"status": "error", "message": "Configuration error: Base directory '/invalid/path' not found or accessible."}

    .
  • If unexpected error occurs:

    {"status": "error", "message": "Unexpected error validating server."}

    .

curl Example (Bash):

curl -X GET -H "Authorization: Bearer YOUR_JWT_TOKEN" \
     http://<your-manager-host>:<port>/api/server/<server_name>/validate

PowerShell Example:

$headers = @{ Authorization = 'Bearer YOUR_JWT_TOKEN' }
Invoke-RestMethod -Method Get -Uri "http://<your-manager-host>:<port>/api/server/<server_name>/validate" -Headers $headers

GET /api/server/{server_name}/status_info - Get Server Status Info

Retrieves runtime status information for a specific server process, including running state and basic resource usage (PID, CPU, Memory, Uptime) if the process is active and accessible.

Note on CPU Usage: CPU percentage is calculated based on the change in CPU time since the last request to this endpoint for any server. The first request after the manager starts or after a period of inactivity will report 0.0% CPU. Subsequent calls provide a more accurate reading. Accuracy might be limited on Linux when using screen.

This endpoint is exempt from CSRF protection but requires authentication.

Authentication:

Required (JWT or active Web UI session).

Path Parameters:

• server_name(string)(Required): The unique name of the server instance.

Request Body:

None.

Success Response (`200 OK`):

Returned regardless of whether the server is running or not.

• If Server Process is Found:

  {
      "status": "success",
      "process_info": {
          "pid": 12345,
          "cpu_percent": 10.5,
          "memory_mb": 512.5,
          "uptime": "1:00:00"
      }
  }

  • status: "success"
  • process_info (*object*): Details of the running process (PID, CPU%, Memory MB, Uptime string).
• If Server Process is Not Found / Not Running:

  {
      "status": "success",
      "process_info": null,
      "message": "Server '<server_name>' is not running."
  }

  • status: "success"
  • process_info: `null`
  • message: Indicates server not running.

Error Responses:

• 400 Bad Request:
  • If server_name is invalid:

    {"status": "error", "message": "Invalid input: Server name cannot be empty."}

    .
• 401 Unauthorized:
  • Authentication missing or invalid.
• 500 Internal Server Error:
  • If configuration error (e.g., invalid BASE_DIR):

    {"status": "error", "message": "Server configuration error: BASE_DIR setting is missing or empty in configuration."}

    .
  • If `psutil` is required but not installed:

    {"status": "error", "message": "Error getting process info: 'psutil' is required for process monitoring."}

    .
  • If error retrieving process details via `psutil` (permissions, OS error):

    {"status": "error", "message": "Error getting process info: Error getting process details for '<server_name>': ..."}

    .
  • If unexpected error occurs:

    {"status": "error", "message": "An unexpected error occurred: <original error message>"}

    .

curl Example (Bash):

curl -X GET -H "Authorization: Bearer YOUR_JWT_TOKEN" \
     http://<your-manager-host>:<port>/api/server/<server_name>/status_info

PowerShell Example:

$headers = @{ Authorization = 'Bearer YOUR_JWT_TOKEN' }
Invoke-RestMethod -Method Get -Uri "http://<your-manager-host>:<port>/api/server/<server_name>/status_info" -Headers $headers

POST /api/server/{server_name}/start - Start Server

Starts the specified Bedrock server instance process. Uses systemd (with screen fallback) on Linux or direct process creation on Windows. Waits for confirmation that the server process is running.

This endpoint is exempt from CSRF protection but requires authentication.

Authentication:

Required (JWT or active Web UI session).

Path Parameters:

• server_name(string)(Required): The unique name of the server instance to start.

Request Body:

None.

Success Response (`200 OK`):

Returned when the server process is successfully initiated and confirmed running.

{
    "status": "success",
    "message": "Server '<server_name>' started successfully."
}

Error Responses:

• 400 Bad Request:
  • Invalid server_name:

    {"status": "error", "message": "Invalid input: Server name cannot be empty."}

    .
• 401 Unauthorized:
  • Authentication missing or invalid.
• 404 Not Found:
  • Server executable not found:

    {"status": "error", "message": "Server not found: Server executable 'bedrock_server.exe' not found in C:\\path\\to\\servers\\MyServer"}

    .
• 500 Internal Server Error:
  • Configuration error (e.g., invalid BASE_DIR):

    {"status": "error", "message": "Server configuration error: BASE_DIR setting is missing or empty in configuration."}

    .
  • Server already running:

    {"status": "error", "message": "Failed to start server '<server_name>': Server '<server_name>' is already running."}

    .
  • OS-specific start failure (unsupported OS, systemd/screen error, Windows error):

    {"status": "error", "message": "Failed to start server '<server_name>': Unsupported operating system: Darwin"}

    or

    {"status": "error", "message": "Failed to start server '<server_name>': Failed to start server executable 'C:\\path\\to\\bedrock_server.exe': [WinError 5] Access is denied"}

    or

    {"status": "error", "message": "Failed to start server '<server_name>': Failed to start server '<server_name>' using screen. Error: Must be connected to a terminal."}

    .
  • Required command not found (Linux: systemctl, screen):

    {"status": "error", "message": "Failed to start server '<server_name>': Command 'screen' not found in system PATH."}

    .
  • Start timed out:

    {"status": "error", "message": "Failed to start server '<server_name>': Server '<server_name>' failed to start within the timeout."}

    .
  • Unexpected error:

    {"status": "error", "message": "An unexpected error occurred: <original error message>"}

    .

curl Example (Bash):

curl -X POST -H "Authorization: Bearer YOUR_JWT_TOKEN" \
     http://<your-manager-host>:<port>/api/server/<server_name>/start

PowerShell Example:

$headers = @{ Authorization = 'Bearer YOUR_JWT_TOKEN' }
Invoke-RestMethod -Method Post -Uri "http://<your-manager-host>:<port>/api/server/<server_name>/start" -Headers $headers

POST /api/server/{server_name}/stop - Stop Server

Stops the specified running Bedrock server instance. Attempts graceful shutdown (Linux) or terminates (Windows). Waits for termination.

This endpoint is exempt from CSRF protection but requires authentication.

Authentication:

Required (JWT or active Web UI session).

Path Parameters:

• server_name(string)(Required): The unique name of the server instance to stop.

Request Body:

None.

Success Response (`200 OK`):

Returned if server stops successfully or was already stopped.

{
    "status": "success",
    "message": "Server '<server_name>' stopped successfully."
}

or

{
    "status": "success",
    "message": "Server '<server_name>' was already stopped."
}

Error Responses:

• 400 Bad Request:
  • Invalid server_name.
• 401 Unauthorized:
  • Authentication missing or invalid.
• 500 Internal Server Error:
  • Configuration error (e.g., invalid BASE_DIR).
  • Sending 'stop' command failed (Linux):

    {"status": "error", "message": "Failed to stop server '<server_name>': Error sending command: Failed to find screen session 'bedrock-<server_name>' to send command to."}

    .
  • Executable missing but process found:

    {"status": "error", "message": "Server '<server_name>' process found but executable missing. Stop failed."}

    .
  • Stop timed out:

    {"status": "error", "message": "Failed to stop server '<server_name>': Server '<server_name>' failed to stop within the timeout. Manual intervention may be required."}

    .
  • Underlying stop mechanism failed (systemd, Windows terminate):

    {"status": "error", "message": "Failed to stop server '<server_name>': Stopping via systemctl failed (maybe service wasn't running under systemd?): ..."}

    or

    {"status": "error", "message": "Failed to stop server '<server_name>': Unexpected error stopping server '<server_name>': ..."}

    .
  • Required command not found (Linux: systemctl, screen):

    {"status": "error", "message": "Failed to stop server '<server_name>': Command 'screen' not found in system PATH."}

    .
  • Unexpected error.
• 501 Not Implemented:
  • Attempting graceful stop on unsupported OS:

    {"status": "error", "message": "Failed to stop server '<server_name>': Unsupported operating system: Darwin"}

    .

curl Example (Bash):

curl -X POST -H "Authorization: Bearer YOUR_JWT_TOKEN" \
     http://<your-manager-host>:<port>/api/server/<server_name>/stop

PowerShell Example:

$headers = @{ Authorization = 'Bearer YOUR_JWT_TOKEN' }
Invoke-RestMethod -Method Post -Uri "http://<your-manager-host>:<port>/api/server/<server_name>/stop" -Headers $headers

POST /api/server/{server_name}/restart - Restart Server

Restarts the specified Bedrock server instance. If running, sends warning (Linux), stops, then starts. If stopped, just starts.

This endpoint is exempt from CSRF protection but requires authentication.

Authentication:

Required (JWT or active Web UI session).

Path Parameters:

• server_name(string)(Required): The unique name of the server instance to restart.

Request Body:

None.

Success Response (`200 OK`):

Returned when the restart sequence completes successfully.

{
    "status": "success",
    "message": "Server '<server_name>' restarted successfully."
}

or if initially stopped:

{
    "status": "success",
    "message": "Server '<server_name>' was not running and was started."
}

Error Responses:

• 400 Bad Request:
  • Invalid server_name.
• 401 Unauthorized:
  • Authentication missing or invalid.
• 500 Internal Server Error:
  • Configuration error (e.g., invalid BASE_DIR).
  • Stop phase failed: (command error, timeout, OS error):

    {"status": "error", "message": "Restart failed during stop phase: Failed to stop server '<server_name>': Server '<server_name>' failed to stop within the timeout. Manual intervention may be required."}

    or

    {"status": "error", "message": "Restart failed during stop phase: Failed to stop server '<server_name>': Error sending command: Failed to find screen session 'bedrock-<server_name>' to send command to."}

    .
  • Start phase failed: (executable missing, config error, OS error, timeout):

    {"status": "error", "message": "Restart failed during start phase: Failed to start server '<server_name>': Server executable 'bedrock_server' not found in /path/to/servers/<server_name>"}

    or

    {"status": "error", "message": "Restart failed during start phase: Failed to start server '<server_name>': Server '<server_name>' failed to start within the timeout."}

    .
  • Unexpected error during orchestration.
• 501 Not Implemented:
  • Underlying stop or start mechanisms not supported on OS:

    {"status": "error", "message": "Restart failed during stop phase: Failed to stop server '<server_name>': Unsupported operating system: Darwin"}

    or start phase equivalent.

curl Example (Bash):

curl -X POST -H "Authorization: Bearer YOUR_JWT_TOKEN" \
     http://<your-manager-host>:<port>/api/server/<server_name>/restart

PowerShell Example:

$headers = @{ Authorization = 'Bearer YOUR_JWT_TOKEN' }
Invoke-RestMethod -Method Post -Uri "http://<your-manager-host>:<port>/api/server/<server_name>/restart" -Headers $headers

POST /api/server/{server_name}/send_command - Send Command

Sends a command string to the specified running Bedrock server instance's console input (uses screen on Linux, Named Pipes on Windows).

This endpoint is exempt from CSRF protection but requires authentication.

Authentication:

Required (JWT or active Web UI session).

Path Parameters:

• server_name(string)(Required): The unique name of the target server instance.

Request Body (application/json):

{
    "command": "your server command here"
}

• command(string)(Required): Command string to send. Must not be empty/whitespace.

Success Response (`200 OK`):

Returned when command sent successfully (doesn't confirm server processed it).

{
    "status": "success",
    "message": "Command '<command>' sent successfully."
}

Error Responses:

• 400 Bad Request:
  • Invalid/missing JSON body.
  • Missing, invalid, or empty command field:

    {"status": "error", "message": "Request body must contain a non-empty string 'command' field."}

    .
  • Invalid server_name.
• 401 Unauthorized:
  • Authentication missing or invalid.
• 404 Not Found:
  • Server executable missing:

    {"status": "error", "message": "Server not found: Server executable 'bedrock_server' not found in /path/to/servers/MyServer"}

    .
• 500 Internal Server Error:
  • Configuration error (e.g., invalid BASE_DIR).
  • Server not running or cannot communicate:

    {"status": "error", "message": "Failed to send command: Server 'MyServer' is not running."}

    or

    {"status": "error", "message": "Failed to send command: Screen session 'bedrock-MyServer' not found."}

    or

    {"status": "error", "message": "Failed to send command: Pipe '\\\\.\\pipe\\BedrockServerMyServer' does not exist. Server likely not running."}

    .
  • Error during command sending (screen error, pipe error):

    {"status": "error", "message": "Failed to send command: Failed to send command via screen: Command '['/usr/bin/screen', '-S', 'bedrock-MyServer', '-X', 'stuff', 'list\\n']' returned non-zero exit status 1."}

    or

    {"status": "error", "message": "Failed to send command: Windows error sending command: (109, 'CreateFile', 'The pipe has been ended.')"}

    .
  • Required command not found (Linux: screen):

    {"status": "error", "message": "Failed to send command: Command 'screen' not found. Is it installed?"}

    .
  • Unexpected error.
• 501 Not Implemented:
  • Sending commands not supported on OS:

    {"status": "error", "message": "Failed to send command: Sending commands not supported on Darwin"}

    .
  • Missing required Windows components (pywin32):

    {"status": "error", "message": "Failed to send command: Cannot send command on Windows: 'pywin32' module not found."}

    .

curl Example (Bash):

curl -X POST -H "Authorization: Bearer YOUR_JWT_TOKEN" -H "Content-Type: application/json" \
     -d '{"command": "say Hello from API!"}' \
     http://<your-manager-host>:<port>/api/server/<server_name>/send_command

PowerShell Example:

$headers = @{ Authorization = 'Bearer YOUR_JWT_TOKEN'; 'Content-Type' = 'application/json' }
$body = @{ command = 'say Hello from API!' } | ConvertTo-Json
Invoke-RestMethod -Method Post -Uri "http://<your-manager-host>:<port>/api/server/<server_name>/send_command" -Headers $headers -Body $body

POST /api/server/{server_name}/update - Update Server

Checks for the latest Bedrock Dedicated Server version and updates the server instance if a newer version is available or if the installed version is unknown. Handles download, backup, extraction, and optionally in-game notification.

This endpoint is exempt from CSRF protection but requires authentication.

Authentication:

Required (JWT or active Web UI session).

Path Parameters:

• server_name(string)(Required): The unique name of the server instance to update.

Request Body:

None.

Success Response (`200 OK`):

Returned when the update check/process completes.

• If update performed:

  {
      "status": "success",
      "updated": true,
      "new_version": "1.20.81.01",
      "message": "Server '<server_name>' update process completed. New version: 1.20.81.01."
  }

• If already up-to-date:

  {
      "status": "success",
      "updated": false,
      "new_version": "1.20.73.02",
      "message": "Server is already up-to-date."
  }

• status: Always "success".
• updated (*boolean*): `true` if a new version was installed.
• new_version (*string | null*): Version string now installed (or current if no update).
• message (*string*): Descriptive outcome message.

Error Responses:

• 400 Bad Request:
  • Invalid server_name.
• 401 Unauthorized:
  • Authentication missing or invalid.
• 500 Internal Server Error:
  • Configuration error (missing BASE_DIR, DOWNLOAD_DIR, BACKUP_DIR).
  • Reading server config failed.
  • Internet connectivity check failed:

    {"status": "error", "message": "Server Update failed: Failed to verify internet connectivity: No internet connection detected."}

    .
  • Download URL lookup failed:

    {"status": "error", "message": "Server Update failed: Failed to fetch download page 'https://www.minecraft.net/en-us/download/server/bedrock': ..."}

    or

    {"status": "error", "message": "Server Update failed: Could not find a download URL matching OS 'Linux' and version type 'LATEST' on page ..."}

    .
  • File download failed:

    {"status": "error", "message": "Server Update failed: Download failed for '<download_url>': 404 Client Error: Not Found for url: <download_url>"}

    .
  • Stopping server before update failed.
  • Backing up server before update failed.
  • Extracting downloaded ZIP failed (corrupt, permissions, disk full):

    {"status": "error", "message": "Server Update failed: Invalid ZIP file: '/path/to/downloads/stable/bedrock-server-1.20.xx.xx.zip'. Bad magic number for file header"}

    or

    {"status": "error", "message": "Server Update failed: Error during file extraction: [Errno 13] Permission denied: '/path/to/servers/<server_name>/bedrock_server'"}

    .
  • Writing new version/status to config failed.
  • Restarting server after update failed (logged, doesn't usually cause API 500).
  • Unexpected error.

curl Example (Bash):

curl -X POST -H "Authorization: Bearer YOUR_JWT_TOKEN" \
     http://<your-manager-host>:<port>/api/server/<server_name>/update

PowerShell Example:

$headers = @{ Authorization = 'Bearer YOUR_JWT_TOKEN' }
Invoke-RestMethod -Method Post -Uri "http://<your-manager-host>:<port>/api/server/<server_name>/update" -Headers $headers

DELETE /api/server/{server_name}/delete - Delete Server

Permanently deletes all data associated with the specified server instance (installation, config, backups). Irreversible action. Stops the server if running.

This endpoint is exempt from CSRF protection but requires authentication.

Authentication:

Required (JWT or active Web UI session).

Path Parameters:

• server_name(string)(Required): The unique name of the server instance to delete.

Request Body:

None.

Success Response (`200 OK`):

Returned when all associated data has been removed.

{
    "status": "success",
    "message": "All data for server '<server_name>' deleted successfully."
}

Error Responses:

• 400 Bad Request:
  • Invalid server_name.
• 401 Unauthorized:
  • Authentication missing or invalid.
• 500 Internal Server Error:
  • Configuration error (missing BASE_DIR, BACKUP_DIR, config path).
  • Stopping server before deletion failed (timeout, command error):

    {"status": "error", "message": "Failed to stop server '<server_name>' before deletion: Failed to stop server '<server_name>': Server '<server_name>' failed to stop within the timeout. Manual intervention may be required.. Deletion aborted."}

    .
  • Deleting server directories failed (permissions, files in use):

    {"status": "error", "message": "Error deleting server directories: Failed to completely delete server '<server_name>'. Failed items: installation directory '/path/to/servers/<server_name>' ([Errno 13] Permission denied)"}

    .
  • Unexpected error during stop or deletion.

curl Example (Bash):

curl -X DELETE -H "Authorization: Bearer YOUR_JWT_TOKEN" \
     http://<your-manager-host>:<port>/api/server/<server_name>/delete

PowerShell Example:

$headers = @{ Authorization = 'Bearer YOUR_JWT_TOKEN' }
Invoke-RestMethod -Method Delete -Uri "http://<your-manager-host>:<port>/api/server/<server_name>/delete" -Headers $headers

POST /api/server/{server_name}/export_world - Export World

Triggers an export of the server's currently configured world into a .mcworld archive file saved in the configured BACKUP_DIR.

This endpoint is exempt from CSRF protection but requires authentication.

Authentication:

Required (JWT or active Web UI session).

Path Parameters:

• server_name(string)(Required): The unique name of the server instance.

Request Body:

None.

Success Response (`200 OK`):

Returned when the world is successfully archived.

{
    "status": "success",
    "export_file": "/path/to/configured/backups/MyServer/Bedrock_level_export_20240115_103000.mcworld",
    "message": "World exported successfully."
}

• status: Always "success".
• export_file: Full path to the created .mcworld file.
• message: Confirmation message.

Error Responses:

• 400 Bad Request:
  • Invalid server_name.
• 401 Unauthorized:
  • Authentication missing or invalid.
• 500 Internal Server Error:
  • Configuration error (missing BASE_DIR, BACKUP_DIR).
  • Cannot read server.properties or find level-name.
  • World directory not found:

    {"status": "error", "message": "Failed to export world: World directory 'Bedrock level' not found at expected location: /path/to/servers/MyServer/worlds/Bedrock level"}

    .
  • Archive creation failed (disk space, permissions, zip error):

    {"status": "error", "message": "Failed to export world: Failed to create world backup archive: [Errno 28] No space left on device"}

    or

    {"status": "error", "message": "Failed to export world: Cannot create target directory '/path/to/backups/MyServer': [Errno 13] Permission denied"}

    .
  • Unexpected error.

curl Example (Bash):

curl -X POST -H "Authorization: Bearer YOUR_JWT_TOKEN" \
     http://<your-manager-host>:<port>/api/server/<server_name>/export_world

PowerShell Example:

$headers = @{ Authorization = 'Bearer YOUR_JWT_TOKEN' }
Invoke-RestMethod -Method Post -Uri "http://<your-manager-host>:<port>/api/server/<server_name>/export_world" -Headers $headers

POST /api/server/{server_name}/backups/prune - Prune Server Backups

Deletes older backups (world, properties, json) for a specific server, keeping a specified number of newest files for each type.

This endpoint is exempt from CSRF protection but requires authentication.

Authentication:

Required (JWT or active Web UI session).

Path Parameters:

• server_name(string)(Required): The unique name of the server.

Query Parameters:

None.

Request Body (application/json, optional):

{
    "keep": 10
}

• keep(integer)(Optional): Number of backups of *each type* to keep. Defaults to BACKUP_KEEP setting (or 3).

Success Response (`200 OK`):

Returned when pruning completes or if no backups found.

• If pruning occurred/not needed:

  {"status": "success", "message": "Backup pruning completed for server '<server_name>'."}

• If backup directory not found:

  {"status": "success", "message": "No backup directory found, nothing to prune."}

Error Responses:

• 400 Bad Request:
  • Invalid server_name.
  • Invalid keep value (not integer).
  • Resolved `keep` value is negative/invalid.
• 401 Unauthorized:
  • Authentication missing or invalid.
• 500 Internal Server Error:
  • Configuration error (missing BASE_DIR, BACKUP_DIR).
  • Backup directory path exists but is not a directory.
  • Error determining world name (for world backup prefix).
  • File system errors during pruning (listing, sorting, deleting) for any type:

    {"status": "error", "message": "Pruning failed for some backup types: World backups (Failed to delete all required old backups (1 deletion(s) failed). Check logs.); JSON backups (Error pruning backups in '/path/to/backups/MyServer': [Errno 13] Permission denied)"}

    .
  • Unexpected error.

curl Example (Bash):

# Using default keep count
curl -X POST -H "Authorization: Bearer YOUR_JWT_TOKEN" \
     http://<your-manager-host>:<port>/api/server/<server_name>/backups/prune

# Specifying keep count
curl -X POST -H "Authorization: Bearer YOUR_JWT_TOKEN" -H "Content-Type: application/json" \
     -d '{"keep": 5}' \
     http://<your-manager-host>:<port>/api/server/<server_name>/backups/prune

PowerShell Example:

# Using default keep count
$headers = @{ Authorization = 'Bearer YOUR_JWT_TOKEN' }
Invoke-RestMethod -Method Post -Uri "http://<your-manager-host>:<port>/api/server/<server_name>/backups/prune" -Headers $headers

# Specifying keep count
$headers = @{ Authorization = 'Bearer YOUR_JWT_TOKEN'; 'Content-Type' = 'application/json' }
$body = @{ keep = 5 } | ConvertTo-Json
Invoke-RestMethod -Method Post -Uri "http://<your-manager-host>:<port>/api/server/<server_name>/backups/prune" -Headers $headers -Body $body

POST /api/server/{server_name}/backup/action - Trigger Backup

Triggers a backup operation (world, specific config, or all) for the specified server. Optionally stops/starts the server if running.

This endpoint is exempt from CSRF protection but requires authentication.

Authentication:

Required (JWT or active Web UI session).

Path Parameters:

• server_name(string)(Required): The unique name of the server instance.

Request Body (application/json):

• For World Backup:

  {"backup_type": "world"}

• For Config Backup:

  {"backup_type": "config", "file_to_backup": "server.properties"}

  (Use relative path within server dir).
• For Full Backup:

  {"backup_type": "all"}

• backup_type(string)(Required): `"world"`, `"config"`, or `"all"`.
• file_to_backup(string)(Required if `backup_type` is `"config"`): Relative path of config file.

Success Response (`200 OK`):

Returned when the specified backup completes.

{
    "status": "success",
    "message": "World backup completed successfully for server '<server_name>'."
}

(Message varies by type. May indicate restart error if applicable.)

Error Responses:

• 400 Bad Request:
  • Invalid/missing JSON body.
  • Missing/invalid backup_type.
  • Missing/invalid file_to_backup for config type.
  • Specified file_to_backup does not exist.
  • Other invalid input (e.g., empty server_name).
• 401 Unauthorized:
  • Authentication missing or invalid.
• 500 Internal Server Error:
  • Configuration error (missing BASE_DIR, BACKUP_DIR).
  • Error stopping/starting server (if applicable).
  • World backup failed (world name error, zip error, dir error):

    {"status": "error", "message": "World backup failed: World backup failed for 'MyServer': Could not determine world name for server 'MyServer'. Cannot perform world backup."}

    or

    {"status": "error", "message": "World backup failed: World backup failed for 'MyServer': Failed to create world backup archive: [Errno 13] Permission denied: '/path/to/backups/MyServer/world_backup_...mcworld.zip'"}

    .
  • Config backup failed (copy error, permissions):

    {"status": "error", "message": "Config file backup for 'server.properties' failed: Failed to copy config file 'server.properties': [Errno 13] Permission denied"}

    .
  • "All" backup failed on any component:

    {"status": "error", "message": "Full backup failed: World backup failed during full backup of 'MyServer'."}

    or

    {"status": "error", "message": "Full backup failed: Full backup completed with errors. Failed to back up config file(s): permissions.json."}

    .
  • Unexpected error.

curl Example (Bash - World Backup):

curl -X POST -H "Authorization: Bearer YOUR_JWT_TOKEN" -H "Content-Type: application/json" \
     -d '{"backup_type": "world"}' \
     http://<your-manager-host>:<port>/api/server/<server_name>/backup/action

PowerShell Example (Config Backup):

$headers = @{ Authorization = 'Bearer YOUR_JWT_TOKEN'; 'Content-Type' = 'application/json' }
$body = @{ backup_type = 'config'; file_to_backup = 'server.properties' } | ConvertTo-Json
Invoke-RestMethod -Method Post -Uri "http://<your-manager-host>:<port>/api/server/<server_name>/backup/action" -Headers $headers -Body $body

POST /api/server/{server_name}/restore/action - Trigger Restore

Restores a server's world or a specific config file from a backup. Warning: Overwrites current files. Recommended to stop server first (API handles by default).

This endpoint is exempt from CSRF protection but requires authentication.

Authentication:

Required (JWT or active Web UI session).

Path Parameters:

• server_name(string)(Required): The unique name of the server instance.

Request Body (application/json):

{
    "restore_type": "world", // or "config"
    "backup_file": "/full/path/to/backups/MyServer/backup_file.mcworld" // or ...properties, etc.
}

• restore_type(string)(Required): `"world"` or `"config"`.
• backup_file(string)(Required): Full, absolute path to backup file (must be within configured BACKUP_DIR).

Success Response (`200 OK`):

Returned when restore completes.

{
    "status": "success",
    "message": "Restoration from 'world_backup_xyz.mcworld' (type: world) completed successfully."
}

(May indicate restart error if applicable.)

Error Responses:

• 400 Bad Request:
  • Invalid/missing JSON body.
  • Missing/invalid restore_type or backup_file.
  • backup_file path outside BACKUP_DIR.
  • Other invalid input (e.g., empty server_name).
  • Invalid config backup filename format (cannot determine original name):

    {"status": "error", "message": "Config restore failed: Could not determine original filename from backup file format: 'bad_backup_name.properties'"}

    .
• 401 Unauthorized:
  • Authentication missing or invalid.
• 404 Not Found:
  • Specified backup_file does not exist:

    {"status": "error", "message": "Backup file not found."}

    .
• 500 Internal Server Error:
  • Configuration error (missing BASE_DIR, BACKUP_DIR).
  • Error stopping/starting server (if applicable).
  • World restore failed (unzip error, file/dir error):

    {"status": "error", "message": "World restore failed: World import failed for server 'MyServer': Failed to extract archive: Error extracting zip file /path/to/backups/MyServer/world_backup_xyz.mcworld: Bad magic number for file header"}

    .
  • Config restore failed (copy error, permissions):

    {"status": "error", "message": "Config file restore failed: Failed to restore config file 'server.properties': [Errno 13] Permission denied"}

    .
  • Unexpected error.

curl Example (Bash - World Restore):

curl -X POST -H "Authorization: Bearer YOUR_JWT_TOKEN" -H "Content-Type: application/json" \
     -d '{"restore_type": "world", "backup_file": "/full/path/to/backups/MyServer/world_backup_xyz.mcworld"}' \
     http://<your-manager-host>:<port>/api/server/<server_name>/restore/action

PowerShell Example (Config Restore):

$headers = @{ Authorization = 'Bearer YOUR_JWT_TOKEN'; 'Content-Type' = 'application/json' }
$body = @{ restore_type = 'config'; backup_file = 'C:\full\path\to\backups\MyServer\server_backup_abc.properties' } | ConvertTo-Json
Invoke-RestMethod -Method Post -Uri "http://<your-manager-host>:<port>/api/server/<server_name>/restore/action" -Headers $headers -Body $body

POST /api/server/{server_name}/restore/all - Trigger Restore All

Restores server world AND standard config files from their *latest* available backups. Warning: Overwrites current files. Recommended to stop server first (API handles by default).

This endpoint is exempt from CSRF protection but requires authentication.

Authentication:

Required (JWT or active Web UI session).

Path Parameters:

• server_name(string)(Required): The unique name of the server instance.

Request Body:

None.

Success Response (`200 OK`):

Returned when restore for all components completes.

{
    "status": "success",
    "message": "Restore all completed successfully for server '<server_name>'."
}

(May indicate restart error if applicable.)

Error Responses:

• 401 Unauthorized:
  • Authentication missing or invalid.
• 500 Internal Server Error:
  • Configuration error (missing BASE_DIR, BACKUP_DIR).
  • Error stopping/starting server (if applicable).
  • Any part of the restore failed (world or config). Error message indicates failed components:

    {"status": "error", "message": "Restore all failed: Restore failed for server 'MyServer'. Failed components: World (World import failed for server 'MyServer': Failed to extract archive: ...), server.properties (Failed to restore config file 'server.properties': [Errno 13] Permission denied)"}

    .
  • Unexpected error.

curl Example (Bash):

curl -X POST -H "Authorization: Bearer YOUR_JWT_TOKEN" \
     http://<your-manager-host>:<port>/api/server/<server_name>/restore/all

PowerShell Example:

$headers = @{ Authorization = 'Bearer YOUR_JWT_TOKEN' }
Invoke-RestMethod -Method Post -Uri "http://<your-manager-host>:<port>/api/server/<server_name>/restore/all" -Headers $headers

POST /api/server/{server_name}/world/install - Install World

Installs a world from a .mcworld file into the specified server, replacing the existing world files. File must exist in configured content/worlds directory. Warning: Overwrites current world. Stops/starts server if needed.

This endpoint is exempt from CSRF protection but requires authentication.

Authentication:

Required (JWT or active Web UI session).

Path Parameters:

• server_name(string)(Required): The name of the server instance.

Request Body (application/json):

{
    "filename": "MyCoolWorld.mcworld"
}

or (with subdirectories):

{
    "filename": "user_uploads/MyCoolWorld.mcworld"
}

• filename(string)(Required): Path to .mcworld file *relative* to configured content/worlds directory. Path traversal blocked.

Success Response (`200 OK`):

Returned when world file found, validated, and extracted.

{
    "status": "success",
    "message": "World 'MyCoolWorld.mcworld' installed successfully for server '<server_name>'."
}

(May indicate restart error if applicable.)

Error Responses:

• 400 Bad Request:
  • Invalid/missing JSON body.
  • Missing/invalid filename.
  • filename path traversal attempt:

    {"status": "error", "message": "Invalid filename: Filename must be within the allowed content directory."}

    .
  • Other input validation fails (e.g., empty server_name).
• 401 Unauthorized:
  • Authentication missing or invalid.
• 404 Not Found:
  • Specified .mcworld file not found in content/worlds:

    {"status": "error", "message": "Selected world file not found: /path/to/content/worlds/nonexistent.mcworld"}

    .
• 500 Internal Server Error:
  • Configuration error (missing BASE_DIR, CONTENT_DIR).
  • Error stopping/starting server (if applicable).
  • Cannot determine target world name from server.properties:

    {"status": "error", "message": "World installation error: World import failed: Cannot import world: Failed to get world name for server '<server_name>'."}

    .
  • World extraction failed (invalid format, disk full, permissions):

    {"status": "error", "message": "World installation error: World import failed: Error extracting archive '/path/to/content/worlds/MyCoolWorld.mcworld': File is not a zip file"}

    or

    {"status": "error", "message": "World installation error: World import failed: Failed to remove existing world directory '/path/to/servers/MyServer/worlds/Bedrock level': [Errno 13] Permission denied"}

    .
  • Unexpected error.

curl Example (Bash):

curl -X POST -H "Authorization: Bearer YOUR_JWT_TOKEN" -H "Content-Type: application/json" \
     -d '{"filename": "MyDownloadedWorld.mcworld"}' \
     http://<your-manager-host>:<port>/api/server/<server_name>/world/install

PowerShell Example:

$headers = @{ Authorization = 'Bearer YOUR_JWT_TOKEN'; 'Content-Type' = 'application/json' }
$body = @{ filename = 'MyDownloadedWorld.mcworld' } | ConvertTo-Json
Invoke-RestMethod -Method Post -Uri "http://<your-manager-host>:<port>/api/server/<server_name>/world/install" -Headers $headers -Body $body

POST /api/server/{server_name}/addon/install - Install Addon

Installs addon pack (.mcaddon/.mcpack) into the server. File must exist in configured content/addons directory. Extracts packs and updates world manifests. Stops/starts server if needed.

This endpoint is exempt from CSRF protection but requires authentication.

Authentication:

Required (JWT or active Web UI session).

Path Parameters:

• server_name(string)(Required): The name of the server instance.

Request Body (application/json):

{
    "filename": "CoolBehaviorPack.mcpack"
}

or

{
    "filename": "collections/AwesomeAddonCollection.mcaddon"
}

• filename(string)(Required): Path to addon file *relative* to configured content/addons directory. Path traversal blocked.

Success Response (`200 OK`):

Returned when addon found, validated, processed, and installed.

{
    "status": "success",
    "message": "Addon 'AwesomeAddonCollection.mcaddon' installed successfully for server '<server_name>'."
}

(May indicate restart error if applicable.)

Error Responses:

• 400 Bad Request:
  • Invalid/missing JSON body.
  • Missing/invalid filename.
  • filename path traversal attempt.
  • Unsupported addon extension (not .mcaddon or .mcpack):

    {"status": "error", "message": "Addon installation error: Unsupported addon file type: 'MyAddon.zip'. Only .mcaddon and .mcpack are supported."}

    .
  • Invalid/missing manifest.json in addon:

    {"status": "error", "message": "Addon installation error: Invalid manifest structure in /path/to/temp/..../manifest.json. Missing fields: ['uuid']"}

    or

    {"status": "error", "message": "Addon installation error: Manifest not found in pack: /path/to/temp/..."}

    .
  • Other input validation fails (e.g., empty server_name).
• 401 Unauthorized:
  • Authentication missing or invalid.
• 404 Not Found:
  • Specified addon file not found in content/addons:

    {"status": "error", "message": "Selected addon file not found: /path/to/content/addons/nonexistent.mcpack"}

    .
• 500 Internal Server Error:
  • Configuration error (missing BASE_DIR, CONTENT_DIR).
  • Error stopping/starting server (if applicable).
  • Cannot determine target world name from server.properties:

    {"status": "error", "message": "Addon installation error: Failed to determine world name or paths for server '<server_name>': Could not determine world name for server '<server_name>'."}

    .
  • Corrupted addon file (not valid zip):

    {"status": "error", "message": "Addon installation error: Invalid .mcpack file (not a zip): CoolBehaviorPack.mcpack"}

    .
  • File system errors during extraction/installation (copying, creating dirs, updating JSONs, permissions, disk full):

    {"status": "error", "message": "Addon installation error: Failed to copy behavior pack files: [Errno 13] Permission denied: '/path/to/servers/MyServer/worlds/Bedrock level/behavior_packs/CoolPack_1.0.0/script.js'"}

    or

    {"status": "error", "message": "Addon installation error: Failed to update world activation JSON 'world_resource_packs.json': Failed to write world pack JSON: world_resource_packs.json"}

    .
  • Unexpected error.

curl Example (Bash):

curl -X POST -H "Authorization: Bearer YOUR_JWT_TOKEN" -H "Content-Type: application/json" \
     -d '{"filename": "AwesomeAddonCollection.mcaddon"}' \
     http://<your-manager-host>:<port>/api/server/<server_name>/addon/install

PowerShell Example:

$headers = @{ Authorization = 'Bearer YOUR_JWT_TOKEN'; 'Content-Type' = 'application/json' }
$body = @{ filename = 'AwesomeAddonCollection.mcaddon' } | ConvertTo-Json
Invoke-RestMethod -Method Post -Uri "http://<your-manager-host>:<port>/api/server/<server_name>/addon/install" -Headers $headers -Body $body

POST /api/players/scan - Scan Player Logs

Triggers a scan of all server log files (server_output.txt) to find player connection entries (Name, XUID) and update the central players.json file.

This endpoint is exempt from CSRF protection but requires authentication.

Authentication:

Required (JWT or active Web UI session).

Path Parameters:

None.

Query Parameters:

None.

Request Body:

None.

Success Response (`200 OK`):

Indicates scan completion.

• If players found/updated:

  {
      "status": "success", "players_found": true, "message": "Player scan completed and data saved."
  }

• If no new players found:

  {
      "status": "success", "players_found": false, "message": "Player scan completed, no new player data found."
  }

• If no server directories found:

  {
      "status": "success", "players_found": false, "message": "No server directories found."
  }

Error Responses:

• 401 Unauthorized:
  • Authentication missing or invalid.
• 500 Internal Server Error:
  • Configuration error (missing BASE_DIR, config dir).
  • Errors scanning some log files (permissions):

    {"status": "error", "message": "Scan completed with errors for server(s): ServerA, ServerC. Player data found in other logs was saved."}

    .
  • Error saving data to players.json (write permissions, disk full):

    {"status": "error", "message": "Error saving player data to JSON: Failed to write players data to '/path/to/config/players.json': [Errno 13] Permission denied"}

    .
  • Unexpected error.

curl Example (Bash):

curl -X POST -H "Authorization: Bearer YOUR_JWT_TOKEN" \
     http://<your-manager-host>:<port>/api/players/scan

PowerShell Example:

$headers = @{ Authorization = 'Bearer YOUR_JWT_TOKEN' }
Invoke-RestMethod -Method Post -Uri "http://<your-manager-host>:<port>/api/players/scan" -Headers $headers

GET /api/server/{server_name}/allowlist - Get Allowlist

Retrieves the current list of players from the server's allowlist.json file.

This endpoint is exempt from CSRF protection but requires authentication.

Authentication:

Required (JWT or active Web UI session).

Path Parameters:

• server_name(string)(Required): The name of the server instance.

Query Parameters:

None.

Request Body:

None.

Success Response (`200 OK`):

Returns the list of players currently in allowlist.json.

{
    "status": "success",
    "existing_players": [
        {
            "ignoresPlayerLimit": false,
            "name": "PlayerOne"
        },
        {
            "ignoresPlayerLimit": false,
            "name": "PlayerTwoXUID"
        }
    ],
    "message": "Successfully retrieved 2 players from allowlist."
}

or if empty/not found:

{
    "status": "success",
    "existing_players": [],
    "message": "Successfully retrieved 0 players from allowlist."
}

• status: Always "success".
• existing_players (*list[object]*): List of player objects (containing ignoresPlayerLimit and name).
• message (*string*): Indicates number retrieved.

Error Responses:

• 401 Unauthorized:
  • Authentication missing or invalid.
• 500 Internal Server Error:
  • Invalid server_name.
  • Configuration error (missing BASE_DIR, server dir not found).
  • Failed to read allowlist.json (permissions, OS error).
  • Invalid JSON in allowlist.json:

    { "status": "error", "message": "Error retrieving allowlist: Invalid JSON in allowlist file: /path/to/servers/<server_name>/allowlist.json" }

    .
  • Unexpected error.

curl Example (Bash):

curl -X GET -H "Authorization: Bearer YOUR_JWT_TOKEN" \
     http://<your-manager-host>:<port>/api/server/<server_name>/allowlist

PowerShell Example:

$headers = @{ Authorization = 'Bearer YOUR_JWT_TOKEN' }
Invoke-RestMethod -Method Get -Uri "http://<your-manager-host>:<port>/api/server/<server_name>/allowlist" -Headers $headers

POST /api/server/{server_name}/allowlist/add - Add Players to Allowlist

Adds players to the server's allowlist.json file. Appends players from request if not already present (case-insensitive name check).

Note: This is an ADD operation, not replace.

This endpoint is exempt from CSRF protection but requires authentication.

Authentication:

Required (JWT or active Web UI session).

Path Parameters:

• server_name(string)(Required): The name of the server instance.

Request Body (application/json):

{
    "players": ["NewPlayer1", "AnotherPlayer"],
    "ignoresPlayerLimit": false
}

• players(list[string])(Required): List of player names (Gamertags) to add. Empty/invalid names ignored.
• ignoresPlayerLimit(boolean)(Optional, default: false): Sets this flag for all players added in this request.

Success Response (`200 OK`):

Returned on completion, even if no new players added.

• If new players added:

  {"status": "success", "message": "Allowlist saved successfully with X player(s)."}

• If no new players added:

  {"status": "success", "message": "No new players provided or all provided players were duplicates/invalid."}

Error Responses:

• 400 Bad Request:
  • Invalid/missing JSON body.
  • Missing or non-list players key.
  • Non-boolean ignoresPlayerLimit key.
  • Invalid server_name.
• 401 Unauthorized:
  • Authentication missing or invalid.
• 500 Internal Server Error:
  • Configuration error (missing BASE_DIR, server dir not found).
  • Failed reading existing allowlist.json (permissions, invalid JSON).
  • Failed writing updated allowlist.json (permissions, disk full).
  • Unexpected error.

curl Example (Bash):

curl -X POST -H "Authorization: Bearer YOUR_JWT_TOKEN" -H "Content-Type: application/json" \
     -d '{"players": ["AdminUser", "VIP_Player"], "ignoresPlayerLimit": false}' \
     http://<your-manager-host>:<port>/api/server/<server_name>/allowlist/add

PowerShell Example:

$headers = @{ Authorization = 'Bearer YOUR_JWT_TOKEN'; 'Content-Type' = 'application/json' }
$body = @{ players = @('AdminUser', 'VIP_Player'); ignoresPlayerLimit = $false } | ConvertTo-Json
Invoke-RestMethod -Method Post -Uri "http://<your-manager-host>:<port>/api/server/<server_name>/allowlist/add" -Headers $headers -Body $body

PUT /api/server/{server_name}/permissions - Update Player Permissions

Updates permission levels for players in permissions.json. Takes map of XUIDs to permission levels.

This endpoint is exempt from CSRF protection but requires authentication.

Authentication:

Required (JWT or active Web UI session).

Path Parameters:

• server_name(string)(Required): The name of the server instance.

Request Body (application/json):

{
    "permissions": {
        "2535416409681153": "operator",
        "2535457894355891": "member",
        "2535400000000000": "visitor"
    }
}

• permissions(object)(Required): Object mapping player XUIDs (strings) to level strings.
  • Valid Levels: `"visitor"`, `"member"`, `"operator"` (case-insensitive).

Success Response (`200 OK`):

Returned if all valid changes applied or no valid changes submitted.

• If changes applied:

  {"status": "success", "message": "Permissions updated successfully for 2 player(s) on server '<server_name>'."}

• If no valid changes submitted:

  {"status": "success", "message": "No valid permission changes submitted."}

Error Responses:

• 400 Bad Request:
  • Invalid/missing JSON body or missing permissions key.
  • permissions value is not an object.
  • Invalid permission level provided for one or more XUIDs:

    {
        "status": "error",
        "message": "Validation failed for one or more permission levels.",
        "errors": {
            "2535411111111111": "Invalid level 'guest'. Must be one of ('visitor', 'member', 'operator')."
        }
    }

• 401 Unauthorized:
  • Authentication missing or invalid.
• 500 Internal Server Error:
  • Configuration error (missing BASE_DIR, server dir not found).
  • Failed reading/writing permissions.json for any player (permissions, invalid JSON, disk full). Response includes details:

    {
        "status": "error",
        "message": "One or more errors occurred while setting permissions for '<server_name>'.",
        "errors": {
            "2535457894355891": "Failed to configure permission: Failed to write permissions file: /path/to/servers/<server_name>/permissions.json"
        }
    }

  • Unexpected error.

curl Example (Bash):

curl -X PUT -H "Authorization: Bearer YOUR_JWT_TOKEN" -H "Content-Type: application/json" \
     -d '{"permissions": {"2535416409681153": "operator", "2535457894355891": "member"}}' \
     http://<your-manager-host>:<port>/api/server/<server_name>/permissions

PowerShell Example:

$headers = @{ Authorization = 'Bearer YOUR_JWT_TOKEN'; 'Content-Type' = 'application/json' }
$permBody = @{
    permissions = @{
        '2535416409681153' = 'operator'
        '2535457894355891' = 'member'
    }
}
$bodyJson = $permBody | ConvertTo-Json -Depth 3
Invoke-RestMethod -Method Put -Uri "http://<your-manager-host>:<port>/api/server/<server_name>/permissions" -Headers $headers -Body $bodyJson

POST /api/server/{server_name}/properties - Update Server Properties

Updates specified key-value pairs in the server.properties file. Only allowed keys are modified. Values undergo basic validation. level-name is automatically cleaned.

This endpoint is exempt from CSRF protection but requires authentication.

Authentication:

Required (JWT or active Web UI session).

Path Parameters:

• server_name(string)(Required): The name of the server instance.

Request Body (application/json):

JSON object mapping property keys to new values.

{
    "level-name": "Updated World Name",
    "max-players": "20",
    "difficulty": "hard",
    "server-port": 19133
    // Only include keys you want to change
}

Allowed Keys: server-name, level-name, gamemode, difficulty, allow-cheats, max-players, server-port, server-portv6, enable-lan-visibility, allow-list, default-player-permission-level, view-distance, tick-distance, level-seed, online-mode, texturepack-required. (Other keys ignored).

Success Response (`200 OK`):

Returned when properties successfully validated/written or if no valid/allowed changes provided.

{
    "status": "success",
    "message": "Server properties for '<server_name>' updated successfully."
}

or if no valid changes:

{
    "status": "success",
    "message": "No valid properties provided or no changes needed."
}

Error Responses:

• 400 Bad Request:
  • Invalid/missing JSON body.
  • Validation failed for one or more values. Response includes errors object:

    {
        "status": "error",
        "message": "Validation failed for one or more properties.",
        "errors": {
            "server-port": "Invalid value for 'server-port'. Must be a number between 1024 and 65535.",
            "difficulty": "Invalid value for 'difficulty'. Must be one of peaceful, easy, normal, hard."
        }
    }

  • server.properties file not found.
  • Input value contains invalid control characters.
  • Invalid server_name.
• 401 Unauthorized:
  • Authentication missing or invalid.
• 500 Internal Server Error:
  • Reading/writing server.properties failed (permissions, disk full):

    {"status": "error", "message": "Error updating properties: Failed to modify server.properties: [Errno 13] Permission denied: '/path/to/servers/<server_name>/server.properties'"}

    .
  • Unexpected error.

curl Example (Bash):

curl -X POST -H "Authorization: Bearer YOUR_JWT_TOKEN" -H "Content-Type: application/json" \
     -d '{"max-players": "12", "allow-list": "true"}' \
     http://<your-manager-host>:<port>/api/server/<server_name>/properties

PowerShell Example:

$headers = @{ Authorization = 'Bearer YOUR_JWT_TOKEN'; 'Content-Type' = 'application/json' }
# Note: Quotes may be needed around keys with hyphens depending on PowerShell version/parsing
$body = @{ 'max-players' = '12'; 'allow-list' = 'true' } | ConvertTo-Json
Invoke-RestMethod -Method Post -Uri "http://<your-manager-host>:<port>/api/server/<server_name>/properties" -Headers $headers -Body $body

POST /api/server/{server_name}/service - Configure OS Service Settings

Configures OS-specific service settings (Linux: systemd service/timer; Windows: autoupdate flag in config). Behavior depends on host OS.

This endpoint is exempt from CSRF protection but requires authentication.

Authentication:

Required (JWT or active Web UI session).

Path Parameters:

• server_name(string)(Required): The name of the server instance.

Request Body (application/json):

• On Linux:

  {
      "autoupdate": true,
      "autostart": true
  }

  • autoupdate(boolean)(Required): Configure systemd service ExecStartPre for update check.
  • autostart(boolean)(Required): Enable/disable the systemd service (systemctl --user enable/disable).
• On Windows:

  {
      "autoupdate": true
  }

  • autoupdate(boolean)(Required): Value for autoupdate setting in server's JSON config file.

Success Response (`200 OK`):

Returned when OS-specific configuration applied.

• Linux:

  {"status": "success", "message": "Systemd service created and enabled successfully."}

  (Message varies)
• Windows:

  {"status": "success", "message": "Autoupdate setting for '<server_name>' updated to true."}

  (Message varies)

Error Responses:

• 400 Bad Request:
  • Invalid/missing JSON body.
  • Incorrect boolean values for expected keys (OS-specific).
  • Invalid server_name.
• 401 Unauthorized:
  • Authentication missing or invalid.
• 403 Forbidden / 500 Internal Server Error (OS Mismatch):
  • Endpoint called on unsupported OS:

    { "status": "error", "message": "Service configuration is not supported on this operating system (Darwin)." }

    .
• 500 Internal Server Error:
  • Configuration error (missing BASE_DIR).
  • Linux: Creating systemd dir/writing service file failed (permissions, disk full).
  • Linux: systemctl command not found.
  • Linux: Reloading systemd daemon failed.
  • Linux: Enabling/disabling service via systemctl failed.
  • Windows: Writing autoupdate flag to config JSON failed.
  • Unexpected error.

curl Example (Bash - Linux):

curl -X POST -H "Authorization: Bearer YOUR_JWT_TOKEN" -H "Content-Type: application/json" \
     -d '{"autoupdate": true, "autostart": true}' \
     http://<your-manager-host>:<port>/api/server/<server_name>/service

PowerShell Example (Windows):

$headers = @{ Authorization = 'Bearer YOUR_JWT_TOKEN'; 'Content-Type' = 'application/json' }
$body = @{ autoupdate = $true } | ConvertTo-Json
Invoke-RestMethod -Method Post -Uri "http://<your-manager-host>:<port>/api/server/<server_name>/service" -Headers $headers -Body $body

POST /api/downloads/prune - Prune Download Cache

Deletes older downloaded server archives (e.g., bedrock-server-*.zip) from a specified directory, keeping a defined number of newest files.

This endpoint is exempt from CSRF protection but requires authentication.

Authentication:

Required (JWT or active Web UI session).

Path Parameters:

None.

Query Parameters:

None.

Request Body (application/json):

{
    "directory": "/path/to/your/download/cache",
    "keep": 5
}

• directory(string)(Required): Absolute path to directory containing downloads to prune.
• keep(integer)(Optional): Number of newest files to retain. Defaults to DOWNLOAD_KEEP setting (or 3).

Success Response (`200 OK`):

Indicates pruning completed successfully.

{
    "status": "success",
    "message": "Download cache pruned successfully for '/path/to/your/download/cache'."
}

(Message doesn't detail counts currently.)

Error Responses:

• 400 Bad Request:
  • Invalid/missing JSON body.
  • Missing directory field.
  • keep value is not an integer.
  • directory value is empty string.
  • Resolved `keep` value is negative/invalid.
• 401 Unauthorized:
  • Authentication missing or invalid.
• 500 Internal Server Error:
  • Specified `directory` does not exist or is not a directory.
  • Error accessing/deleting files (permissions, disk errors):

    {"status": "error", "message": "Failed to prune downloads: Failed to delete old server download '/path/to/cache/bedrock-server-old.zip': [Errno 13] Permission denied"}

    or

    {"status": "error", "message": "Failed to prune downloads: Failed to delete all required old downloads (1 failed). Check logs."}

    .
  • Unexpected error.

curl Example (Bash):

curl -X POST -H "Authorization: Bearer YOUR_JWT_TOKEN" -H "Content-Type: application/json" \
     -d '{"directory": "/opt/bedrock-server-manager/.downloads/stable", "keep": 3}' \
     http://<your-manager-host>:<port>/api/downloads/prune

PowerShell Example:

$headers = @{ Authorization = 'Bearer YOUR_JWT_TOKEN'; 'Content-Type' = 'application/json' }
$body = @{ directory = 'C:\bedrock-server-manager\.downloads\stable'; keep = 3 } | ConvertTo-Json
Invoke-RestMethod -Method Post -Uri "http://<your-manager-host>:<port>/api/downloads/prune" -Headers $headers -Body $body

POST /api/server/install - Install New Server

Creates and installs a new Bedrock server instance. Validates name/version, handles optional overwrite, downloads, extracts, and sets up initial config.

This endpoint is exempt from CSRF protection but requires authentication.

Authentication:

Required (JWT or active Web UI session).

Path Parameters:

None.

Query Parameters:

None.

Request Body (application/json):

{
    "server_name": "UniqueServerName",
    "server_version": "LATEST",
    "overwrite": false
}

• server_name(string)(Required): Desired unique name (valid directory name, no spaces/special chars except - _).
• server_version(string)(Required): Version to install ("LATEST", "PREVIEW", or specific version "1.20.81.01").
• overwrite(boolean)(Optional, default: false): If `true`, deletes existing server data first.

Success Responses:

• `201 Created` (New server installed or overwritten):

  {
      "status": "success",
      "server_name": "UniqueServerName",
      "version": "1.20.81.01", // Actual version installed
      "message": "Server 'UniqueServerName' installed successfully (Version: 1.20.81.01).",
      "next_step_url": "/server/UniqueServerName/configure_properties?new_install=true" // For UI flow
  }

  (Message might indicate final status config write failure even on success.)
• `200 OK` (Confirmation Needed) (Server exists, `overwrite` is false):

  {
      "status": "confirm_needed",
      "message": "Server 'UniqueServerName' already exists. Overwrite existing data and reinstall?",
      "server_name": "UniqueServerName",
      "server_version": "LATEST" // Original requested version
  }

Error Responses:

• 400 Bad Request:
  • Invalid/missing JSON body.
  • Missing/invalid server_name or server_version.
  • overwrite field not boolean.
  • Invalid server_name format:

    {"status": "error", "message": "Server name format is invalid: Cannot contain spaces."}

    .
  • Other input validation failures.
• 401 Unauthorized:
  • Authentication missing or invalid.
• 500 Internal Server Error:
  • Configuration error (missing BASE_DIR, DOWNLOAD_DIR, BACKUP_DIR, config path).
  • `overwrite` true but deleting existing data failed.
  • Writing initial server config failed.
  • Any step of download/install failed (connectivity, URL lookup, download, extraction, final config write):

    {"status": "error", "message": "Server Installation failed: Failed to fetch download page ..."}

    or

    {"status": "error", "message": "Server Installation failed: Failed to extract server files ..."}

    .
  • Unexpected error.

curl Example (Bash):

# Install new server (will fail if exists unless overwrite: true)
curl -X POST -H "Authorization: Bearer YOUR_JWT_TOKEN" -H "Content-Type: application/json" \
     -d '{"server_name": "MySurvivalServer", "server_version": "LATEST", "overwrite": false}' \
     http://<your-manager-host>:<port>/api/server/install

# Force overwrite existing server
curl -X POST -H "Authorization: Bearer YOUR_JWT_TOKEN" -H "Content-Type: application/json" \
     -d '{"server_name": "MySurvivalServer", "server_version": "LATEST", "overwrite": true}' \
     http://<your-manager-host>:<port>/api/server/install

PowerShell Example:

# Install new server
$headers = @{ Authorization = 'Bearer YOUR_JWT_TOKEN'; 'Content-Type' = 'application/json' }
$body = @{ server_name = 'MySurvivalServer'; server_version = 'LATEST'; overwrite = $false } | ConvertTo-Json
Invoke-RestMethod -Method Post -Uri "http://<your-manager-host>:<port>/api/server/install" -Headers $headers -Body $body

# Force overwrite existing server
$headers = @{ Authorization = 'Bearer YOUR_JWT_TOKEN'; 'Content-Type' = 'application/json' }
$body = @{ server_name = 'MySurvivalServer'; server_version = 'LATEST'; overwrite = $true } | ConvertTo-Json
Invoke-RestMethod -Method Post -Uri "http://<your-manager-host>:<port>/api/server/install" -Headers $headers -Body $body

POST /api/server/{server_name}/cron_scheduler/add - Add Cron Job (Linux Only)

Adds a new cron job entry to the crontab of the user running the manager. Linux only.

This endpoint is exempt from CSRF protection but requires authentication.

Authentication:

Required (JWT or active Web UI session).

Platform:

Linux Only.

Path Parameters:

• server_name(string)(Required): Server context (logging/auth), not usually part of the cron command itself.

Request Body (application/json):

{
    "new_cron_job": "0 3 * * * /path/to/bedrock-server-manager backup-all --server MyServer"
}

• new_cron_job(string)(Required): Complete, raw cron job line string. Must not be empty/whitespace.

Success Response (`201 Created`):

Returned when cron job line successfully added.

{
    "status": "success",
    "message": "Cron job added successfully."
}

Error Responses:

• 400 Bad Request:
  • Invalid/missing JSON body.
  • Missing/invalid/empty new_cron_job field.
  • Invalid server_name.
• 401 Unauthorized:
  • Authentication missing or invalid.
• 403 Forbidden:
  • Request made on non-Linux OS.
• 500 Internal Server Error:
  • crontab command not found.
  • Reading/writing crontab failed (permissions, OS errors).
  • Unexpected error.

curl Example (Bash):

# Note: Ensure command path/server name in cron string are correct
CRON_LINE="0 4 * * * /usr/local/bin/bedrock-server-manager restart-server --server MyProdServer"
curl -X POST -H "Authorization: Bearer YOUR_JWT_TOKEN" -H "Content-Type: application/json" \
     -d "{\"new_cron_job\": \"$CRON_LINE\"}" \
     "http://<your-manager-host>:<port>/api/server/MyProdServer/cron_scheduler/add"

PowerShell Example:

# Note: Linux-only endpoint. Sends request assuming target is Linux.
$headers = @{ Authorization = 'Bearer YOUR_JWT_TOKEN'; 'Content-Type' = 'application/json' }
$cronLine = "0 4 * * * /usr/local/bin/bedrock-server-manager restart-server --server MyProdServer"
$body = @{ new_cron_job = $cronLine } | ConvertTo-Json
Invoke-RestMethod -Method Post -Uri "http://<your-manager-host>:<port>/api/server/MyProdServer/cron_scheduler/add" -Headers $headers -Body $body

POST /api/server/{server_name}/cron_scheduler/modify - Modify Cron Job (Linux Only)

Modifies an existing cron job by replacing the exact line matching old_cron_job with new_cron_job. Linux only.

This endpoint is exempt from CSRF protection but requires authentication.

Authentication:

Required (JWT or active Web UI session).

Platform:

Linux Only.

Path Parameters:

• server_name(string)(Required): Server context.

Request Body (application/json):

{
    "old_cron_job": "0 3 * * * /path/to/old_command --args",
    "new_cron_job": "0 4 * * * /path/to/new_command --newargs"
}

• old_cron_job(string)(Required): Exact, complete, existing cron line to find/replace.
• new_cron_job(string)(Required): New, complete cron line to replace with.

Success Response (`200 OK`):

Returned when replacement successful or if old/new identical.

{
    "status": "success",
    "message": "Cron job modified successfully."
}

or if no change:

{
    "status": "success",
    "message": "No modification needed, jobs are identical."
}

Error Responses:

• 400 Bad Request:
  • Invalid/missing JSON body.
  • Missing/invalid/empty old_cron_job or new_cron_job.
  • Invalid server_name.
• 401 Unauthorized:
  • Authentication missing or invalid.
• 403 Forbidden:
  • Request made on non-Linux OS.
• 404 Not Found:
  • Exact old_cron_job string not found in crontab.
• 500 Internal Server Error:
  • crontab command not found.
  • Reading/writing crontab failed (permissions, OS errors).
  • Unexpected error.

curl Example (Bash):

OLD_CRON="0 3 * * * /path/to/cmd --old"
NEW_CRON="0 4 * * * /path/to/cmd --new"
curl -X POST -H "Authorization: Bearer YOUR_JWT_TOKEN" -H "Content-Type: application/json" \
     -d "{\"old_cron_job\": \"$OLD_CRON\", \"new_cron_job\": \"$NEW_CRON\"}" \
     "http://<your-manager-host>:<port>/api/server/MyServer/cron_scheduler/modify"

PowerShell Example:

# Note: Linux-only endpoint.
$headers = @{ Authorization = 'Bearer YOUR_JWT_TOKEN'; 'Content-Type' = 'application/json' }
$oldCron = "0 3 * * * /path/to/cmd --old"
$newCron = "0 4 * * * /path/to/cmd --new"
$body = @{ old_cron_job = $oldCron; new_cron_job = $newCron } | ConvertTo-Json
Invoke-RestMethod -Method Post -Uri "http://<your-manager-host>:<port>/api/server/MyServer/cron_scheduler/modify" -Headers $headers -Body $body

DELETE /api/server/{server_name}/cron_scheduler/delete - Delete Cron Job (Linux Only)

Deletes a specific cron job line from the user's crontab by exact string match. Linux only.

This endpoint is exempt from CSRF protection but requires authentication.

Authentication:

Required (JWT or active Web UI session).

Platform:

Linux Only.

Path Parameters:

• server_name(string)(Required): Server context.

Query Parameters:

• cron_string(string)(Required): Exact, complete cron line to delete (URL-encoded).

Request Body:

None.

Success Response (`200 OK`):

Returned on completion, even if string wasn't found (idempotent).

{
    "status": "success",
    "message": "Cron job deleted successfully (if it existed)."
}

Error Responses:

• 400 Bad Request:
  • Missing/empty cron_string query parameter.
  • Invalid server_name.
• 401 Unauthorized:
  • Authentication missing or invalid.
• 403 Forbidden:
  • Request made on non-Linux OS.
• 500 Internal Server Error:
  • crontab command not found.
  • Reading/writing crontab failed (permissions, OS errors).
  • Unexpected error.

curl Example (Bash):

# URL Encode the cron string (example using Python)
CRON_STRING_URLENCODED=$(python3 -c 'import urllib.parse; print(urllib.parse.quote_plus("0 4 * * * /path/to/bedrock-server-manager backup-all --server MyProdServer"))')

curl -X DELETE -H "Authorization: Bearer YOUR_JWT_TOKEN" \
     "http://<your-manager-host>:<port>/api/server/MyServer/cron_scheduler/delete?cron_string=${CRON_STRING_URLENCODED}"

PowerShell Example:

# Note: Linux-only endpoint.
$headers = @{ Authorization = 'Bearer YOUR_JWT_TOKEN' }
$cronString = "0 4 * * * /path/to/bedrock-server-manager backup-all --server MyProdServer"
# Use appropriate URL encoding method
$encodedCronString = [System.Web.HttpUtility]::UrlEncode($cronString) # .NET Framework example
# $encodedCronString = [uri]::EscapeDataString($cronString) # PowerShell Core example
$uri = "http://<your-manager-host>:<port>/api/server/MyServer/cron_scheduler/delete?cron_string=$encodedCronString"
Invoke-RestMethod -Method Delete -Uri $uri -Headers $headers

POST /api/server/{server_name}/task_scheduler/add - Add Windows Task (Windows Only)

Creates a new scheduled task in Windows Task Scheduler to run a manager command. Generates/imports task XML. Windows only.

This endpoint is exempt from CSRF protection but requires authentication.

Authentication:

Required (JWT or active Web UI session).

Platform:

Windows Only.

Path Parameters:

• server_name(string)(Required): Server context for the task (used in command args and XML path).

Request Body (application/json):

{
    "command": "backup-all",
    "triggers": [
        {
            "type": "Daily",
            "start": "2024-01-16T03:00:00",
            "interval": 1
        },
        {
            "type": "Weekly",
            "start": "2024-01-20T05:00:00",
            "interval": 2,
            "days": ["Saturday", "Sunday"]
        }
    ]
}

• command(string)(Required): Manager command ("update-server", "backup-all", "start-server", "stop-server", "restart-server", "scan-players").
• triggers(list[object])(Required): Non-empty list of trigger definitions. Each needs:
  • type(string)(Required): Supported types (e.g., "Daily", "Weekly", "Monthly", "TimeTrigger", "LogonTrigger").
  • start(string)(Required for time-based): ISO 8601 format (e.g., YYYY-MM-DDTHH:MM:SS).
  • interval(integer)(Optional, default: 1): For Daily/Weekly.
  • days(list[string|integer])(Required for `Weekly`): Days ("Monday", "Mon", `1`).
  • months(list[string|integer])(Required for `Monthly`): Months ("January", "Jan", `1`).
  • days_of_month(list[string|integer])(Required for `Monthly`): Day numbers (1-31).

Success Response (`201 Created`):

Returned when task XML generated and imported successfully. Includes task name.

{
    "status": "success",
    "message": "Windows task '<generated_task_name>' created successfully.",
    "created_task_name": "bedrock_MyWinServer_backup-all_20240115_103000"
}

Error Responses:

• 400 Bad Request:
  • Invalid/missing JSON body.
  • Invalid/missing command.
  • Missing/empty/invalid triggers list or objects (type, start, days, etc.).
  • Invalid server_name.
• 401 Unauthorized:
  • Authentication missing or invalid.
• 403 Forbidden:
  • Request made on non-Windows OS.
• 500 Internal Server Error:
  • Configuration error (missing config dir, manager script path EXPATH).
  • Creating task XML file failed (permissions, disk full).
  • schtasks command not found.
  • Importing XML via schtasks /Create failed (access denied, invalid XML).
  • Unexpected error.

curl Example (Bash):

# Note: Windows-only endpoint.
curl -X POST -H "Authorization: Bearer YOUR_JWT_TOKEN" -H "Content-Type: application/json" \
     -d '{"command": "backup-all", "triggers": [{"type": "Daily", "start": "2024-01-16T02:30:00", "interval": 1}]}' \
     "http://<your-manager-host>:<port>/api/server/MyWinServer/task_scheduler/add"

PowerShell Example:

$headers = @{ Authorization = 'Bearer YOUR_JWT_TOKEN'; 'Content-Type' = 'application/json' }
$taskBody = @{
    command = 'backup-all'
    triggers = @(
        @{ type = 'Daily'; start = '2024-01-16T02:30:00'; interval = 1 }
    )
}
$bodyJson = $taskBody | ConvertTo-Json -Depth 3
# Expect error if manager host is not Windows
Invoke-RestMethod -Method Post -Uri "http://<your-manager-host>:<port>/api/server/MyWinServer/task_scheduler/add" -Headers $headers -Body $bodyJson

POST /api/server/{server_name}/task_scheduler/details - Get Windows Task Details (Windows Only)

Retrieves details (command, triggers) by parsing the task's associated XML config file. Windows only.

This endpoint is exempt from CSRF protection but requires authentication.

Authentication:

Required (JWT or active Web UI session).

Platform:

Windows Only.

Path Parameters:

• server_name(string)(Required): Server context to locate task XML.

Request Body (application/json):

{
    "task_name": "bedrock_MyWinServer_backup-all_..."
}

• task_name(string)(Required): Full name of the task whose details to retrieve.

Success Response (`200 OK`):

Returned when task XML found and parsed successfully.

{
    "status": "success",
    "task_details": {
        "command_path": "C:\\path\\to\\manager.exe",
        "command_args": "backup-all --server MyWinServer",
        "base_command": "backup-all",
        "triggers": [
            {
                "type": "Daily",
                "start": "2024-01-16T02:30:00",
                "interval": 1
            }
        ]
    }
}

• status: "success"
• task_details (*object*): Parsed details (command path, args, base command, triggers list).

Error Responses:

• 400 Bad Request:
  • Invalid/missing JSON body.
  • Missing/invalid task_name.
• 401 Unauthorized:
  • Authentication missing or invalid.
• 403 Forbidden:
  • Request made on non-Windows OS.
• 404 Not Found:
  • Task XML config file not found for the given name/server context.
• 500 Internal Server Error:
  • Configuration error (missing config dir).
  • Error parsing XML file (invalid XML, missing elements).
  • Unexpected error.

curl Example (Bash):

# Note: Windows-only endpoint.
TASK_NAME="bedrock_MyWinServer_backup-all_20240115103000"
curl -X POST -H "Authorization: Bearer YOUR_JWT_TOKEN" -H "Content-Type: application/json" \
     -d "{\"task_name\": \"$TASK_NAME\"}" \
     "http://<your-manager-host>:<port>/api/server/MyWinServer/task_scheduler/details"

PowerShell Example:

$headers = @{ Authorization = 'Bearer YOUR_JWT_TOKEN'; 'Content-Type' = 'application/json' }
$taskName = "bedrock_MyWinServer_backup-all_20240115103000"
$body = @{ task_name = $taskName } | ConvertTo-Json
Invoke-RestMethod -Method Post -Uri "http://<your-manager-host>:<port>/api/server/MyWinServer/task_scheduler/details" -Headers $headers -Body $body

PUT /api/server/{server_name}/task_scheduler/task/{task_name} - Modify Windows Task (Windows Only)

Modifies an existing Windows task by deleting the old task (task_name) and creating a new one with details from the request body. The new task gets a new timestamped name. Windows only.

This endpoint is exempt from CSRF protection but requires authentication.

Authentication:

Required (JWT or active Web UI session).

Platform:

Windows Only.

Path Parameters:

• server_name(string)(Required): Server context.
• task_name(string)(Required): Current full name of the task to replace (URL encode if needed).

Request Body (application/json):

Same structure as "Add Windows Task", defining the new command and triggers.

{
    "command": "restart-server",
    "triggers": [ { "type": "Weekly", "start": "...", "days": ["Saturday"] } ]
}

Success Response (`200 OK`):

Returned when old task deleted (or not found) and new task created successfully. Includes the new task name.

{
    "status": "success",
    "message": "Windows task modified successfully.", // Simple message from API
    "new_task_name": "bedrock_MyWinServer_restart-server_20240116_090000" // Added by route handler
}

Error Responses:

• 400 Bad Request:
  • Missing task_name in URL path (Flask 404).
  • Invalid/missing JSON body.
  • Validation of *new* command/triggers failed (see Add Task errors).
• 401 Unauthorized:
  • Authentication missing or invalid.
• 403 Forbidden:
  • Request made on non-Windows OS.
• 500 Internal Server Error:
  • Deleting *old* task failed (access denied).
  • Creating or importing *new* task failed (config errors, XML errors, schtasks errors - see Add Task errors).
  • Unexpected error during delete or create.

curl Example (Bash):

# Note: Windows-only endpoint.
OLD_TASK_NAME="bedrock_MyWinServer_backup-all_..."
# URL Encode if needed
ENCODED_OLD_TASK_NAME=$(python3 -c 'import urllib.parse; print(urllib.parse.quote("'$OLD_TASK_NAME'"))')

curl -X PUT -H "Authorization: Bearer YOUR_JWT_TOKEN" -H "Content-Type: application/json" \
     -d '{"command": "restart-server", "triggers": [{"type": "Weekly", "start": "2024-01-20T05:00:00", "days": ["Saturday"]}]}' \
     "http://<your-manager-host>:<port>/api/server/MyWinServer/task_scheduler/task/${ENCODED_OLD_TASK_NAME}"

PowerShell Example:

$headers = @{ Authorization = 'Bearer YOUR_JWT_TOKEN'; 'Content-Type' = 'application/json' }
$oldTaskName = "bedrock_MyWinServer_backup-all_..."
# URL encode the task name for the URI
$encodedOldTaskName = [uri]::EscapeDataString($oldTaskName) # PS Core encoding

$newTaskBody = @{
    command = 'restart-server'
    triggers = @(
        @{ type = 'Weekly'; start = '2024-01-20T05:00:00'; days = @('Saturday') }
    )
}
$bodyJson = $newTaskBody | ConvertTo-Json -Depth 3
$uri = "http://<your-manager-host>:<port>/api/server/MyWinServer/task_scheduler/task/$encodedOldTaskName"
Invoke-RestMethod -Method Put -Uri $uri -Headers $headers -Body $bodyJson

DELETE /api/server/{server_name}/task_scheduler/task/{task_name} - Delete Windows Task (Windows Only)

Deletes an existing Windows task using schtasks.exe /Delete and attempts to delete its XML config file. Windows only.

This endpoint is exempt from CSRF protection but requires authentication.

Authentication:

Required (JWT or active Web UI session).

Platform:

Windows Only.

Path Parameters:

• server_name(string)(Required): Server context for locating XML file.
• task_name(string)(Required): Full name of task to delete (URL encode if needed).

Request Body:

None.

Success Response (`200 OK`):

Returned when task deleted from scheduler (or already gone) and XML file deleted (or not found).

{
    "status": "success",
    "message": "Task '<task_name>' and its definition file deleted successfully."
}

Error Responses:

• 400 Bad Request:
  • Missing task_name in URL path (Flask 404).
• 401 Unauthorized:
  • Authentication missing or invalid.
• 403 Forbidden:
  • Request made on non-Windows OS.
• 500 Internal Server Error:
  • Configuration error (missing config dir).
  • Deleting task via schtasks /Delete failed (access denied).
  • Deleting task XML config file failed (permissions).
  • schtasks command not found.
  • Unexpected error.
  *(Note: Response aggregates errors if both deletions have issues.)*

curl Example (Bash):

# Note: Windows-only endpoint.
TASK_NAME="bedrock_MyWinServer_backup-all_..."
# URL Encode if needed
ENCODED_TASK_NAME=$(python3 -c 'import urllib.parse; print(urllib.parse.quote("'$TASK_NAME'"))')
curl -X DELETE -H "Authorization: Bearer YOUR_JWT_TOKEN" \
     "http://<your-manager-host>:<port>/api/server/MyWinServer/task_scheduler/task/${ENCODED_TASK_NAME}"

PowerShell Example:

$headers = @{ Authorization = 'Bearer YOUR_JWT_TOKEN' }
$taskName = "bedrock_MyWinServer_backup-all_..."
# URL encode the task name for the URI
$encodedTaskName = [uri]::EscapeDataString($taskName) # PS Core encoding
$uri = "http://<your-manager-host>:<port>/api/server/MyWinServer/task_scheduler/task/$encodedTaskName"
Invoke-RestMethod -Method Delete -Uri $uri -Headers $headers