vm.php¶

VM management module for handling snapshots, statistics loading, and CPU graph generation.

API Methods¶

Method	Action	Description
`cpu_graph`	get cpu graph	Returns a base64 encoded PNG image of the CPU usage graph for the specified server.
`create_snapshot`	create snapshot	Creates a new snapshot for the specified server.
`get_snapshot`	get snapshot	Retrieves a list of snapshots and their settings for the specified server.
`load_stats`	load stats	Requests loading of server statistics.
`remove_snapshot`	remove snapshot	Removes a specific snapshot from the server.
`restore_snapshot`	restore snapshot	Restores a server from a previously created snapshot.
`update_restore_settings`	update restore settings	Updates the snapshot/backup rotation and exclusion settings for a server.

vm/cpu_graph¶

Returns a base64 encoded PNG image of the CPU usage graph for the specified server.

HTTP method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `cpu_graph`
token	✅	string	Authentication token.
id	✅	integer	Server ID.

Request example

curl -s "https://invapi.hostkey.com/vm.php" -X POST \
--data "action=cpu_graph" \
--data "token=HOSTKEY_TOKEN" \
--data "id=VALUE"

Success response example

{
"result": "OK",
"image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg=="
}

Error examples

{
"code": -1,
"message": "CPU graph is temporarily unavailable"
}

vm/create_snapshot¶

Creates a new snapshot for the specified server.

HTTP method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `create_snapshot`
token	✅	string	Authentication token.
id	✅	integer	Server ID.
params[name]	✅	string	Snapshot name. Must be between 5 and 30 characters and not start with reserved backup prefixes.
params[type]	❌	string	Snapshot type. Allowed values: snapshot, backup.
params[num_rotation]	❌	integer	Number of rotations for snapshots.
type	❌	string	Snapshot type. Allowed values: snapshot, backup.
num_rotation	❌	integer	Number of rotations for snapshots.
name	✅	string	The name of the snapshot, must be between 5 and 30 characters.

Request example

curl -s "https://invapi.hostkey.com/vm.php" -X POST \
--data "action=create_snapshot" \
--data "token=HOSTKEY_TOKEN" \
--data "id=VALUE" \
--data "params[name]=VALUE" \
--data "name=VALUE"

Success response example

{
"result": "OK",
"module": "vm",
"action": "create_snapshot",
"callback": "7bc29eb23b1b879b21fce509597f07c"
}

Error examples

{
"code": -1,
"message": "Internal server error, please try again later"
}

vm/get_snapshot¶

Retrieves a list of snapshots and their settings for the specified server.

HTTP method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `get_snapshot`
token	✅	string	Authentication token.
id	✅	integer	Server ID.
params[type]	❌	string	Snapshot type. Allowed values: snapshot, backup.
type	✅	string	Type of snapshots to retrieve. Allowed values: snapshot, backup.

Request example

curl -s "https://invapi.hostkey.com/vm.php" -X POST \
--data "action=get_snapshot" \
--data "token=HOSTKEY_TOKEN" \
--data "id=VALUE" \
--data "type=VALUE"

Success response example

{
"result": "OK",
"module": null,
"action": "get_snapshot",
"callback": "7bc29eb23b1b879b21fce509597f07c",
"settings": {
"enable_rotation": true,
"exclude_rotation": [
123,
456
],
"memory_limit": 1024,
"num_max": 5
}
}

Error examples

{
"code": -1,
"message": "failed to request snapshots list for id - error message"
}

vm/remove_snapshot¶

Removes a specific snapshot from the server.

HTTP method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `remove_snapshot`
token	✅	string	Authentication token.
id	✅	integer	Server ID.
params[name]	✅	string	Name of the snapshot to remove.
params[type]	❌	string	Snapshot type. Allowed values: snapshot, backup.
params[openstack_id]	❌	string	OpenStack identifier for the snapshot.
type	❌	string	Snapshot type. Allowed values: snapshot, backup.
openstack_id	❌	string	OpenStack identifier for the snapshot.
name	✅	string	The name of the snapshot to be removed.

Request example

curl -s "https://invapi.hostkey.com/vm.php" -X POST \
--data "action=remove_snapshot" \
--data "token=HOSTKEY_TOKEN" \
--data "id=VALUE" \
--data "params[name]=VALUE" \
--data "name=VALUE"

Success response example

{
"result": "OK",
"module": "vm",
"action": "remove_snapshot",
"callback": "7bc29eb23b1b879b21fce509597f07c"
}

Error examples

{
"code": -1,
"message": "failed to request snapshot removal for id - error message"
}

vm/restore_snapshot¶

Restores a server from a previously created snapshot.

HTTP method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `restore_snapshot`
token	✅	string	Authentication token.
id	✅	integer	Server ID.
params[name]	✅	string	Name of the snapshot to restore from.
type	❌	string	Snapshot type. Allowed values: snapshot, backup.
openstack_id	❌	string	OpenStack identifier for the snapshot.
params[type]	❌	string	Snapshot type. Allowed values: snapshot, backup.
params[openstack_id]	❌	string	OpenStack identifier for the snapshot.
name	✅	string	The name of the snapshot to be restored.

Request example

curl -s "https://invapi.hostkey.com/vm.php" -X POST \
--data "action=restore_snapshot" \
--data "token=HOSTKEY_TOKEN" \
--data "id=VALUE" \
--data "params[name]=VALUE" \
--data "type=snapshot" \
--data "openstack_id=VALUE" \
--data "params[type]=snapshot" \
--data "params[openstack_id]=VALUE" \
--data "name=VALUE"

Success response example

{
"action": "restore_snapshot",
"callback_key": "7bc29eb23b1b879b21fce509597f07c",
"dc_location": "example_location",
"engine": "ovirt",
"openstack_image_id": "",
"status": "pending",
"type": "snapshot"
}

Error examples

{
"code": -1,
"message": "failed to request restore from snapshot for id - error message"
}

vm/load_stats¶

Requests loading of server statistics.

HTTP method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `load_stats`
token	✅	string	Authentication token.
id	✅	integer	Server ID.

Request example

curl -s "https://invapi.hostkey.com/vm.php" -X POST \
--data "action=load_stats" \
--data "token=HOSTKEY_TOKEN" \
--data "id=VALUE"

Success response example

{
"result": "OK",
"module": "vm",
"action": "load_stats",
"callback": "7bc29eb23b1b879b21fce509597f07c"
}

Error examples

{
"code": -1,
"message": "vm/load_stats: failed to request stats for id - error message"
}

vm/update_restore_settings¶

Updates the snapshot/backup rotation and exclusion settings for a server.

HTTP method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `update_restore_settings`
token	✅	string	Authentication token.
id	✅	integer	Server ID.
type	❌	string	Snapshot or backup type. Allowed values: snapshot, backup
enable_rotation	❌	boolean	Whether rotation should be enabled.
exclude_rotation	❌	`array<integer>`	List of snapshot/backup IDs to exclude from rotation.
params[type]	❌	string	Snapshot or backup type. Allowed values: snapshot, backup.
params[enable_rotation]	❌	boolean	Whether rotation should be enabled.
params[exclude_rotation]	❌	`array<integer>`	List of snapshot/backup IDs to exclude from rotation.

Request example

curl -s "https://invapi.hostkey.com/vm.php" -X POST \
--data "action=update_restore_settings" \
--data "token=HOSTKEY_TOKEN" \
--data "id=123" \
--data "type=snapshot" \
--data "enable_rotation=true" \
--data "exclude_rotation[]=101" \
--data "exclude_rotation[]=102"

Success response example

{
"result": "OK",
"module": null,
"action": "update_restore_settings"
}

Error examples

{
"code": -1,
"message": "Error description"
}