{% extends "base.html" %} {# --- Page Title --- #} {% block title %}API Quick Reference - {{ 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 Quick Reference

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

← Back to Documentation Index

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) --- #}

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:

{# --- 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 path matches the target pattern (and isn't bypassed), is extracted.
  2. The internal function validate_server_exist is called.
  3. The result determines the outcome.

Outcomes:

Implications for API Users:

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

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

Success Response (`200 OK`):

{ "access_token": "YOUR_JWT_TOKEN" }
{# --- Application Information Section --- #}

Application Information

GET /api/info

Retrieves the operating system type and the current application version.

Authentication:

None.

Success Response (`200 OK`):

{
        "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.)

{# --- Server Information Section --- #}

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

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

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

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

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

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

GET /api/servers/{server_name}/read_properties

Retrieves the parsed content of a server's server.properties file.

Path Parameter: server_name (string, required).

Authentication:

Required.

Success Response (`200 OK`):

{
    "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.)

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

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

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

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."
}
{# --- End Task Scheduler Section --- #} {# --- Optional: Back link at the bottom --- #}

← Back to Documentation Index

{% endblock %} {# --- Page Specific Scripts --- #} {% block body_scripts %} {# Add any JS needed specifically for this page, if any #} {% endblock %}