{% 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 --- #}

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" }
{# --- 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:

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:

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:

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:

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:

Responses:

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:

Success Response (`200 OK`):

{# --- Server Actions Section --- #}

Server Actions

POST /api/server/{server_name}/start

Starts the specified server instance.

Authentication:

Required.

Path Parameters:

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:

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:

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:

Request Body (application/json):

{ "command": "your server command" }

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:

Success Response (`200 OK`):

DELETE /api/server/{server_name}/delete

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

Authentication:

Required.

Path Parameters:

Success Response (`200 OK`):

{"status": "success", "message": "All data for server '...' deleted successfully."}
{# --- Backup & Restore Section --- #}

Backup & Restore

POST /api/server/{server_name}/export_world

Exports current world to .mcworld file in backup dir.

Authentication:

Required.

Path Parameters:

Success Response (`200 OK`):

{
    "status": "success",
    "export_file": "/path/to/export.mcworld",
    "message": "World exported successfully."
}

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

Deletes old backups, keeping specified number.

Authentication:

Required.

Path Parameters:

Request Body (application/json, optional):

{ "keep": number }

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:

Request Body (application/json):

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:

Request Body (application/json):

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:

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/install

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

Authentication:

Required.

Path Parameters:

Request Body (application/json):

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

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:

Request Body (application/json):

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

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:

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:

Request Body (application/json):

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

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

PUT /api/server/{server_name}/permissions

Updates player permission levels in permissions.json.

Authentication:

Required.

Path Parameters:

Request Body (application/json):

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

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:

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:

Request Body (application/json):

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
}

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
}

Success Responses:

{# --- 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:

Request Body (application/json):

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

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:

Request Body (application/json):

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

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:

Query Parameters:

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:

Request Body (application/json):

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

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:

Request Body (application/json):

{ "task_name": "full_task_name" }

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:

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:

Success Response (`200 OK`):

{
    "status": "success",
    "message": "Task '...' and its definition file deleted successfully."
}
{# --- End Task Scheduler Section --- #} {# --- Optional: Back link at the bottom --- #} {% endblock %} {# --- Page Specific Scripts --- #} {% block body_scripts %} {# Add any JS needed specifically for this page, if any #} {% endblock %}