{% extends "base.html" %} {# --- Page Title --- #} {% block title %}API Documentation - {{ super() }}{% endblock %} {# --- Specific Styles for API Docs --- #} {% block head_styles %} {# Add specific styles for API docs elements on top of base CSS #} {% endblock %} {# --- Main Content Area --- #} {% block content %}

Bedrock Server Manager - HTTP API Documentation

{# --- Link back to the Documentation Index --- #}

This document outlines the available HTTP API endpoints for interacting with the Bedrock Server Manager.

{# --- Introduction Section (copied from MD) --- #}

Base URL:

All endpoint paths are relative to the base URL where the manager's web server is running. Replace http://<your-manager-host>:<port> with the actual address. The default port is 11325 (configurable via the WEB_PORT setting).

Authentication:

Most API endpoints require authentication. This is done by providing a JSON Web Token (JWT) obtained from the /api/login endpoint. Include the token in the Authorization header as a Bearer token:

Authorization: Bearer YOUR_JWT_TOKEN

The token expiration duration is configurable via the TOKEN_EXPIRES_WEEKS setting, defaulting to 4 weeks.

Content-Type:

For requests that include data in the body (POST, PUT), the Content-Type header should be set to application/json. Responses from the API will typically have a Content-Type of application/json.

Standard Responses:

{# --- Global Server Validation Section --- #}

Global Server Validation (Request Pre-Processing)

To enhance robustness and provide immediate feedback, the application implements a global pre-request validation check. This check runs before the actual route handler for most requests involving a specific server instance.

Mechanism:

Targeted URLs:

Bypassed URLs:

Validation Process:

  1. If the request path matches the target pattern (and is not bypassed), the <server_name> segment is extracted.
  2. The internal function validate_server_exist (which checks for the existence of the server's directory and executable) is called with the extracted server_name.
  3. The result of validate_server_exist determines the outcome.

Outcomes:

Implications for API Users:

{# --- Authentication Section --- #}

Authentication

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

Success Response (`200 OK`):

Returns a JSON object containing the JWT access token.

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

Error Responses:

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'
{# --- Server Information Section --- #}

Server Information

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:

Request Body:

None.

Success Response (`200 OK`):

Returns the world name if found successfully.

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

Error Responses:

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:

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
}

Error Responses:

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:

Request Body:

None.

Success Response (`200 OK`):

Returns the status string from the configuration file.

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

Error Responses:

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:

Request Body:

None.

Success Response (`200 OK`):

Returns the installed version string from the configuration file.

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

Error Responses:

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:

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:

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:

Request Body:

None.

Success Response (`200 OK`):

Returned regardless of whether the server is running or not.

Error Responses:

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
{# --- Server Actions Section --- #}

Server Actions

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:

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:

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:

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:

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:

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:

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:

Request Body (application/json):

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

Success Response (`200 OK`):

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

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

Error Responses:

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:

Request Body:

None.

Success Response (`200 OK`):

Returned when the update check/process completes.

Error Responses:

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:

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:

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
{# --- Backup & Restore Section --- #}

Backup & Restore

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:

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

Error Responses:

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:

Query Parameters:

None.

Request Body (application/json, optional):

{
    "keep": 10
}

Success Response (`200 OK`):

Returned when pruning completes or if no backups found.

Error Responses:

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:

Request Body (application/json):

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:

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:

Request Body (application/json):

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

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:

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:

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:

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
{# --- Content Management Section --- #}

World & Addon Management

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:

Request Body (application/json):

{
    "filename": "MyCoolWorld.mcworld"
}
or (with subdirectories):
{
    "filename": "user_uploads/MyCoolWorld.mcworld"
}

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:

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:

Request Body (application/json):

{
    "filename": "CoolBehaviorPack.mcpack"
}
or
{
    "filename": "collections/AwesomeAddonCollection.mcaddon"
}

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:

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
{# --- Player Management Section --- #}

Player Management

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.

Error Responses:

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:

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

Error Responses:

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:

Request Body (application/json):

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

Success Response (`200 OK`):

Returned on completion, even if no new players added.

Error Responses:

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:

Request Body (application/json):

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

Success Response (`200 OK`):

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

Error Responses:

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
{# --- Configuration Section --- #}

Configuration

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:

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:

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:

Request Body (application/json):

Success Response (`200 OK`):

Returned when OS-specific configuration applied.

Error Responses:

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
{# --- Downloads Section --- #}

Downloads

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
}

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:

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
{# --- Server Installation Section --- #}

Server Installation

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
}

Success Responses:

Error Responses:

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
{# --- Scheduled Tasks Section --- #}

Task Scheduler (OS Specific)

Note: These endpoints interact with Linux cron or Windows Task Scheduler based on the host OS.

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:

Request Body (application/json):

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

Success Response (`201 Created`):

Returned when cron job line successfully added.

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

Error Responses:

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:

Request Body (application/json):

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

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:

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:

Query Parameters:

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:

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:

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

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:

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:

Request Body (application/json):

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

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

Error Responses:

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:

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:

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:

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:

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
{# --- End Scheduled Tasks Section --- #} {# --- Optional: Back link at the bottom --- #} {#
#} {# Using border-bottom on section instead #} {% endblock %} {# --- Page Specific Scripts --- #} {% block body_scripts %} {# Add any JS needed specifically for this page, if any #} {% endblock %}