Introduction

Base URL:

All endpoint paths are relative to the base URL where the manager's web server is running. Replace http://: 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:

Success: Typically returns HTTP status 200 OK, 201 Created with a JSON body like:
```
{
    "status": "success",
    "message": "Operation completed successfully.",
    "data_key": "optional_data"
}
```
(Specific data_key names vary by endpoint)
Error: Typically returns HTTP status 4xx (Client Error) or 5xx (Server Error) with a JSON body like:
```
{
    "status": "error",
    "message": "A description of the error.",
    "errors": { // Optional: Field-specific validation errors
        "field_name": "Specific error for this field."
    }
}
```
Common error codes:
- 400 Bad Request: Invalid input, missing parameters, validation failed, invalid format (e.g., not JSON).
- 401 Unauthorized: Authentication token missing or invalid (for JWT protected routes).
- 403 Forbidden: Authenticated user lacks permission (or OS mismatch for platform-specific endpoints like scheduling).
- 404 Not Found: Server, task, file, or endpoint not found.
- 500 Internal Server Error: An unexpected error occurred on the server during processing (e.g., file operation failure, configuration issue).
- 501 Not Implemented: Feature not supported on the current OS (e.g., sending commands on Windows).

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:

Uses Flask's @app.before_request decorator.
Runs on every request received by the application.

Targeted URLs:

The validation logic specifically targets URL paths that contain the pattern /server//, where is a segment in the path.
Examples: /server/MyServer/status_info, /api/server/AnotherServer/stop.

Bypassed URLs:

Paths related to server creation are excluded. Currently bypassed paths start with:
/server/install
/api/server/install

Validation Process:

If the path matches the target pattern (and isn't bypassed), is extracted.
The internal function validate_server_exist is called.
The result determines the outcome.

Outcomes:

Success: Request proceeds normally.
Failure (Server Not Found):
- API Requests (/api/...): Aborted with 404 Not Found.
```
{ "status": "error", "message": "Server '' not found." }
```
- Web UI Requests: Redirected to dashboard (/) with a flash message.

Internal Validation Error: Aborted with 500 Internal Server Error.

{ "status": "error", "message": "Internal server error during server validation." }

No Match / Bypassed: Validation skipped.

Implications for API Users:

Requests to /api/server//... for a non-existent server will get an immediate 404.
Ensure server_name corresponds to a valid, existing server.

Authentication

POST `/api/login`

Authenticates using username/password and returns a JWT.

Authentication:

None.

Request Body (`application/json`):

{
    "username": "your_username",
    "password": "your_plain_text_password"
}

username(string)(Required)
password(string)(Required)

Success Response (`200 OK`):

{ "access_token": "YOUR_JWT_TOKEN" }

Server Information

GET `/api/servers`

Lists all detected server instances with configured status/version.

Authentication:

Required.

Success Response (`200 OK`):

{
    "status": "success",
    "servers": [
        { "name": "server1", "status": "RUNNING", "version": "1.20.81.01" },
        { "name": "server2", "status": "STOPPED", "version": "1.20.73.02" }
        // ...
    ]
}

(May include an optional message field if errors occurred reading some server configs.)

GET `/api/server/{server_name}/world_name`

Gets the level-name from server.properties.

Authentication:

Required.

Path Parameters:

server_name(string)(Required)

Success Response (`200 OK`):

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

GET `/api/server/{server_name}/running_status`

Checks if the server process is running.

Authentication:

Required.

Path Parameters:

server_name(string)(Required)

Success Response (`200 OK`):

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

GET `/api/server/{server_name}/config_status`

Gets status stored in manager's config file for the server.

Authentication:

Required.

Path Parameters:

server_name(string)(Required)

Success Response (`200 OK`):

{ "status": "success", "config_status": "Installed | Stopped | Running | ..." }

GET `/api/server/{server_name}/version`

Gets installed version stored in manager's config file.

Authentication:

Required.

Path Parameters:

server_name(string)(Required)

Success Response (`200 OK`):

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

GET `/api/server/{server_name}/validate`

Checks if server directory and executable exist.

Authentication:

Required.

Path Parameters:

server_name(string)(Required)

Responses:

200 OK: Server exists.

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

404 Not Found: Directory or executable missing.

{"status": "error", "message": "Server directory '...' not found."}

GET `/api/server/{server_name}/status_info`

Gets runtime process info (PID, CPU, Mem, Uptime) if running.

Note: CPU % is relative to previous check (first check is 0%).

Authentication:

Required.

Path Parameters:

server_name(string)(Required)

Success Response (`200 OK`):

If running:

{
    "status": "success",
    "process_info": { "pid": ..., "cpu_percent": ..., "memory_mb": ..., "uptime": "..." }
}

If not running:

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

Server Actions

POST `/api/server/{server_name}/start`

Starts the specified server instance.

Authentication:

Required.

Path Parameters:

server_name(string)(Required)

Success Response (`200 OK`):

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

POST `/api/server/{server_name}/stop`

Stops the specified server instance (graceful if possible).

Authentication:

Required.

Path Parameters:

server_name(string)(Required)

Success Response (`200 OK`):

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

or

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

POST `/api/server/{server_name}/restart`

Restarts the server (stops if running, then starts).

Authentication:

Required.

Path Parameters:

server_name(string)(Required)

Success Response (`200 OK`):

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

or

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

POST `/api/server/{server_name}/send_command`

Sends command to running server console (Linux: screen, Windows: Named Pipes).

Authentication:

Required.

Path Parameters:

server_name(string)(Required)

Request Body (`application/json`):

{ "command": "your server command" }

command(string)(Required)

Success Response (`200 OK`):

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

POST `/api/server/{server_name}/update`

Checks for and installs latest/preview/specific version based on server config.

Authentication:

Required.

Path Parameters:

server_name(string)(Required)

Success Response (`200 OK`):

If updated:

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

If up-to-date:

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

DELETE `/api/server/{server_name}/delete`

Irreversibly deletes server instance (installation, config, backups).

Authentication:

Required.

Path Parameters:

server_name(string)(Required)

Success Response (`200 OK`):

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

Backup & Restore

POST `/api/server/{server_name}/backups/prune`

Deletes old backups, keeping specified number.

Authentication:

Required.

Path Parameters:

server_name(string)(Required)

Request Body (`application/json`, optional):

{ "keep": number }

keep(integer)(Optional): Defaults to `BACKUP_KEEP` setting.

Success Response (`200 OK`):

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

POST `/api/server/{server_name}/backup/action`

Triggers a backup (world, config file, or all).

Authentication:

Required.

Path Parameters:

server_name(string)(Required)

Request Body (`application/json`):

```
{"backup_type": "world"}
```

{"backup_type": "config", "file_to_backup": "relative/path/file.json"}

```
{"backup_type": "all"}
```

backup_type(string)(Required)
file_to_backup(string)(Required if `type` is `config`)

Success Response (`200 OK`):

{"status": "success", "message": "... backup completed successfully ..."}

POST `/api/server/{server_name}/restore/action`

Overwrites current files to restore world or config from specific backup.

Authentication:

Required.

Path Parameters:

server_name(string)(Required)

Request Body (`application/json`):

{"restore_type": "world", "backup_file": "/full/path/to/backup.mcworld"}

{"restore_type": "config", "backup_file": "/full/path/to/config_backup.json"}

restore_type(string)(Required): `"world"` or `"config"`.
backup_file(string)(Required): Full path (must be within `BACKUP_DIR`).

Success Response (`200 OK`):

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

POST `/api/server/{server_name}/restore/all`

Overwrites current files to restore world and standard configs from *latest* backups.

Authentication:

Required.

Path Parameters:

server_name(string)(Required)

Success Response (`200 OK`):

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

World & Addon Management

POST `/api/server/{server_name}/world/export`

Exports the server's current world to a .mcworld file in the content/worlds directory.

Authentication:

Required.

Path Parameters:

server_name(string)(Required)

Success Response (`200 OK`):

{
            "status": "success",
            "message": "World for server '...' exported successfully as '....mcworld'.",
            "export_file": "/full/path/to/content/worlds/....mcworld"
        }

POST `/api/server/{server_name}/world/install`

Overwrites current world to install .mcworld from content/worlds dir.

Authentication:

Required.

Path Parameters:

server_name(string)(Required)

Request Body (`application/json`):

{ "filename": "relative/path/to/world.mcworld" }

filename(string)(Required): Path relative to `content/worlds`.

Success Response (`200 OK`):

{"status": "success", "message": "World '...' installed successfully for server '...'."}

POST `/api/server/{server_name}/addon/install`

Installs .mcpack/.mcaddon from content/addons dir into server's world.

Authentication:

Required.

Path Parameters:

server_name(string)(Required)

Request Body (`application/json`):

{ "filename": "relative/path/to/addon.mcpack" }

filename(string)(Required): Path relative to `content/addons`.

Success Response (`200 OK`):

{"status": "success", "message": "Addon '...' installed successfully for server '...'."}

Player Management

POST `/api/players/scan`

Scans all server logs for player connections, updates central players.json.

Authentication:

Required.

Success Response (`200 OK`):

{ "status": "success", "players_found": true|false, "message": "Player scan completed..." }

GET `/api/server/{server_name}/allowlist`

Gets content of server's allowlist.json.

Authentication:

Required.

Path Parameters:

server_name(string)(Required)

Success Response (`200 OK`):

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

POST `/api/server/{server_name}/allowlist/add`

Adds players to allowlist.json (does not remove existing).

Authentication:

Required.

Path Parameters:

server_name(string)(Required)

Request Body (`application/json`):

{
    "players": ["Player1", "Player2"],
    "ignoresPlayerLimit": false | true
}

players(list[string])(Required)
ignoresPlayerLimit(boolean)(Optional, default: false)

Success Response (`200 OK`):

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

or

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

DELETE `/api/server/{server_name}/allowlist/player/{player_name}`

Removes a player (case-insensitive) from the server's allowlist.json file.

Authentication:

Required.

Path Parameters:

server_name(string)(Required)
player_name(string)(Required): The player name to remove.

Success Response (`200 OK`):

{
            "status": "success",
            "message": "Player '...' removed successfully..."
        }

Or if player not found:

{
            "status": "success",
            "message": "Player '...' not found in the allowlist..."
        }

PUT `/api/server/{server_name}/permissions`

Updates player permission levels in permissions.json.

Authentication:

Required.

Path Parameters:

server_name(string)(Required)

Request Body (`application/json`):

{
    "permissions": {
        "XUID_string": "visitor | member | operator",
        ...
    }
}

permissions(object)(Required): Map of XUIDs (string) to levels (string).

Success Response (`200 OK`):

{"status": "success", "message": "Permissions updated successfully for X player(s) ..."}

or

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

Configuration

POST `/api/server/{server_name}/properties`

Updates specified allowed keys in server.properties.

Authentication:

Required.

Path Parameters:

server_name(string)(Required)

Request Body (`application/json`):

{ "property-key": "new-value", ... }

See full docs for list of allowed keys.

Success Response (`200 OK`):

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

POST `/api/server/{server_name}/service`

Configures OS-specific service settings (Linux: systemd; Windows: config flag).

Authentication:

Required.

Path Parameters:

server_name(string)(Required)

Request Body (`application/json`):

Linux:

{ "autoupdate": boolean, "autostart": boolean }

Windows:
```
{ "autoupdate": boolean }
```

autoupdate(boolean)(Required)
autostart(boolean)(Required, Linux only)

Success Response (`200 OK`):

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

(Linux Example)

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

(Windows Example)

Downloads

POST `/api/downloads/prune`

Deletes old downloaded server archives from specified directory.

Authentication:

Required.

Request Body (`application/json`):

{
    "directory": "/absolute/path/to/cache",
    "keep": number
}

directory(string)(Required)
keep(integer)(Optional): Defaults to `DOWNLOAD_KEEP` setting.

Success Response (`200 OK`):

{"status": "success", "message": "Download cache pruned successfully for '...'."}

Server Installation

POST `/api/server/install`

Installs new server instance. Requires confirmation if server name exists and `overwrite` is false.

Authentication:

Required.

Request Body (`application/json`):

{
    "server_name": "NewServer",
    "server_version": "LATEST | PREVIEW | 1.x.y.z",
    "overwrite": false | true
}

server_name(string)(Required)
server_version(string)(Required)
overwrite(boolean)(Optional, default: false)

Success Responses:

201 Created (New/Overwrite):

{
    "status": "success", "server_name": "...", "version": "...", "message": "...", "next_step_url": "..."
}

200 OK (Confirmation Needed):

{
    "status": "confirm_needed", "message": "Server '...' already exists...", "server_name": "...", "server_version": "..."
}

Task Scheduler (OS Specific)

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

{# --- Linux Cron Endpoints --- #}

Linux (Cron)

POST `/api/server/{server_name}/cron_scheduler/add` (Linux Only)

Adds raw cron job line for manager's user.

Authentication:

Required.

Platform:

Linux Only.

Path Parameters:

server_name(string)(Required)

Request Body (`application/json`):

{ "new_cron_job": "0 3 * * * /path/to/cmd --args" }

new_cron_job(string)(Required)

Success Response (`201 Created`):

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

POST `/api/server/{server_name}/cron_scheduler/modify` (Linux Only)

Replaces existing cron job line by exact match.

Authentication:

Required.

Platform:

Linux Only.

Path Parameters:

server_name(string)(Required)

Request Body (`application/json`):

{
    "old_cron_job": "exact old string",
    "new_cron_job": "replacement string"
}

old_cron_job(string)(Required)
new_cron_job(string)(Required)

Success Response (`200 OK`):

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

or

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

DELETE `/api/server/{server_name}/cron_scheduler/delete` (Linux Only)

Deletes cron job line by exact match.

Authentication:

Required.

Platform:

Linux Only.

Path Parameters:

server_name(string)(Required)

Query Parameters:

cron_string(string)(Required): URL-encoded exact string of job to delete.

Success Response (`200 OK`):

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

{# --- Windows Task Scheduler Endpoints --- #}

Windows (Task Scheduler)

POST `/api/server/{server_name}/task_scheduler/add` (Windows Only)

Creates new Windows scheduled task.

Authentication:

Required.

Platform:

Windows Only.

Path Parameters:

server_name(string)(Required)

Request Body (`application/json`):

{
    "command": "backup-all | update-server | ...",
    "triggers": [ { "type": "Daily|Weekly|...", "start": "ISO8601", ... } ]
}

command(string)(Required): See full docs for list.
triggers(list[object])(Required): See full docs for trigger structure.

Success Response (`201 Created`):

{
    "status": "success",
    "message": "Windows task '...' created successfully.",
    "created_task_name": "..."
}

POST `/api/server/{server_name}/task_scheduler/details` (Windows Only)

Gets details by parsing task's stored XML file.

Authentication:

Required.

Platform:

Windows Only.

Path Parameters:

server_name(string)(Required)

Request Body (`application/json`):

{ "task_name": "full_task_name" }

task_name(string)(Required)

Success Response (`200 OK`):

{
    "status": "success",
    "task_details": { "command_path": "...", "command_args": "...", "base_command": "...", "triggers": [...] }
}

PUT `/api/server/{server_name}/task_scheduler/task/{task_name}` (Windows Only)

Modifies task by deleting old (task_name) and creating new based on body.

Authentication:

Required.

Platform:

Windows Only.

Path Parameters:

server_name(string)(Required)
task_name(string)(Required): Task to replace (URL encode if needed).

Request Body (`application/json`):

Same as "Add Windows Task" body, defining the new task.

Success Response (`200 OK`):

{
    "status": "success",
    "message": "Windows task modified successfully.",
    "new_task_name": "..."
}

DELETE `/api/server/{server_name}/task_scheduler/task/{task_name}` (Windows Only)

Deletes Windows task and its associated XML file.

Authentication:

Required.

Platform:

Windows Only.

Path Parameters:

server_name(string)(Required)
task_name(string)(Required): Task to delete (URL encode if needed).

Success Response (`200 OK`):

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

Bedrock Server Manager - HTTP API Quick Reference

Introduction

Base URL:

Authentication:

Content-Type:

Standard Responses:

Global Server Validation (Request Pre-Processing)

Mechanism:

Targeted URLs:

Bypassed URLs:

Validation Process:

Outcomes:

Implications for API Users:

Authentication

POST /api/login

Authentication:

Request Body (application/json):

Success Response (`200 OK`):

Server Information

GET /api/servers

Authentication:

Success Response (`200 OK`):

GET /api/server/{server_name}/world_name

Authentication:

Path Parameters:

Success Response (`200 OK`):

GET /api/server/{server_name}/running_status

Authentication:

Path Parameters:

Success Response (`200 OK`):

GET /api/server/{server_name}/config_status

Authentication:

Path Parameters:

Success Response (`200 OK`):

GET /api/server/{server_name}/version

Authentication:

Path Parameters:

Success Response (`200 OK`):

GET /api/server/{server_name}/validate

Authentication:

Path Parameters:

Responses:

GET /api/server/{server_name}/status_info

Authentication:

Path Parameters:

Success Response (`200 OK`):

Server Actions

POST /api/server/{server_name}/start

Authentication:

Path Parameters:

Success Response (`200 OK`):

POST /api/server/{server_name}/stop

Authentication:

Path Parameters:

Success Response (`200 OK`):

POST /api/server/{server_name}/restart

Authentication:

Path Parameters:

Success Response (`200 OK`):

POST /api/server/{server_name}/send_command

Authentication:

Path Parameters:

Request Body (application/json):

Success Response (`200 OK`):

POST /api/server/{server_name}/update

Authentication:

Path Parameters:

Success Response (`200 OK`):

DELETE /api/server/{server_name}/delete

Authentication:

Path Parameters:

Success Response (`200 OK`):

Backup & Restore

POST /api/server/{server_name}/backups/prune

Authentication:

Path Parameters:

Request Body (application/json, optional):

Success Response (`200 OK`):

POST /api/server/{server_name}/backup/action

Authentication:

POST `/api/login`

Request Body (`application/json`):

GET `/api/servers`

GET `/api/server/{server_name}/world_name`

GET `/api/server/{server_name}/running_status`

GET `/api/server/{server_name}/config_status`

GET `/api/server/{server_name}/version`

GET `/api/server/{server_name}/validate`

GET `/api/server/{server_name}/status_info`

POST `/api/server/{server_name}/start`

POST `/api/server/{server_name}/stop`

POST `/api/server/{server_name}/restart`

POST `/api/server/{server_name}/send_command`

Request Body (`application/json`):

POST `/api/server/{server_name}/update`

DELETE `/api/server/{server_name}/delete`

POST `/api/server/{server_name}/backups/prune`

Request Body (`application/json`, optional):

POST `/api/server/{server_name}/backup/action`

Request Body (`application/json`):

POST `/api/server/{server_name}/restore/action`

Request Body (`application/json`):

POST `/api/server/{server_name}/restore/all`

POST `/api/server/{server_name}/world/export`

POST `/api/server/{server_name}/world/install`

Request Body (`application/json`):

POST `/api/server/{server_name}/addon/install`

Request Body (`application/json`):

POST `/api/players/scan`

GET `/api/server/{server_name}/allowlist`

POST `/api/server/{server_name}/allowlist/add`

Request Body (`application/json`):

DELETE `/api/server/{server_name}/allowlist/player/{player_name}`

PUT `/api/server/{server_name}/permissions`

Request Body (`application/json`):

POST `/api/server/{server_name}/properties`

Request Body (`application/json`):

POST `/api/server/{server_name}/service`

Request Body (`application/json`):

POST `/api/downloads/prune`

Request Body (`application/json`):

POST `/api/server/install`

Request Body (`application/json`):