Server API Documentation

Provides API functions for managing Bedrock server instances.

This module serves as a key interface layer for server-specific operations within the Bedrock Server Manager. It leverages the BedrockServer core class to perform a variety of actions such as server lifecycle management (starting, stopping, restarting), configuration (getting/setting server-specific properties), and command execution.

The functions within this module are designed to return structured dictionary responses, making them suitable for consumption by web API routes, command-line interface (CLI) commands, or other parts of the application. This module also integrates with the plugin system by exposing many of its functions as callable APIs for plugins (via plugin_method()) and by triggering various plugin events during server operations.

bedrock_server_manager.api.server.get_server_setting(server_name: str, key: str, app_context: AppContext | None = None) → Dict[str, Any]

Reads any value from a server’s specific JSON configuration file (e.g., <server_name>_config.json) using dot-notation for keys.

Parameters:

  • server_name (str) – The name of the server.

  • key (str) – The dot-notation key to read from the server’s JSON configuration (e.g., “server_info.status”, “settings.autoupdate”, “custom.my_value”).

Returns:

A dictionary containing the operation result. On success: {"status": "success", "value": <retrieved_value>} On error: {"status": "error", "message": "<error_message>"} The <retrieved_value> will be None if the key is not found.

Return type:

Dict[str, Any]

Raises:
bedrock_server_manager.api.server.set_server_setting(server_name: str, key: str, value: Any, app_context: AppContext | None = None) → Dict[str, Any]

Writes any value to a server’s specific JSON configuration file (e.g., <server_name>_config.json) using dot-notation for keys. Intermediate dictionaries will be created if they don’t exist along the key path.

Parameters:

  • server_name (str) – The name of the server.

  • key (str) – The dot-notation key to write to in the server’s JSON configuration (e.g., “server_info.status”, “custom.new_setting”).

  • value (Any) – The new value to write. Must be JSON serializable.

Returns:

A dictionary containing the operation result. On success: {"status": "success", "message": "Setting '<key>' updated..."} On error: {"status": "error", "message": "<error_message>"}

Return type:

Dict[str, Any]

Raises:
bedrock_server_manager.api.server.set_server_custom_value(server_name: str, key: str, value: Any, app_context: AppContext | None = None) → Dict[str, Any]

Writes a key-value pair to the ‘custom’ section of a server’s specific JSON configuration file (e.g., <server_name>_config.json). This is a sandboxed way for plugins or users to store arbitrary data associated with a server. The key will be stored as custom.<key>.

Parameters:

  • server_name (str) – The name of the server.

  • key (str) – The key (string) for the custom value within the ‘custom’ section. Cannot be empty.

  • value (Any) – The value to write. Must be JSON serializable.

Returns:

A dictionary containing the operation result. On success: {"status": "success", "message": "Custom value '<key>' updated..."} On error: {"status": "error", "message": "<error_message>"}

Return type:

Dict[str, Any]

Raises:
bedrock_server_manager.api.server.get_all_server_settings(server_name: str, app_context: AppContext | None = None) → Dict[str, Any]

Reads the entire JSON configuration for a specific server from its dedicated configuration file (e.g., <server_name>_config.json). If the file doesn’t exist, it will be created with default values. Handles schema migration if an older config format is detected.

Parameters:

server_name (str) – The name of the server.

Returns:

A dictionary containing the operation result. On success: {"status": "success", "data": <all_settings_dict>} On error: {"status": "error", "message": "<error_message>"}

Return type:

Dict[str, Any]

Raises:
bedrock_server_manager.api.server.start_server(server_name: str, app_context: AppContext | None = None) → Dict[str, Any]

Starts the specified Bedrock server.

bedrock_server_manager.api.server.stop_server(server_name: str, app_context: AppContext | None = None) → Dict[str, str]

Stops the specified Bedrock server.

Triggers the before_server_stop and after_server_stop plugin events. The method used for stopping stop(), which involves gracefully shutdown, with a forceful fallback.

Parameters:

server_name (str) – The name of the server to stop.

Returns:

A dictionary containing the operation result.

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

{"status": "success", "message": "Server... stop initiated via <service_manager>."}

On error (e.g., already stopped): {"status": "error", "message": "<error_message>"}

Return type:

Dict[str, str]

Raises:
bedrock_server_manager.api.server.restart_server(server_name: str, send_message: bool = True, app_context: AppContext | None = None) → Dict[str, str]

Restarts the specified Bedrock server by orchestrating stop and start.

This function internally calls stop_server() and then start_server().

  • If the server is already stopped, this function will attempt to start it.

  • If running, it will attempt to stop it (optionally sending a restart message to the server if send_message=True), wait briefly for the stop to complete, and then start it again.

Parameters:

  • server_name (str) – The name of the server to restart.

  • send_message (bool, optional) – If True, attempts to send a “say Restarting server…” message to the server console via send_command() before stopping. Defaults to True.

Returns:

A dictionary with the operation status and a message, reflecting the outcome of the start/stop operations. On success: {"status": "success", "message": "Server... restarted successfully."} On error: {"status": "error", "message": "Restart failed: <reason>"}

Return type:

Dict[str, str]

Raises:
bedrock_server_manager.api.server.send_command(server_name: str, command: str, app_context: AppContext | None = None) → Dict[str, str]

Sends a command to a running Bedrock server.

The command is checked against a blacklist (defined by API_COMMAND_BLACKLIST) before being sent via send_command(). Triggers before_command_send and after_command_send plugin events.

Parameters:

  • server_name (str) – The name of the server to send the command to.

  • command (str) – The command string to send (e.g., “list”, “say Hello”). Cannot be empty.

Returns:

On successful command submission, returns a dictionary: {"status": "success", "message": "Command '<command>' sent successfully."}. If an error occurs, an exception is raised instead of returning an error dictionary.

Return type:

Dict[str, str]

Raises:
bedrock_server_manager.api.server.delete_server_data(server_name: str, stop_if_running: bool = True, app_context: AppContext | None = None) → Dict[str, str]

Deletes all data associated with a Bedrock server.

Danger

This is a HIGHLY DESTRUCTIVE and irreversible operation.

It calls delete_all_data(), which removes: - The server’s main installation directory. - The server’s JSON configuration subdirectory. - The server’s entire backup directory. - The server’s PID file.

Triggers before_delete_server_data and after_delete_server_data plugin events.

Parameters:

  • server_name (str) – The name of the server to delete.

  • stop_if_running (bool, optional) – If True (default), the server will be stopped using stop_server() before its data is deleted. If False and the server is running, the operation will likely fail due to file locks or other conflicts.

Returns:

A dictionary with the operation status and a message. On success: {"status": "success", "message": "All data for server... deleted successfully."} On error: {"status": "error", "message": "<error_message>"}

Return type:

Dict[str, str]

Raises: