This document provides a concise overview of the HTTP API endpoints for interacting with the Bedrock Server Manager.
{# --- Table of Contents --- #} {# --- Introduction Section (copied from MD) --- #}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).
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_TOKENThe token expiration duration is configurable via the TOKEN_EXPIRES_WEEKS setting, defaulting to 4 weeks.
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.
200 OK, 201 Created with a JSON body like:
{
"status": "success",
"message": "Operation completed successfully.",
"data_key": "optional_data"
}data_key names vary by endpoint)
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."
}
}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).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.
@app.before_request decorator./server// , where /server/MyServer/process_info, /api/server/AnotherServer/stop./server/install/api/server/installvalidate_server_exist is called./api/...): Aborted with 404 Not Found.
{ "status": "error", "message": "Server '' not found." } /) with a flash message.500 Internal Server Error.
{ "status": "error", "message": "Internal server error during server validation." }/api/server//... for a non-existent server will get an immediate 404.server_name corresponds to a valid, existing server./api/loginAuthenticates using username/password and returns a JWT.
None.
application/json):{
"username": "your_username",
"password": "your_plain_text_password"
}username(string)(Required)password(string)(Required){ "access_token": "YOUR_JWT_TOKEN" }/api/infoRetrieves the operating system type and the current application version.
None.
{
"status": "success",
"data": {
"os_type": "Linux", // Or "Windows"
"app_version": "3.2.1" // Application version
}
}(Error responses like 500 Internal Server Error can occur if an internal issue arises.)
/api/serversLists all detected server instances with configured status/version.
Required.
{
"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.)
/api/server/{server_name}/world_nameGets the level-name from server.properties.
Required.
server_name(string)(Required){ "status": "success", "world_name": "Bedrock level" }/api/server/{server_name}/running_statusChecks if the server process is running.
Required.
server_name(string)(Required){ "status": "success", "is_running": true | false }/api/server/{server_name}/config_statusGets status stored in manager's config file for the server.
Required.
server_name(string)(Required){ "status": "success", "config_status": "Installed | Stopped | Running | ..." }/api/server/{server_name}/versionGets installed version stored in manager's config file.
Required.
server_name(string)(Required){ "status": "success", "installed_version": "1.20.81.01 | UNKNOWN" }/api/server/{server_name}/validateChecks if server directory and executable exist.
Required.
server_name(string)(Required)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."}/api/server/{server_name}/process_infoGets runtime process info (PID, CPU, Mem, Uptime) if running.
Note: CPU % is relative to previous check (first check is 0%).
Required.
server_name(string)(Required){
"status": "success",
"process_info": { "pid": ..., "cpu_percent": ..., "memory_mb": ..., "uptime": "..." }
}{
"status": "success", "process_info": null, "message": "Server '...' is not running."
}/api/server//permissions_data Retrieves player permissions from the server's permissions.json, optionally enriching with names from global players.json.
Path Parameter: server_name (string, required).
Query Parameters: base_dir (optional), config_dir (optional for name lookup).
Required.
{
"status": "success",
"data": {
"permissions": [
{ "xuid": "...", "name": "...", "permission_level": "..." }
// ... more players with permissions
]
},
"message": "Optional contextual message (e.g., 'Server permissions file not found.')"
}(If server's permissions.json is not found/empty, the permissions list will be empty. Error responses like 400, 401, 404, or 500 can occur.)
/api/server/{server_name}/startStarts the specified server instance.
Required.
server_name(string)(Required){"status": "success", "message": "Server '...' started successfully."}/api/server/{server_name}/stopStops the specified server instance (graceful if possible).
Required.
server_name(string)(Required){"status": "success", "message": "Server '...' stopped successfully."}{"status": "success", "message": "Server '...' was already stopped."}/api/server/{server_name}/restartRestarts the server (stops if running, then starts).
Required.
server_name(string)(Required){"status": "success", "message": "Server '...' restarted successfully."}{"status": "success", "message": "Server '...' was not running and was started."}/api/server/{server_name}/send_commandSends command to running server console (Linux: screen, Windows: Named Pipes).
Required.
server_name(string)(Required)application/json):{ "command": "your server command" }command(string)(Required){"status": "success", "message": "Command '...' sent successfully."}/api/server/{server_name}/updateChecks for and installs latest/preview/specific version based on server config.
Required.
server_name(string)(Required){"status": "success", "updated": true, "new_version": "...", "message": "Server '...' update process completed. New version: ..." }{"status": "success", "updated": false, "new_version": "...", "message": "Server is already up-to-date." }/api/server/{server_name}/deleteIrreversibly deletes server instance (installation, config, backups).
Required.
server_name(string)(Required){"status": "success", "message": "All data for server '...' deleted successfully."}/api/server/{server_name}/backups/pruneDeletes old backups, keeping specified number.
Required.
server_name(string)(Required)application/json, optional):{ "keep": number }keep(integer)(Optional): Defaults to `BACKUP_KEEP` setting.{"status": "success", "message": "Backup pruning completed for server '...'."}/api/server//backups/list/ Lists available backup **filenames (basenames only)** for a server and backup type ("world" or "config").
Path Parameters: server_name (required), backup_type (required: "world" or "config").
Required.
{
"status": "success",
"backups": [
"backup_file1.mcworld",
"backup_file2.mcworld"
// ... (empty list if no backups)
]
}(Error responses like 400 Bad Request, 401 Unauthorized, or 500 Internal Server Error can occur.)
/api/server/{server_name}/backup/actionTriggers a backup (world, config file, or all).
Required.
server_name(string)(Required)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`){"status": "success", "message": "... backup completed successfully ..."}/api/server/{server_name}/restore/actionOverwrites current files to restore world or config from specific backup.
Required.
server_name(string)(Required)application/json):{"restore_type": "world", "backup_file": "backup.mcworld"}{"restore_type": "config", "backup_file": "config_backup.json"}restore_type(string)(Required): `"world"` or `"config"`.backup_file(string)(Required): Relative path to the backup file inside `BACKUP_DIR`/{server_name}.{"status": "success", "message": "Restoration from '...' (type: ...) completed successfully."}/api/server/{server_name}/restore/allOverwrites current files to restore world and standard configs from *latest* backups.
Required.
server_name(string)(Required){"status": "success", "message": "Restore all completed successfully for server '...'."}/api/content/worldsLists available world **filenames (basenames only)** from CONTENT_DIR/worlds (typically .mcworld files).
Required.
{
"status": "success",
"files": [
"MyWorld.mcworld",
"AnotherWorld.mcworld"
// ... (empty list if no files)
],
"message": "No matching files found." // Optional: if files list is empty
}(Error responses like 401 Unauthorized, 404 Not Found, or 500 Internal Server Error can occur.)
/api/content/addonsLists available addon **filenames (basenames only)** from CONTENT_DIR/addons (e.g., .mcpack, .mcaddon, .zip files).
Required.
{
"status": "success",
"files": [
"MyBehaviorPack.mcpack",
"CoolTextures.mcaddon"
// ... (empty list if no files)
],
"message": "No matching files found." // Optional: if files list is empty
}(Error responses like 401 Unauthorized, 404 Not Found, or 500 Internal Server Error can occur.)
/api/server/{server_name}/world/exportExports the server's current world to a .mcworld file in the content/worlds directory.
Required.
server_name(string)(Required){
"status": "success",
"message": "World for server '...' exported successfully as '....mcworld'.",
"export_file": "/full/path/to/content/worlds/....mcworld"
}/api/server/{server_name}/world/resetResets the server's current world.
Required.
server_name(string)(Required){
"status": "success",
"message": "World for server '...' reset successfull.",
}/api/server/{server_name}/world/installOverwrites current world to install .mcworld from content/worlds dir.
Required.
server_name(string)(Required)application/json):{ "filename": "relative/path/to/world.mcworld" }filename(string)(Required): Path relative to `content/worlds`.{"status": "success", "message": "World '...' installed successfully for server '...'."}/api/server/{server_name}/addon/installInstalls .mcpack/.mcaddon from content/addons dir into server's world.
Required.
server_name(string)(Required)application/json):{ "filename": "relative/path/to/addon.mcpack" }filename(string)(Required): Path relative to `content/addons`.{"status": "success", "message": "Addon '...' installed successfully for server '...'."}/api/players/scanScans all server logs for player connections, updates central players.json.
Required.
{ "status": "success", "players_found": true|false, "message": "Player scan completed..." }/api/players/addAdds or updates players in the global players.json file.
Required.
{
"players": [ "PlayerName1:XUID1", "PlayerName2:XUID2", /* ... */ ]
}Each player string must be in "PlayerName:PlayerXUID" format.
{
"status": "success",
"message": "Players added successfully."
}(Error responses like 400 Bad Request, 401 Unauthorized, 415 Unsupported Media Type, or 500 Internal Server Error can occur.)
/api/players/getRetrieves a list of all known players from the central players.json file.
Required.
{
"status": "success",
"players": [
{ "name": "PlayerOne", "xuid": "2535414141111111" },
{ "name": "AnotherPlayer", "xuid": "2535414141222222" }
// ...
]
// "message" field may be present if players.json was not found
}(If players.json is missing or empty, players will be an empty list. Error responses like 401 Unauthorized or 500 Internal Server Error can occur.)
/api/server/{server_name}/allowlistGets content of server's allowlist.json.
Required.
server_name(string)(Required){
"status": "success",
"existing_players": [ { "ignoresPlayerLimit": ..., "name": "..." }, ... ],
"message": "Successfully retrieved X players from allowlist."
}/api/server/{server_name}/allowlist/addAdds players to allowlist.json (does not remove existing).
Required.
server_name(string)(Required)application/json):{
"players": ["Player1", "Player2"],
"ignoresPlayerLimit": false | true
}players(list[string])(Required)ignoresPlayerLimit(boolean)(Optional, default: false){"status": "success", "message": "Allowlist saved successfully with X player(s)."}{"status": "success", "message": "No new players provided or all provided players were duplicates/invalid."}/api/server/{server_name}/allowlist/removeRemoves one or more players (case-insensitive) from the server's allowlist.json file.
Required.
server_name(string)(Required)A JSON object containing an array of player names.
players(array of strings)(Required): The list of player names to remove.{
"players": ["Steve", "Alex"]
}Returns a summary message and a details object categorizing which players were removed and which were not found.
{
"status": "success",
"message": "Allowlist update process completed.",
"details": {
"removed": [
"Steve"
],
"not_found": [
"NonExistentPlayer"
]
}
}/api/server/{server_name}/permissionsUpdates player permission levels in permissions.json.
Required.
server_name(string)(Required)application/json):{
"permissions": {
"XUID_string": "visitor | member | operator",
...
}
}permissions(object)(Required): Map of XUIDs (string) to levels (string).{"status": "success", "message": "Permissions updated successfully for X player(s) ..."}{"status": "success", "message": "No valid permission changes submitted."}/api/server/{server_name}/propertiesUpdates specified allowed keys in server.properties.
Required.
server_name(string)(Required)application/json):{ "property-key": "new-value", ... }See full docs for list of allowed keys.
{"status": "success", "message": "Server properties for '...' updated successfully."}/api/server/{server_name}/read_propertiesRetrieves the parsed content of a server's server.properties file.
Path Parameter: server_name (string, required).
Required.
{
"status": "success",
"properties": {
"level-name": "Bedrock level",
"gamemode": "survival",
"difficulty": "normal"
// ... and other properties
}
}(Error responses like 400 Bad Request, 401 Unauthorized, 404 Not Found, or 500 Internal Server Error can occur.)
/api/server/{server_name}/serviceConfigures OS-specific service settings (Linux: systemd; Windows: config flag).
Required.
server_name(string)(Required)application/json):{ "autoupdate": boolean, "autostart": boolean }{ "autoupdate": boolean }autoupdate(boolean)(Required)autostart(boolean)(Required, Linux only){"status": "success", "message": "Systemd service created and enabled successfully."}{"status": "success", "message": "Autoupdate setting for '...' updated to true."}/api/downloads/pruneDeletes old downloaded server archives from specified directory.
Required.
application/json):{
"directory": "/absolute/path/to/cache",
"keep": number
}directory(string)(Required)keep(integer)(Optional): Defaults to `DOWNLOAD_KEEP` setting.{"status": "success", "message": "Download cache pruned successfully for '...'."}/api/server/installInstalls new server instance. Requires confirmation if server name exists and `overwrite` is false.
Required.
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)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": "..."
}Note: These endpoints interact with Linux cron or Windows Task Scheduler based on the host OS.
/api/server/{server_name}/cron_scheduler/add (Linux Only)Adds raw cron job line for manager's user.
Required.
Linux Only.
server_name(string)(Required)application/json):{ "new_cron_job": "0 3 * * * /path/to/cmd --args" }new_cron_job(string)(Required){"status": "success", "message": "Cron job added successfully."}/api/server/{server_name}/cron_scheduler/modify (Linux Only)Replaces existing cron job line by exact match.
Required.
Linux Only.
server_name(string)(Required)application/json):{
"old_cron_job": "exact old string",
"new_cron_job": "replacement string"
}old_cron_job(string)(Required)new_cron_job(string)(Required){"status": "success", "message": "Cron job modified successfully."}{"status": "success", "message": "No modification needed, jobs are identical."}/api/server/{server_name}/cron_scheduler/delete (Linux Only)Deletes cron job line by exact match.
Required.
Linux Only.
server_name(string)(Required)cron_string(string)(Required): URL-encoded exact string of job to delete.{"status": "success", "message": "Cron job deleted successfully (if it existed)."}/api/server/{server_name}/task_scheduler/add (Windows Only)Creates new Windows scheduled task.
Required.
Windows Only.
server_name(string)(Required)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.{
"status": "success",
"message": "Windows task '...' created successfully.",
"created_task_name": "..."
}/api/server/{server_name}/task_scheduler/details (Windows Only)Gets details by parsing task's stored XML file.
Required.
Windows Only.
server_name(string)(Required)application/json):{ "task_name": "full_task_name" }task_name(string)(Required){
"status": "success",
"task_details": { "command_path": "...", "command_args": "...", "base_command": "...", "triggers": [...] }
}/api/server/{server_name}/task_scheduler/task/{task_name} (Windows Only)Modifies task by deleting old (task_name) and creating new based on body.
Required.
Windows Only.
server_name(string)(Required)task_name(string)(Required): Task to replace (URL encode if needed).application/json):Same as "Add Windows Task" body, defining the new task.
{
"status": "success",
"message": "Windows task modified successfully.",
"new_task_name": "..."
}/api/server/{server_name}/task_scheduler/task/{task_name} (Windows Only)Deletes Windows task and its associated XML file.
Required.
Windows Only.
server_name(string)(Required)task_name(string)(Required): Task to delete (URL encode if needed).{
"status": "success",
"message": "Task '...' and its definition file deleted successfully."
}