Bridge

This is used to handle your login credentials and AMP Login Sessions.

class ampapi.Bridge(api_params: APIParams | None = None, *args: Any, **kwargs: Any)[source]

Handles the API login credentials for connecting to AMP.

Simply create the class similar to the example below and then access any other API class you wish.

Then when creating any API class, this will pull login details from the Bridge.

1# This is to handle login details.
2_params = APIParams(url="http://192.168.13.130:8080", user="bot_username", password="bot_password")
3_bridge: Bridge = Bridge(ap_params=_params)
4del _params

Base

All Modules/Plugins inherit from this class.

class ampapi.Base[source]

Contains the base functions for all AMP API endpoints and handles the parsing of Bridge data.

Warning

Do not overwrite or alter the instance_id.

Note

A session expires after 240sec of inactivity per Cube Coders AMP. If for any reason you want to change that value; set the attribute session_ttl.

api_url

The URL to access the Web Panel. This comes from your APIParams.

Type:

str

session_ttl

How long before the session id expires in seconds, default is 240 seconds.

Type:

int

instance_id

The Instance id is a string determined by AMP.

This attribute will be set automatically after making a login() request, default is “O”.

Type:

str

property format_data: bool

Controls whether the data returned from an API endpoint is formatted or not.

Default is True which comes from the global parameter FORMAT_DATA.

Note

True = formatted

False = unformatted

Returns:

Returns True or False.

Return type:

bool

static ads_only(func: Callable[Concatenate[D, T], Coroutine[None, None, F]]) → Callable[Concatenate[D, T], Coroutine[None, None, F]][source]

Checks the class attribute .module and is equal to ADS or if the type of Instance using the function is AMPADSInstance.

Parameters:

func (Callable[Concatenate[D, T], Coroutine[None, None, F]]) – The function the decorator is wrapping.

Returns:

The function the decorator is wrapping.

Return type:

Callable[Concatenate[D, T], Coroutine[None, None, F]]

Raises:

RuntimeError – The API call is only allowed to be run on a type(AMPADSInstance).

async call_end_point(api: str, parameters: None | dict[str, Any] = None) → dict[str, Any][source]

This function is a coroutine.

Universal API function for calling any API endpoint. Some API endpoints require the Instance module type to be ADS.

See /api_spec_sheets/ADS_api_spec.md or /api_spec_sheets/Minecraft_api_spec.md for full API endpoints and parameter information.

Note

Parameter key “SESSIONID” is handled for you.

Warning

DO NOT include the full URL - Exclude: www.yourAMPURL.com/API/

Parameters:

  • api (str) – The AMP API endpoint to call. eg “Core/GetModuleInfo”

  • parameters (None | dict[str, Any], optional) – The parameters to pass to the API endpoint, by default is None

Returns:

The JSON response from the API endpoint.

Return type:

dict[str, Any]

static camel_to_snake_re(data: str) → str[source]

A simple regex pattern applied to a string to remove Camel Casing and apply snake_case.

Note

This will fail on entries with an underscore between to capital characters. | eg (Tool_Version = tool__version)

Will also not format properly when handling strings that have a multiple uppercase followed by a lowercase. | eg (ContainerCPUs = container_cp_us)

Parameters:

data (str) – The string to be converted.

Returns:

The converted string from CamelCase to snake_case.

Return type:

str

static camel_case_data(data: dict[str, Any]) → dict[str, Any][source]

Calls the title() on every dict key.

Parameters:

data (dict[str, Any]) – The dictionary to camel case.

Returns:

The camel cased dict.

Return type:

dict[str, Any]

static dataclass_to_dict(dataclass_: DataclassInstance) → dict[str, Any][source]

Convert a dataclass to a dictionary.

Parameters:

dataclass (DataclassInstance) – The dataclass to convert.

Returns:

The converted dataclass as a dict.

Return type:

dict[str, Any]

Raises:

TypeError – When the object passed in is not of type(DataclassInstance).

static json_to_dataclass(json: Iterable[Any], format_: type[X] | type[APIResponseDataTableAlias], _use_from_dict: bool, _auto_unpack: bool) → X | list[APIResponseDataTableAlias | X] | APIResponseDataTableAlias | None[source]

Format the JSON response data to a dataclass.

Note

All JSON response data will be sanitized before it is turned into a dataclass. See sanitize_json().

Parameters:

  • json (Any) – JSON response data to format.

  • format (Union[DataclassInstance, class:DeploymentTemplate]) – Must be of type DataclassInstance or similar to unpack the JSON response data.

  • _use_from_dict (bool) – Use fromdict() from dataclass_wizard to unpack the JSON response data. - Typically this is used to handle nested DataclassInstance.

  • _auto_unpack (bool) – Use **data to unpack the JSON response data.

Returns:

Either a list or single entry of DataclassInstance.

Return type:

X | list[DeploymentTemplate | X] | DeploymentTemplate | None

parse_bridge(bridge: Bridge) → None[source]

Takes the Bridge object and set’s the url and sets _bridge to our Bridge object.

Note

Also validates the 2FA token.

Parameters:

bridge (Bridge) – The Bridge object to parse.

Raises:

ValueError – If 2FA Token is not provided and _use_2fa == True. If 2FA Token is not enclosed in single(‘,’) or double(“,”) quotes.

parse_data(data: Controller | Instance | InstanceStatus | Updates) → Self[source]

Takes in a DataclassInstance and iterates through it’s fields() and set’s the values as attributes of the DataclassInstance that called this function.

Parameters:

data (Union[Controller, Instance, AppStatus, Updates]) – The DataclassInstance to parse.

Returns:

Returns the class that called this function.

Return type:

Self

classmethod sanitize_json(json: str) → str[source]
classmethod sanitize_json(json: Iterable) → Iterable[Any]

This function is a https://docs.python.org/3/library/functions.html#classmethod

Replaces spaces and underscores in the JSON response dict keys while also formatting keys to snake_case.

Also supports a single string and will replace any of these chars _ ' ( ) with nothing.

Parameters:

json (Any) – The JSON response data to be sanitize.

Returns:

The JSON response data cleaned up.

Return type:

Iterable[Any]

static sanitize_path(path: str) → str[source]

The path is relative to the Instances home directory. eg “/myInstanceName/”

You do not need to include “.” to specify the current directory as all path’s start from root/home.

Note

Example await Instance.copyFile(“eula.txt”, “test”) would move ./eula.txt to ./test/eula.txt

Parameters:

path (str) – The path to be sanitized.

Raises:

ValueError – If the path string contains a underscore.

Returns:

Return the sanitized path string.

Return type:

str

static to_snake_case(data: str, /) → str[source]

Quick function to return snake_case from camelCase.

Parameters:

data (str) – The string to convert.

Returns:

The camelCase string.

Return type:

str

async version_validation(version: VersionInfo) → None[source]

Compares the Version of the application/Instance against the version that is passed in.

Parameters:

version (VersionInfo) – The version to compare against the application.

Raises:

RuntimeError – The application version no longer supports this API call..

ADS Module

class ampapi.ADSModule[source]

Bases: Base

Contains the functions for any /API/ADSModule/ API endpoints.

Warning

Do not change the module attribute for any reason.

Note

Every function in this class requires the Instance type be of either AMPADSInstance, ADSModule or the module attribute to be “ADS”.

If the format_data parameter is None on any function; the global FORMAT_DATA will be used instead.

add_datastore(new_datastore: InstanceDatastore, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Add a new datastore.

Parameters:

  • new_datastore (InstanceDatastore) – Your pre-created data structure to be parsed for the required API parameters.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

apply_instance_configuration(instance_id: str, args: dict[str, str], rebuild_configuration: bool = False, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Apply an Instance configuration.

Warning

This Endpoint has not been fully tested, multiple parameters are unknown, or functionality is unknown.

Parameters:

  • instance_id (str) – The Instance ID.

  • args (dict[str, str]) – UNK.

  • rebuild_configuration (bool, optional) – UNK, defaults to False.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

apply_template(instance_id: str, template_id: int, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Overlays an existing template on an existing instance, used to perform package reconfigurations.

Warning

Do not use this to “transform” an existing application into another. The instance should be deleted and re-created in that situation.

Note

If you need to get an AMP Templates ID, use get_deployment_templates() and access the DeploymentTemplate.id attribute.

Parameters:

  • instance_id (str) – The Instance ID to apply the template to.

  • template_id (int) – The Template ID to apply.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

attach_ads(friendly_name: str, instance_id: str, host: str, port: int, is_https: bool, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Attach an AMP Instance to the specified Target ADS name.

Parameters:

  • friendly_name (str) – Name of the ADS.

  • instance_id (str) – The Instance ID of the Instance you want to attach to the ADS.

  • host (str) – The URL/URi to access the Instance.

  • port (int) – The Port you want to attach the Instance to.

  • is_https (bool) – To use HTTPS or not.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

clone_template(template_id: int, name: str, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Clone an existing AMP Deployment Template.

Note

If you need to get an AMP Templates ID, use get_deployment_templates() and access the DeploymentTemplate.id attribute.

Parameters:

  • template_id (int) – The Template ID to copy.

  • name (str) – The name for the newly cloned Template.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

create_deployment_template(template_name: str, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Create a new Deployment Template. Typically used in conjunction with update_deployment_template().

Parameters:

  • template_name (str) – The name for the newly created Template.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

create_instance(instance: CreateInstance, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Create an AMP Instance.

Note

See the CreateInstance for more details on how to configure the Instance when creating.

Parameters:

  • instance (CreateInstance) – Your pre-created data structure to be parsed for the required API parameters.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

create_local_instance(instance: CreateInstance, post_create: PostCreateActionsState = PostCreateActionsState.do_nothing, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Create a local AMP Instance, similar to create_instance(). Use case could be on a remote Target ADS Instance instead of letting AMP decide where to create the Instance.

Note

See the CreateInstance for more details on how to configure the Instance when creating.

Parameters:

  • instance (CreateInstance) – Your pre-created data structure to be parsed for the required API parameters.

  • post_create (PostCreateActions, optional) – The action to take after creating the local instance, defaults to do_nothing.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

delete_datastore(datastore_id: int, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Delete the specified Datastore by ID.

Note

You will need to know the Datastore ID you want to move the Instance ID to. See get_datastores() as a means to get the IDs.

Parameters:

  • datastore_id (int) – The datastore ID.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

delete_deployment_template(template_id: int, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Delete an existing Deployment Template.

Note

If you need to get an AMP Templates ID, use get_deployment_templates() and access the DeploymentTemplate.id attribute.

Parameters:

  • template_id (int) – The Template id.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

delete_instance(instance_name: str, format_data: bool | None = None) → RunningTask[source]

This function is a coroutine.

Delete an Instance.

Note

The instance_name parameter is referring to instance_name attribute of an Instance.

Parameters:

  • instance_name (str) – The Instance name.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a RunningTask dataclass.

Return type:

RunningTask

delete_instance_users(instance_id: str, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Delete all Users from an Instance.

Parameters:

  • instance_id (str) – The Instance ID.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

deploy_template(template: Template, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Deploy a Instance template.

Parameters:

  • template (Union[Template, None], optional) – Your pre-created data structure to be parsed for the required API parameters.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

detach_target(instance_id: str, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

De-tach an Instance from the ADS.

Parameters:

  • instance_id (str) – The Instance ID.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns an ActionResult dataclass.

Return type:

ActionResult

extract_everywhere(source_archive: str, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Extracts everything from an archive.

Note

The parameter source_archive will be sanitized. See sanitized_path()

Parameters:

  • source_archive (str) – The source archive, typically a path to the archive.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns an ActionResult dataclass.

Return type:

ActionResult

get_application_endpoints(instance_id: str, format_data: bool | None = None) → list[Endpoints][source]

This function is a coroutine.

Get the application endpoints for the specified instance.

Parameters:

  • instance_id (str) – The Instance ID.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

Returns a list of endpoints for the specified instance.

Return type:

list[Endpoints]

get_datastore(datastore_id: int, format_data: bool | None = None) → InstanceDatastore[source]

This function is a coroutine.

Get the information for the specified datastore.

Note

You will need to know the Datastore ID you want to move the Instance ID to. See get_datastores() as a means to get the IDs.

Parameters:

  • datastore_id (int) – The datastore ID.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns an InstanceDataStore dataclass.

Return type:

InstanceDataStore

get_datastores(format_data: bool | None = None) → list[InstanceDatastore][source]

This function is a coroutine.

Get a list of Datastores.

Parameters:

format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a list of DatastoreInstance dataclasses.

Return type:

list[DatastoreInstance]

get_datastore_instances(datastore_id: int, format_data: bool | None = None) → list[Instance][source]

This function is a coroutine.

Get a list of Instances tied to the specified datastore.

Note

You will need to know the Datastore ID you want to move the Instance ID to. See get_datastores() as a means to get the IDs.

Parameters:

  • datastore_id (int) – The datastore ID.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a list of Instance dataclasses.

Return type:

list[Instance]

get_deployment_templates(format_data: bool | None = None) → list[DeploymentTemplate][source]

This function is a coroutine.

Gets a list of Deployment Templates.

Parameters:

format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a list of DeploymentTemplate dataclasses.

Return type:

list[DeploymentTemplate]

get_group(group_id: str, format_data: bool | None = None) → dict[source]

This function is a coroutine.

Get the specified group.

Note

Unsure what this is used for or does. May return ADS information/Instances related to it.

Parameters:

  • group_id (str) – The Group ID.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns an dictionary.

Return type:

dict

async get_instance(instance_id: str, format_data: bool | None = None) → Instance[source]

This function is a coroutine.

Returns the Instance information for the provided Instance ID.

Parameters:

  • instance_id (str) – The Instance ID.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a Instance dataclass.

Return type:

Instance

get_instances(include_self: bool = True, format_data: bool | None = None) → list[Controller | Instance][source]

This function is a coroutine.

Returns a list of all Instances the Target ADS or Controller and AMP User has permission to access.

Note

If include_self is False; we force format_data = False

Parameters:

  • include_self (bool, optional) – Force include the Controller or Target ADS Instance in the results, by default True.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

If format_data or global FORMAT_DATA is True we return a Controller dataclasses containing their Instance dataclasses or if used on Target ADS Instance will return a list containing any combination of AMPADSInstance, AMPMinecraftInstance and AMPInstance respectively.

Return type:

list[Union[Controller, Instance]]

get_instance_network_info(instance_name: str, format_data: bool | None = None) → list[PortInfo][source]

This function is a coroutine.

Get the Port and or Network information of an Instance.

Note

The instance_name parameter is referring to instance_name attribute of an Instance.

Parameters:

  • instance_name (str) – The name of the Instance we are targeting.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a list of PortInfo dataclasses.

Return type:

list[PortInfo]

get_instance_statuses(format_data: bool | None = None) → list[InstanceStatus][source]

This function is a coroutine.

Returns a dictionary of the Instance Status.

Parameters:

format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a list of InstanceStatus dataclasses.

Return type:

list[InstanceStatus]

get_local_instances(format_data: bool | None = None) → list[Instance][source]

Gets the local instances related to the ADS or Controller.

Parameters:

format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a list of Instance dataclasses.

Return type:

list[Instance]

get_provision_arguments(module_name: str, format_data: bool | None = None) → list[ProvisionSettingInfo][source]

This function is a coroutine.

Get Provision Arguments.

Parameters:

  • module_name (str) – The Module Name (eg. “Minecraft”)

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a list of ProvisionSettingInfo dataclasses.

Return type:

list[ProvisionSettingInfo]

get_provision_fitness(format_data: bool | None = None) → Provision[source]

This function is a coroutine.

Get the provision fitness of the ADS or Controller.

Parameters:

format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a Provision dataclass.

Return type:

Provision

get_supported_applications(format_data: bool | None = None) → list[Application][source]

This function is a coroutine.

Get supported applications, such as Template information and the list of Applications when creating an Instance.

Parameters:

format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

Returns a list of all applications that can be deployed.

Return type:

list[Application]

get_target_info(format_data: bool | None = None) → RemoteTargetInfo[source]

This function is a coroutine.

Get target info.

Parameters:

format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a RemoteTargetInfo dataclass.

Return type:

RemoteTargetInfo

handout_instance_configs(module: str, setting_node: str, values: list[str], format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Handout Instance Configuration.

Parameters:

  • module (str) – The Module Name. eg. “Minecraft”

  • setting_node (str) – A setting node. See “./docs/setting_nodes.md”

  • values (list[str]) – The values for the setting node.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

manage_instance(instance_id: str, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Manage the specified instance.

Note

Actual usage unknown, may be used for AMP instance management via the web interface.

Parameters:

  • instance_id (str) – The Instance ID.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns an ActionResult dataclass.

Return type:

ActionResult

modify_custom_firewall_rule(instance_id: str, port_number: int, range_: int, protocol: int, description: str, open_: bool = True, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Modify the Firewall Rule of the specified instance.

Parameters:

  • instance_id (str) – The Instance ID.

  • port_number (int) – Port number.

  • range (int) – Port range.

  • protocol (int) – UDP/TCP/Both.

  • description (str) – Description for which the rule is applied.

  • open (bool, optional) – Open or close the port mapping, by default True

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns an ActionResult dataclass.

Return type:

ActionResult

move_instance_datastore(instance_id: str, datastore_id: int, format_data: bool | None = None) → RunningTask[source]

This function is a coroutine.

Move an Instance to a different Datastore.

Note

You will need to know the Datastore ID you want to move the Instance ID to. See get_datastores() as a means to get the IDs.

Parameters:

  • (str) (instance_id) – The Instance ID to move.

  • datastore_id (int) – The ID of the datastore to move the Instance to.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a RunningTask dataclass.

Return type:

RunningTask

reactivate_local_instances(format_data: bool | None = None) → RunningTask[source]

This function is a coroutine.

Reactivate local instances.

Parameters:

format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a RunningTask dataclass.

Return type:

RunningTask

refresh_app_cache() → None[source]

This function is a coroutine.

Refresh the application cache.

Return type:

None

refresh_group(group_id: str, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Refresh the specified group.

Parameters:

  • group_id (str) – The Group ID to refresh.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

refresh_instance_config(instance_id: str, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Refresh an Instance Configuration.

Parameters:

  • instance_id (str) – The Instance ID.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

refresh_remote_config_stores(force: bool = False) → None[source]

This function is a coroutine.

Refresh remote config stores.

Parameters:

force (bool, optional) – Force refresh, defaults to False.

Return type:

None

register_target(controller_url: str, my_url: str, username: str, password: str, friendly_name: str, two_factor_token: str = '', format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Registers a Target to a Controller.

Parameters:

  • controller_url (str) – The Controller panel url.

  • my_url (str) – The Target AMP panel url.

  • username (str) – The username for logging into the Target AMP panel.

  • password (str) – The password for logging into the Target AMP panel.

  • friendly_name (str) – Instance Friendly Name.

  • two_factor_token (str) – The two-factor authentication token for the username. Defaults to “”

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

repair_datastore(datastore_id: int, format_data: bool | None = None) → RunningTask[source]

This function is a coroutine.

Repair the specified datastore.

Note

You will need to know the Datastore ID you want to move the Instance ID to. See get_datastores() as a means to get the IDs.

Parameters:

  • (int) (datastore_id) – The datastore ID.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a RunningTask dataclass.

Return type:

RunningTask

request_datastore_size_calculation(datastore_id: int, format_data: bool | None = None) → RunningTask[source]

This function is a coroutine.

Request a calculation of the size of the specified Datastore.

Note

You will need to know the Datastore ID you want to move the Instance ID to. See get_datastores() as a means to get the IDs.

Parameters:

  • (int) (datastore_id) – The datastore ID.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a RunningTask dataclass.

Return type:

RunningTask

restart_instance(instance_name: str, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Restart an Instance.

Note

The instance_name parameter is referring to instance_name attribute of an Instance.

Parameters:

  • instance_name (str) – The Instance Name.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns an ActionResult dataclass.

Return type:

ActionResult

servers(id_: str, req_rawjson: str = 'application/json', format_data: bool | None = None) → Any[source]

This function is a coroutine.

Used for proxy authentication.

Warning

This Endpoint has not been fully tested, multiple parameters are unknown, or functionality is unknown.

Parameters:

  • id (str) – The Instance ID.

  • req_rawjson (str, optional) – The data type, by default “application/json”

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

UNK.

Return type:

Any

set_instance_network_info(instance_id: str, port_mappings: dict[str, int], format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Set the Port mappings for an Instance.

Parameters:

  • instance_id (str) – The Instance ID.

  • port_mappings (dict[str, int]) – Port ranges and protocols to map.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

set_instance_config(instance_name: str, setting_node: str, value: str, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Set an AMPInstance Setting Node setting.

Note

See ../nodes/setting_nodes.md for possible setting_node values.

Note

The instance_name parameter is referring to instance_name attribute of an Instance.

Parameters:

  • instance_name (str) – The Instance name.

  • setting_node (str) – The setting node name.

  • value (str) – The value for the setting node.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

set_instance_suspended(instance_name: str, suspended: bool = False, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Set an Instances suspended State.

Note

The instance_name parameter is referring to instance_name attribute of an Instance.

Parameters:

  • instance_name (str) – The Instance name.

  • suspended (bool) – Set the instance to be suspended, default False.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns an ActionResult dataclass.

Return type:

ActionResult

start_all_instances(instance_id: str, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Start all Instances.

Parameters:

format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns an ActionResult dataclass.

Return type:

ActionResult

start_instance(instance_name: str, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Start an Instance.

Note

The instance_name parameter is referring to instance_name attribute of an Instance.

Parameters:

  • instance_name (str) – The Instance name.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns an ActionResult dataclass.

Return type:

ActionResult

stop_all_instances(instance_id: str, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Stop all Instances.

Parameters:

format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns an ActionResult dataclass.

Return type:

ActionResult

stop_instance(instance_name: str, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Stop an Instance.

Note

The instance_name parameter is referring to instance_name attribute of an Instance.

Parameters:

  • instance_name – The Instance name.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns an ActionResult dataclass.

Return type:

ActionResult

update_datastore(updated_datastore: InstanceDatastore, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Update an existing datastore.

Parameters:

  • updated_datastore (InstanceDatastore) – Your pre-created data structure to be parsed for the required API parameters.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns an ActionResult dataclass.

Return type:

ActionResult

update_deployment_template(template_to_update: DeploymentTemplate, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Update an existing Deployment Template.

Parameters:

  • template_to_update (DeploymentTemplate) – Your pre-created data structure to be parsed for the required API parameters.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns an ActionResult dataclass.

Return type:

ActionResult

update_instance_info(instance_info: InstanceInfo, format_data: bool | None = None) → ActionResult[source]

Update an Instances info.

Parameters:

  • instance_info (InstanceInfo) – Your pre-created data structure to be parsed for the required API parameters.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns an ActionResult dataclass.

Return type:

ActionResult

update_target(target_id: str) → None[source]

This function is a coroutine.

Update Target ADS Instance.

Note

Typically this will be used on Instances with a the module == “ADS”

Parameters:

target_id (str) – The Target Instance ID.

Return type:

None

update_target_info(instance_id: str, friendly_name: str, url: str, description: str, tags: list[str], format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Update a target Instance information.

Parameters:

  • instance_id (str) – The Instance ID for the Instance you want to update.

  • friendly_name (str) – The Instance friendly name you want to set.

  • url (str) – The Instance URL you want to set.

  • (str) (description)

  • tags (list[str]) – The tags you want to add to the Instance.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

upgrade_all_instances(instance_id: str, restart_running: bool = False, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Upgrade all Instances.

Parameters:

  • restart_running (bool) – Restart any running Instances, default is False.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

upgrade_instance(instance_name: str, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Update or Upgrade the Instance

Note

The instance_name parameter is referring to instance_name attribute of an Instance.

Parameters:

  • instance_name (str) – The Instance name.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

Analytics Module

class ampapi.AnalyticsPlugin[source]

Bases: Base

Contains the base functions for any /API/AnalyticsPlugin/ AMP API endpoints.

Note

If the format_data parameter is None on any function; the global FORMAT_DATA will be used instead.

async get_analytics_summary(period_days: int = 30, start_date: datetime = datetime.datetime(2025, 4, 6, 22, 41, 15, 239927), filters: AnalyticsFilter | None = None, format_data: bool | None = None) → AnalyticsSummary[source]

This function is a coroutine. Retrieves the Analytics data for the Instance.

See data such as how many people are playing, how long they’ve been playing, and where they are from.

Parameters:

  • period_days (int, optional) – How far back in days to go, by default 30

  • start_date (datetime.datetime, optional) – The date to start from, by default now()

  • filters (Union[AnalyticsFilter, None], optional) – Filters results based upon the supplied dataclass values. See Analytics_Filter, by default None

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns an AnalyticsSummary dataclass.

Return type:

AnalyticsSummary

Core Module

class ampapi.Core[source]

Bases: Base

Contains the functions for any /API/Core/ AMP API endpoints.

Note

If the format_data parameter is None on any function; the global FORMAT_DATA will be used instead.

triggers

You can access all the trigger IDs an instance has via this attribute. See TriggerID for more information.

Type:

TriggerID

async acknowledge_amp_update() → None[source]

This function is a coroutine.

Approve an AMP update.

Return type:

None

async activate_amp_license(license_key: str, query_only: bool = False, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Activate an AMP License key.

Parameters:

  • license_key (str) – Your AMP License key.

  • query_only (bool, optional) – UNK, by default False.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

async add_event_trigger(trigger_id: str, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Add an Event Trigger to an Instance.

Note

See Triggers.id; which you can get a list of triggers from the documentation.

Parameters:

  • trigger_id (str) – The Trigger ID.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

async add_task(trigger_id: str, method_id: str, parameter_mapping: dict[str, str], format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Add a task.

Note

Example -> parameter_mapping = { "Subtitle": "Hello World", Title: "Hello {@UserID}" }

Parameters:

  • trigger_id (class:str) – The ID of the trigger to add.

  • method_id (class:str) – The Task method name. eg. `Event.MinecraftModule.SendGlobalTitle

  • parameter_mapping (:class:dict[str, str]) – The parameters to be populated related to the trigger_id/method_id.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

async cancel_task(task_id: str, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Cancel an existing Task.

Parameters:

  • task_id (str) – The ID of the Task.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

async change_user_password(username: str, old_password: str, new_password: str, two_factor_pin: str = '', format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

For a user to change their own password, requires knowing the old password.

Parameters:

  • username (str) – The AMP user name.

  • old_password (str) – Current AMP user password.

  • new_password (str) – New AMP user password.

  • two_factor_pin (str) – Two Factor PIN, if enabled. Defaults to “”.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

async change_task_order(trigger_id: str, task_id: str, new_order: int, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Change the order of a task.

Parameters:

  • trigger_id (str) – The ID of the Trigger you want to change the order of a task.

  • task_id (str) – The ID of the task to modify. See get_schedule_data() to get IDs

  • new_order (int) – The new task position.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

async confirm_two_factor_setup(username: str, two_factor_code: str, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Completes two-factor setup by supplying a valid two factor code based on the secret provided by EnableTwoFactor.

Parameters:

  • username (str) – The AMP User name to confirm 2FA setup.

  • two_factor_code (str) – Two factor code.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

async create_role(role_name: str, as_common_role: bool = False, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Creates an AMP Role.

Parameters:

  • role_name (str) – The name you want for the AMP role.

  • as_common_role (bool, optional) – A role that everyone has, defaults to False.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

async create_user(username: str, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Create an AMP user.

Parameters:

  • username (str) – The AMP User name.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

async current_session_has_permission(node: str) → bool[source]

This function is a coroutine.

Retrieves the current Session IDs permissions. This will differ between the ADS and a Server/Instance.

Note

Supports looking for a blocked permission node simply by appending - in front of the permission node. eg -Core.RoleManagement.DeleteRoles, also supports wildcards *. eg Core.RoleManagement.*

Parameters:

node (str) – The permission node to check for. eg Core.RoleManagement.DeleteRoles.

Return type:

bool

async delete_instance_users(instance_id: str, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Delete an Instances User list.

Parameters:

  • instance_id (str) – The AMP Instance ID.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

async delete_role(role_id: str, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Deletes a role.

Parameters:

  • role_id (str) – The ID of the role to delete.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

async delete_task(trigger_id: str, task_id: str, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Delete a task.

Parameters:

  • trigger_id (str) – The ID of the trigger to delete.

  • task_id (str) – The ID of the task to delete. See get_schedule_data() and check the Tasks class to get IDs.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

async delete_trigger(trigger_id: str, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Delete a trigger.

Parameters:

  • trigger_id (str) – The ID of the trigger to delete.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

async delete_user(username: str, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Delete an AMP user.

Parameters:

  • username (str) – The AMP User name.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

async disable_two_factor(format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Disables two-factor authentication for the currently logged in AMP User.

Warning

This applies to the AMP User name supplied to interact with the API.

Parameters:

format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

async dismiss_all_tasks(format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Dismiss all task notifications.

Parameters:

format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

async dismiss_task(task_id: str, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Dismiss a task notification.

Parameters:

  • task_id (str) – The ID of the task to delete. See get_schedule_data() and check the Tasks class to get IDs.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

async edit_interval_trigger(trigger_id: str, months: int, days: int, hours: int, minutes: int, days_of_month: int, description: str, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Edits an interval trigger.

Parameters:

  • trigger_id (str) – The ID of the interval trigger to edit.

  • months (int) – The number of the month you want the trigger to run.

  • days (int) – The days of the interval trigger to edit, the first day of the week is Monday.

  • hours (int) – The hours of the interval trigger to edit.

  • minutes (int) – The minutes of the interval trigger to edit.

  • days_of_month (int) – The days of the month of the interval trigger to edit.

  • description (str) – The description of the interval trigger to edit.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

async edit_task(trigger_id: str, task_id: str, parameter_mapping: dict[str, str], format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Edit a task.

Parameters:

  • trigger_id (str) – The ID of the trigger to edit.

  • task_id (str) – The ID of the task to edit. See get_schedule_data() to get IDs.

  • parameter_mapping (dict[str, str]:) – The parameters to be updated on the task.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

async enable_two_factor(username: str, password: str, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Sets up two-factor authentication for the given user.

Warning

ConfirmTwoFactorSetup must be invoked to complete setup.

Parameters:

  • username (str) – The AMP User name.

  • password (str) – The AMP Users password.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

end_user_session(session_id: str) → None[source]

This function is a coroutine.

Closes the specified User’s session ID to AMP.

Warning

The Instance must be an ADS or Controller.

Parameters:

session_id (str) – The AMP Session ID to close.

get_active_amp_sessions(format_data: bool | None = None) → list[Session][source]

This function is a coroutine.

Returns currently active AMP Sessions.

Warning

The Instance must be an ADS or Controller.

Parameters:

format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a Session dataclass.

Return type:

Session

async get_all_amp_user_info(format_data: bool | None = None) → list[User][source]

This function is a coroutine.

Retrieves all AMP Users and their information.

Parameters:

format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a list of User dataclasses.

Return type:

list[User]

async get_amp_role_permissions(role_id: str) → list[str][source]

This function is a coroutine.

Retrieves the AMP Role permission nodes for the provided role ID.

Parameters:

role_id (str) – The role ID. eg “5d6566e0-fae2-41d7-bfb6-d21033247f2e”

Returns:

On success returns a list of strings containing all the permission nodes for the provided role id.

Return type:

list[str]

async get_amp_user_info(name: str, format_data: bool | None = None) → User[source]

This function is a coroutine.

Retrieves the AMP User information for the provided username.

Parameters:

  • name (str) – The AMP User name.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a User dataclass.

Return type:

User

async get_amp_users_summary(format_data: bool | None = None) → list[LoginUserInfo][source]

This function is a coroutine.

Get all AMP users summary.

Parameters:

format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a list of UserInfoSummary dataclass.

Return type:

list[UserInfoSummary]

async get_api_spec(sanitize_json: bool = False) → APISpec[source]

This function is a coroutine.

Get’s all the API specs for the Instance.

Note

See API Reference for more information.

Returns:

On success returns a dictionary with all of the API specs, their parameters and return types for the Instance.

Return type:

APISpec

async get_audit_log_entries(before: float = 1743979275.247226, count: int = 10, format_data: bool | None = None) → list[AuditLogEntry][source]

This function is a coroutine.

Returns the last count number of audit log entries.

Note

These are anything in the Console of the Controller/ADS such as login events or API calls.

Parameters:

  • before (float) – A POSIX timestamp, defaults to datetime.now().timestamp().

  • count (int) – Number of entries to return, default is 10.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a list of AuditLogEntry dataclasses.

Return type:

list[AuditLogEntry]

async get_authentication_requirements(username: str, format_data: bool | None = None) → list[Any][source]

This function is a coroutine.

Get a list of Authentication requirements for the AMP user.

Parameters:

  • username (str) – The AMP username.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a list of Authentication requirements.

Return type:

list[Any]

async get_config(node: str, format_data: bool | None = None) → SettingSpec[source]

This function is a coroutine.

Returns the config settings for a specific node.

Note

See Setting Nodes for more information.

Parameters:

  • node (str) – The AMP node to inspect. eg “ADSModule.Networking.BaseURL”

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a SettingSpec dataclass.

Return type:

SettingSpec

async get_configs(nodes: list[str], format_data: bool | None = None) → list[SettingSpec][source]

This function is a coroutine.

Returns the config settings for each node in the list.

Note

See Setting Nodes for more information.

Parameters:

  • node (list[str]) – The list of setting nodes to look at.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a list of SettingSpec dataclasses.

Return type:

list[SettingSpec]

async get_diagnostics_info(format_data: bool | None = None) → Diagnostics[source]

This function is a coroutine.

Get’s the system diagnostics information.

Parameters:

format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a Diagnostics dataclass.

Return type:

Diagnostics

async get_module_info(format_data: bool | None = None) → Module[source]

This function is a coroutine.

Returns the module information.

Parameters:

format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a Module dataclass.

Return type:

Module

async get_new_guid(format_data: bool | None = None) → dict[str, Any][source]

This function is a coroutine.

Get a new GUID for the Instance.

Parameters:

format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

async get_oidc_login_url() → None[source]

Interacts with OIDC credentials.

Return type:

None

async get_permissions_spec() → list[PermissionNode][source]

This function is a coroutine.

Retrieves the AMP Permissions node tree.

Returns:

On success returns a PermissionNode dataclass.

Return type:

list[PermissionNode]

async get_port_summaries(format_data: bool | None = None) → list[Port][source]

This function is a coroutine.

Get a summary of the Instance’s open ports.

Parameters:

format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a list of Port dataclasses.

Return type:

list[Port]

async get_provision_spec(format_data: bool | None = None) → list[SettingSpec][source]

This function is a coroutine.

Returns the provisioning spec.

Parameters:

format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a list of SettingSpec dataclasses.

Return type:

list[SettingSpec]

async get_remote_login_token(description: str | None = None, is_temporary: bool | None = None, format_data: bool | None = None) → str[source]

This function is a coroutine.

Get the remote login token.

Parameters:

  • description (Union[str, None], optional) – You can set a description of what the token is for, defaults to None.

  • is_temporary (Union[bool, None], optional) – If the token should be temporary, defaults to None.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a str.

Return type:

str

async get_role(role_id: str, format_data: bool | None = None) → Role[source]

This function is a coroutine.

Retrieves the AMP Role information for the provided role ID.

Parameters:

  • role_id (str) – The role ID to get information for.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a Role dataclass.

Return type:

Role

async get_role_data(format_data: bool | None = None) → list[Role][source]

This function is a coroutine.

Get’s a list of all the roles.

Parameters:

format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a list of Role dataclasses.

Return type:

list[Role]

async get_role_ids() → dict[str, str][source]

This function is a coroutine.

Retrieves all the Roles AMP currently has and the role IDs.

Returns:

On success returns a dictionary containing all the roles and their IDs.

Return type:

dict[str, str]

async get_schedule_data(format_data: Literal[False] | None) → ScheduleDataData[source]
async get_schedule_data(format_data: Literal[True] | None) → ScheduleData

This function is a coroutine.

Returns a dictionary of the Server/Instance Schedule events and triggers.

Parameters:

format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ScheduleData dataclass, unless format_data is False which it will return ScheduleDataData.

Return type:

ScheduleData | ScheduleDataData

async get_setting_spec(format_data: bool | None = None) → SettingsSpecParent[source]

This function is a coroutine.

Retrieves a list of settings specifications that can be changed.

Note

See Setting Nodes for more information.

Parameters:

format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a SettingSpecParent dataclass.

Return type:

SettingSpecParent

async get_setting_values(setting_node: str) → dict[str, str][source]

This function is a coroutine.

Returns the setting values.

Note

See Setting Nodes for more information.

Parameters:

  • setting_node (str) – The setting node name.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a dictionary of setting values.

Return type:

dict[str, str]

async get_status(format_data: bool | None = None) → InstanceStatus[source]

This function is a coroutine.

Gets the AMP Instance/Application Status information.

Parameters:

format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a InstanceStatus dataclass.

Return type:

InstanceStatus

async get_tasks(format_data: bool | None = None) → list[RunningTask][source]

This function is a coroutine.

Get a list of running tasks on the Instance.

Parameters:

format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a list of RunningTask dataclasses.

Return type:

list[RunningTask]

async get_time_interval_trigger(trigger_id: str, format_data: bool | None = None) → TimedTrigger[source]

This function is a coroutine.

Gets a time interval trigger information.

Parameters:

  • trigger_id (str) – The ID of the time interval trigger to get.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a TimedTrigger dataclass.

Return type:

TimedTrigger

async get_triggers() → TriggerID[source]

This function is a coroutine.

Retrieves the available trigger IDs for the Instance and sets them as attributes tied to triggers.

Note

Each Instance has unique Trigger IDs. You can simply access the correct ID for the Trigger via a_backup_has_started as an example. This would return the ID string to be passed into a function that requires a Trigger ID value.

Returns:

A class containing the Trigger Description as attributes referencing the Trigger ID tied to the Instance.

Return type:

TriggerID

async get_update_info(format_data: bool | None = None) → UpdateInfo[source]

This function is a coroutine.

Gets the Update Version information for AMP.

Parameters:

format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a UpdateInfo dataclass.

Return type:

UpdateInfo

async get_updates(format_data: bool | None = None) → Updates[source]

This function is a coroutine.

Gets changes to the server status, in addition to any notifications or console output that have occurred since the last time meth:get_updates was called by the current session.

Parameters:

format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a Updates dataclass.

Return type:

Updates

async get_user_action_spec(format_data: bool | None = None) → ActionSpec[source]

This function is a coroutine.

Get a specification of the user actions.

Parameters:

format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionSpec.

Return type:

ActionSpec

async get_user_info(user_id: str, format_data: bool | None = None) → UserApplicationData[source]

This function is a coroutine.

Provides information about a given in-application user (as opposed to AMP Users).

Parameters:

  • user_id (str) – The Application User id. See get_user_list().

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a UserApplicationData class.

Return type:

UserApplicationData

async get_user_list(format_data: bool | None = None) → Players[source]

This function is a coroutine.

Returns the list of the connected users to the Application.

Parameters:

format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a Players dataclasses.

Return type:

Players

async get_webauthn_challenge(format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Get a webauthn challenge.

Parameters:

format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

async get_webauthn_credential_ids(username: str, format_data: bool | None = None) → list[Any][source]

This function is a coroutine.

Get a webauthn credential IDs.

Parameters:

  • username (str) – Username.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

async get_webauthn_credential_summary(format_data: bool | None = None) → list[Any][source]

This function is a coroutine.

Get the webauthn credential summaries.

Parameters:

format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

list[Any]

Return type:

List of webauthn credential summaries.

get_webserver_metrics(format_data: bool | None = None) → Any[source]

This function is a coroutine.

Gets the webserver metrics.

Removed in version “2.6.0.0”.

Parameters:

format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

UNK data returned by the API.

Return type:

Any

async kill_application() → None[source]

This function is a coroutine.

Kills the Instances Application (eg. Minecraft Server, Source Server, Palworld Server, etc.)

Return type:

None

kill_instance() → None[source]

This function is a coroutine.

Kills the Instances Application (eg. Minecraft Server, Source Server, Palworld Server, etc.)

Return type:

None

async login(amp_user: str, amp_password: str, token: str = '', rememberME: bool = False, format_data: bool | None = None) → LoginResults[source]

This function is a coroutine.

AMP API login function.

Parameters:

  • amp_user (str) – The username for logging into the AMP Panel

  • amp_password (str) – The password for logging into the AMP Panel

  • token (str , optional) – AMP 2 Factor auth code; typically using TOTP.now(), defaults to “”.

  • rememberME (bool , optional) – Remember me token, defaults to False.

Returns:

On success returns a LoginResults dataclass.

Return type:

LoginResults

async logout() → None[source]

This function is a coroutine.

Logout from AMP.

Return type:

None

restart_amp() → None[source]

This function is a coroutine.

Restart the AMP Instance

Return type:

None

async resume_instance() → None[source]

This function is a coroutine.

Allows the service to be re-started after previously being suspended.

Return type:

None

async refresh_setting_value_list(node: str, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Refreshes a setting nodes values.

Parameters:

  • name (str) – The setting node name.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

async refresh_settings_source_cache(format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Refreshes the settings source cache.

Parameters:

format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

async rename_role(role_id: str, new_name: str, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Renames a role.

Parameters:

  • role_id (str) – The ID of the role to rename.

  • new_name (str) – The new name for the role.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

restart_instance(format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Restarts the Instances Application (eg. Minecraft Server, Source Server, Palworld Server, etc.)

Parameters:

format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

async restart_application(format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Restarts the Instances Application (eg. Minecraft Server, Source Server, Palworld Server, etc.)

Parameters:

format_data (Union[bool, None], optional) – Format the JSON response data. (Uses FORMAT_DATA global constant if None), by default None

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

async reset_user_password(username: str, new_password: str, format_data: bool | None = None) → ActionResult[source]

For administrative users to alter the password of another user.

Parameters:

  • username (str) – Username.

  • new_password (str) – New password.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

async revoke_webauthn_credential(auth_id: int, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Revoke a webauthn credential.

Parameters:

  • auth_id (int) – The Web auth ID.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

async run_security_check(format_data: bool | None = None) → Any[source]

This function is a coroutine.

Run a security check on the Instance.

Parameters:

format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Return type:

Any

async run_event_trigger_immediately(trigger_id: str, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Runs an event trigger immediately.

Parameters:

  • trigger_id (str) – The ID of the event trigger to run.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

async set_amp_user_role_membership(user_id: str, role_id: str, is_member: bool, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Adds a user to an AMP role.

Parameters:

  • user_id (str) – User ID to add to the role.

  • role_id (str) – Role ID to add the user to.

  • is_member (bool) – “True” to add the user to the role, “False” to remove the user from the role.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

async set_amp_role_permission(role_id: str, permission_node: str, enabled: None | bool, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Set a permission node to “True” or “False” for the provided AMP role.

Parameters:

  • role_id (str) – Role ID to add the user to.

  • permission_node (str) – AMP permission node. eg “Core.RoleManagement.DeleteRoles”

  • enabled (Union[None, bool], optional) – Set a permission to “True”, “False” or “None” depending on the results you can disable or enable an entire tree node of permissions.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

async set_trigger_enabled(trigger_id: str, enabled: bool, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Sets the enabled state of a trigger.

Parameters:

  • trigger_id (str) – The ID of the trigger to edit.

  • enabled (bool) – The enabled state of the trigger to edit.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

async send_console_message(msg: str) → None[source]

This function is a coroutine.

Sends a message or command to the Console. (eg /list)

Return type:

None

async set_configs(data: dict[str, str], format_data: bool | None = None) → bool[source]

This function is a coroutine.

Set multiple Setting Nodes values.

Parameters:

  • data (dict[str, str]) – Dictionary of Setting Nodes to set.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a boolean.

Return type:

bool

async set_config(node: str, value: str, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Set a Setting Node value.

Parameters:

  • name (str) – Setting node name.

  • value (str) – Config node value.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

async start_application(format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Starts the Instances Application (eg. Minecraft Server, Source Server, Palworld Server, etc.)

Parameters:

format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

async stop_application() → None[source]

This function is a coroutine.

Stops the Instances Application (eg. Minecraft Server, Source Server, Palworld Server, etc.)

Return type:

None

async suspend_instance() → None[source]

This function is a coroutine.

Prevents the current instance from being started, and stops it if it’s currently running.

Return type:

None

async update_account_info(email_address: str, two_factor_pin: str, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Update account info.

Note

All these settings take affect on the account logged in via the API.

Parameters:

  • email_address (str) – The new Email address.

  • two_factor_pin (str) – Two factor PIN.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

upgrade_amp() → None[source]

This function is a coroutine.

Upgrade the current AMP Instance.

Warning

The Instance must be an ADS or Controller.

Return type:

None

update_amp_instance() → None[source]

This function is a coroutine.

Updates the ADS Instance.

Warning

The Instance must be an ADS or Controller.

Return type:

None

async update_application(format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Update the Instance application.

Parameters:

format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

async update_user_info(username: str, disabled: bool = False, password_expires: bool = False, cannot_change_password: bool = False, must_change_password: bool = False, email_address: str = '', format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Update an AMP user.

Parameters:

  • username (str) – The AMP user to update.

  • disabled (bool, optional) – If the AMP user should be disabled, defaults to False.

  • password_expires (bool, optional) – If the AMP user password should expire, defaults to False.

  • cannot_change_password (bool, optional) – The AMP user cannot change their password, defaults to False.

  • must_change_password (bool, optional) – The AMP user must change password upon next login, defaults to False.

  • email_address (str, optional) – The email address to set for the AMP user, defaults to “”.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

async webauthn_register(attestation_object: str, client_data_json: str, description: str, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Webauthn register.

Note

Unknown usage.

Parameters:

  • attestation_object (str) – Attestation object.

  • client_data_json (str) – Client data JSON.

  • description (str) – Description.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

Email Sender Module

class ampapi.EmailSenderPlugin[source]

Bases: Base

Contains the functions for any /API/EmailSenderPlugin/ API endpoints.

async test_SMTP_settings(format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Test SMTP Settings.

Note

This is a development endpoint.

Parameters:

format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns an ActionResult dataclass.

Return type:

ActionResult

File Manager Module

class ampapi.FileManagerPlugin[source]

Bases: Base

Contains all functions for any /API/FileManagerPlugin/ API endpoints.

Note

All file_path fields must include the path to the file and the file name. All paths are relative to the Server/Instance root that is making the API call.

Note

You do not need to include the “/” at the start of the path. All file_path fields are sanitized prior to making the API call. See sanitize_path()

Note

“await Instance.copyFile(“eula.txt”, “test”)” would move “./InstanceName/eula.txt” to “./InstanceName/test/eula.txt”

async append_file_chunk(file_path: str, data: str, delete: bool) → None[source]

This function is a coroutine.

Append data to a file.

Parameters:

  • file_path (str) – Path to the file; relative to the Instance root. eg ./InstanceName/.

  • data (str) – Binary data to be written.

  • delete (bool) – UNK

async calculate_file_md5_sum(file_path: str, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Calculate the MD5 sum of a file.

Parameters:

  • file_path (str) – Path to the file; relative to the Instance root. eg ./InstanceName/.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

async change_exclusion(file_path: str, as_directory: bool, exclude: bool, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Change a file or directory to be excluded from backups.

Parameters:

  • file_path (str) – Path to the file; relative to the Instance root. eg ./InstanceName/.

  • as_directory (bool) – If file_path is a directory.

  • exclude (bool) – If file_path should be excluded from backups or not.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

async copy_file(file_path: str, destination_path: str, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Moves a file from the origin directory to the target_directory.

Warning

Make sure to NOT INCLUDE the file name in the destionation_path parameter.

Parameters:

  • file_path (str) – Path to the file; relative to the Instance root. eg ./InstanceName/.

  • destionation_path (str) – Similar to file_path; do not include the file name. (eg. “test”)

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

async create_archive(file_path: str, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Create an archive file.

Parameters:

  • file_path (str) – Path to the file; relative to the Instance root. eg ./InstanceName/.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

async create_directory(file_path: str, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Creates a new directory. The parent directory must already exist.

Parameters:

  • file_path (str) – Path to the file; relative to the Instance root. eg ./InstanceName/.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

async download_file_from_url(source: str, file_path: str, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Download a file from a URL.

Parameters:

  • source (str) – The URL to file.

  • file_path (str) – Path to the file; relative to the Instance root. eg ./InstanceName/.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

async empty_trash(file_path: str, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Empties a trash bin for the AMP Server/Instance.

Note

Typically the directory is called Trashed Files, it is case sensitive and located in the Server/Instance root directory.

Parameters:

  • file_path (str) – Path to the file; relative to the Instance root. eg ./InstanceName/.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

async extract_archive(file_path: str, destination_path: str | None = None, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Extract an archive file.

Parameters:

  • file_path (str) – Path to the file; relative to the Instance root. eg ./InstanceName/.

  • destination_path (Union[str, None], optional) – The path to extract the archive to; relative to the Server/Instance root. eg home/config, defaults to None.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

async get_directory_listing(file_path: str = '', format_data: bool | None = None) → list[Directory][source]

This function is a coroutine.

Returns a dictionary of the path’s properties and the files contained in the directory and their properties.

Note

If a file has a similar name it may return the file instead of the directory.

Parameters:

  • file_path (str) – Path to the file; relative to the Instance root. eg ./InstanceName/.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a list of Directory dataclasses.

Return type:

list[Directory]

async get_file_chunk(file_path: str, index: int, length: int, format_data: bool | None = None) → FileChunk[source]

This function is a coroutine.

Returns a specific section of Base64 data from the file.

Parameters:

  • file_path (str) – Path to the file; relative to the Instance root. eg ./InstanceName/.

  • index (int) – The start position to read the file from, in bytes.

  • length (int) – How far to read from the index position, in bytes.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a FileChunk dataclass.

Return type:

FileChunk

async read_file_chunk(file_path: str, offset: int, chunk_size: int | None = None, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Read a chunk of data from a file.

Parameters:

  • file_path (str) – Path to the file; relative to the Instance root. eg ./InstanceName/.

  • index (int) – The start position to read the file from, in bytes.

  • length (int) – How far to read from the index position, in bytes.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

async release_file_upload_lock(file_path: str, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Releases a File Upload Lock.

Parameters:

  • file_path (str) – Path to the file; relative to the Instance root. eg ./InstanceName/.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

async rename_directory(file_path: str, name: str, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Rename a directory.

Parameters:

  • file_path (str) – Path to the directory; relative to the Instance root. eg ./InstanceName/.

  • name (str) – The new name for the directory, do not include the path.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

async rename_file(file_path: str, file_name: str, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Changes the name of a file.

Parameters:

  • file_path (str) – Path to the file; relative to the Instance root. eg ./InstanceName/.

  • file_name (str) – The new name for the file; no path needed. (eg. “renamed_myfile.txt”)

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

async trash_directory(file_path: str, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Moves a directory to the trash, directories must be trashed before they can be emptied.

Note

See FileManagerPlugin.empty_trash() to remove the files from the trash directory.

Parameters:

  • file_path (str) – Path to the file; relative to the Instance root. eg ./InstanceName/.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

async trash_file(file_path: str, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Moves a file to the trash, files must be trashed before they can be emptied.

Note

See FileManagerPlugin.empty_trash() to remove the files from the trash directory.

Parameters:

  • file_path (str) – Path to the file; relative to the Instance root. eg ./InstanceName/.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

async write_file_chunk(file_path: str, data: str, offset: int, append: bool = False, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Write data to a file with an offset.

Parameters:

  • file_path (str) – Path to the file; relative to the Instance root. eg ./InstanceName/.

  • data (str) – The binary data to be written.

  • index (int) – The position offset from start of file.

  • append (bool) – Appends the data to the end of the file, default is False.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

Local File Backup Module

class ampapi.LocalFileBackupPlugin[source]

Bases: Base

Contains all functions for any /API/LocalFileBackupPlugin/ API endpoints.

async delete_from_s3(backup_id: str, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Delete a backup from S3.

Parameters:

  • backup_id (str) – The backup ID to delete.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

async delete_local_backup(backup_id: str) → None[source]

This function is a coroutine.

Delete a local backup.

Parameters:

backup_id (str) – The backup ID to delete.

Return type:

None

async download_from_s3(backup_id: str, format_data: bool | None = None) → RunningTask[source]

This function is a coroutine.

Download a backup from S3.

Parameters:

  • backup_id (str) – The backup ID to download.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a RunningTask dataclass.

Return type:

RunningTask

async get_backups(format_data: bool | None = None) → list[Backup][source]

This function is a coroutine.

Get a list of Backups.

Parameters:

format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a list of Backup dataclasses.

Return type:

list[Backup]

async refresh_backup_list() → None[source]

This function is a coroutine.

Refresh the list of backups.

Return type:

None

async restore_backup(backup_id: str, delete_existing_data: bool = False, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Restore a backup.

Parameters:

  • backup_id (str) – The backup ID to restore.

  • delete_existing_data (bool, optional) – Delete the backup after restoring, defaults to False.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

async set_backup_sticky(backup_id: str, sticky: bool = False) → None[source]

This function is a coroutine.

Set a backup as sticky.

Parameters:

  • backup_id (str) – The backup ID to set as sticky.

  • sticky (bool, optional) – Set the backup as sticky, defaults to False.

Return type:

None

async take_backup(name: str, description: str, sticky: bool = False, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Takes a backup of the AMP Server.

Parameters:

  • name (str) – The name of the backup.

  • description (str) – Brief description of why or what the backup is for.

  • sticky (bool, optional) – Sticky backups won’t be deleted to make room for automatic backups, defaults to False.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a ActionResult dataclass.

Return type:

ActionResult

async upload_to_s3(backup_id: str, format_data: bool | None = None) → RunningTask[source]

This function is a coroutine.

Upload a backup to S3.

Parameters:

  • backup_id (str) – The backup ID to upload.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a RunningTask dataclass.

Return type:

RunningTask

Minecraft Module

class ampapi.MinecraftModule[source]

Bases: Base

Contains all Endpoints for /API/MinecraftModule/.

static mc_only(func: Callable[Concatenate[D, T], Coroutine[None, None, F]]) → Callable[Concatenate[D, T], Coroutine[None, None, F]][source]

Checks the module property and raises ConnectionError if the Instance is Offline or Stopped.

Raises:

RuntimeError – This API call is only available on ADS instances.

mc_accept_eula() → bool[source]

This function is a coroutine.

Accept the EULA summary.

Returns:

On success returns a Bool.

Return type:

bool

mc_add_op_entry(user_or_uuid: str, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Add an entry to the OP list.

Parameters:

user_or_uuid (str) – The Minecraft UUID or Username.

Returns:

On success returns an ActionResult dataclass.

Return type:

ActionResult

mc_add_to_whitelist(user_or_uuid: str, format_data: bool | None = None) → ActionResult[source]

This function is a coroutine.

Add a user to the whitelist.

Parameters:

user_or_uuid (str) – The Minecraft UUID or Username.

Returns:

On success returns an ActionResult dataclass.

Return type:

ActionResult

mc_buk_get_categories() → list[BukkitCategories][source]

This function is a coroutine.

Get Bukkit categories.

Note

CATEGORIES: ‘Bungee - Spigot’, ‘Bungee - Proxy’, ‘Spigot’, ‘Transportation’, ‘Chat’, ‘Tools and Utilities’, ‘Misc’, ‘Libraries / APIs’

Returns:

On success returns a list of BukkitCategories dataclasses.

Return type:

list[BukkitCategories]

mc_buk_get_installed_plugins(format_data: bool | None = None) → list[BukkitPlugin][source]

This function is a coroutine.

Get Bukkit installed plugins.

Parameters:

format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a list of BukkitPlugin dataclasses.

Return type:

list[BukkitPlugin]

mc_buk_get_install_update_plugin(plugin_id: int, format_data: bool | None = None) → RunningTask[source]

This function is a coroutine.

Get update for Bukkit plugin.

Parameters:

  • plugin_id (int) – The plugin ID. See BukkitPlugin for the ID value.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a RunningTask dataclass.

Return type:

RunningTask

mc_buk_get_plugin_info(plugin_id: int, format_data: bool | None = None) → Any[source]

This function is a coroutine.

Get Bukkit plugin info.

Parameters:

  • plugin_id (int) – The plugin ID. See BukkitPlugin for the ID value.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

UNK data returned by the API.

Return type:

Any

mc_buk_get_plugins_for_category(category_id: str, page_number: int = 1, page_size: int = 10, format_data: bool | None = None) → list[BukkitPlugin][source]

This function is a coroutine.

Get Bukkit plugins from category.

Parameters:

  • category_id (str) – The plugin category ID. See -> mc_buk_get_categories()

  • page_number (int) – The page number, default is 1.

  • page_size (int) – The number of entries per page, default is 10.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a list of BukkitPlugin dataclasses.

Return type:

list[BukkitPlugin]

This function is a coroutine.

Get Bukkit popular plugins.

Parameters:

format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a list of BukkitPlugin dataclasses.

Return type:

list[BukkitPlugin]

mc_buk_get_remove_plugin(plugin_id: int) → None[source]

This function is a coroutine.

Remove Bukkit plugin.

Parameters:

plugin_id (int) – The plugin ID. See BukkitPlugin for the ID value.

Return type:

None

This function is a coroutine.

Search for Bukkit plugins.

Parameters:

  • query (str) – The search query.

  • page_number (int) – The page number, default is 1.

  • page_size (int) – The number of entries per page, default is 10.

  • format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a list of BukkitPlugin dataclasses.

Return type:

list[BukkitPlugin]

mc_ban_user_by_id(user_id: str) → None[source]

This function is a coroutine.

Ban the specified Minecraft UUID.

Note

This requires the full UUID of the user with the - chars included.

Parameters:

user_id (str) – The Minecraft Users UUID.

Return type:

None

mc_clear_inventory_by_id(user_id: str) → None[source]

This function is a coroutine.

Clear a players inventory.

Note

This requires the full UUID of the user with the - chars included.

Parameters:

user_id (str) – The Minecraft Users UUID.

Return type:

None

mc_get_failure_reason() → str[source]

This function is a coroutine.

Get the Server failure reason, if any.

Returns:

On success returns a string representation of the failure reason.

Return type:

str

mc_get_head_by_uuid(user_id: str) → str[source]

This function is a coroutine.

Get a skin as a base64 string.

Note

This requires the full UUID of the user with the - chars included.

Parameters:

user_id (str) – The Minecraft Users UUID.

Returns:

base64 string. eg. (data:image/gif;base64, data)

Return type:

str

mc_get_op_whitelist(format_data: bool | None = None) → OPWhitelist[source]

This function is a coroutine.

Get the OP whitelist.

Parameters:

format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a OPWhitelist dataclass.

Return type:

OPWhitelist

mc_get_whitelist(format_data: bool | None = None) → list[MCUser][source]

This function is a coroutine.

Get the whitelist.

Parameters:

format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a list of MCUser dataclasses.

Return type:

list[MCUser]

mc_kick_user_by_id(user_id: str) → None[source]

This function is a coroutine.

Kick the specified Minecraft Users UUID.

Note

This requires the full UUID of the user with the - chars included.

Parameters:

user_id (str) – The Minecraft Users UUID.

Return type:

None

mc_kill_by_id(user_id: str) → None[source]

This function is a coroutine.

Kill the Minecraft player.

Note

This requires the full UUID of the user with the - chars included.

Parameters:

user_id (str) – The Minecraft Users UUID.

Return type:

None

mc_load_op_list(format_data: bool | None = None) → list[OPList][source]

This function is a coroutine.

Get the OP list.

Parameters:

format_data (Union[bool, None], optional) – Format the JSON response data, by default None.

Returns:

On success returns a list of OPList dataclasses.

Return type:

list[OPList]

mc_remove_op_entry(user: str) → None[source]

This function is a coroutine.

Remove an entry from the OP list.

Note

You can supply a Minecraft UUID (non-trimmed) or Username.

Parameters:

user (str) – The Minecraft UUID or Username.

mc_remove_whitelist_entry(user: str) → None[source]

This function is a coroutine.

Remove a user from the whitelist.

Note

You can supply a Minecraft UUID (non-trimmed) or Username.

Parameters:

user (str) – The Minecraft UUID or Username.

mc_smite_by_id(user_id: str) → None[source]

This function is a coroutine.

Strike a player with lightning

Note

This requires the full UUID of the user with the - chars included.

Parameters:

user_id (str) – The Minecraft Users UUID.

Return type:

None