API Documentation

VM Methods

/virtual_machines

A listing of all virtual machines owned by the current user. Requests to this method must be authenticated with an X-Api-Key header containing the user's API key.

    Returns detailed information on all virtual machines owned by the current user.

    The attributes returned by this API call will be:

    • id The unique ID of the server
    • name The VM's name
    • hostname The VM's hostname
    • state The current state of the VM, in the set of pending, running, halted, halting, starting
    • created_at Timestamp of the VM's creation
    • region_id The VM's region ID (see here)
    • os_template_id The VM's OS template ID (see here)
    • initial_password Default root password for the VM
    • owner_id Internal ID of the user
    • updated_at Timestamp of the last action executed on the VM
    • region_name Descriptive name of the VM's region
    • os_template_name Descriptive name of the VM's operating system
    • ip_allocations A list of IP adress allocations for the current VM
    • package_id The VM's package ID (see here)
    • package_name A descriptive name of the VM's package
    • unbilled_hours Hours that the VM has been operational since the last billing cycle
    • transfer Total allocated transfer, in megabytes
    • transfer_month Remaining transfer for the month

    • Success - 200 OK

      Returns a JSON object containing a list of VMs owned by the current user.

    Example Request

    curl -H 'X-Api-Key: xxxx' https://api.vps247.com/virtual_machines

    Example Response

    [{
    "id": 90,
    "name": "api_test",
    "hostname": "xxxx",
    "state": "running",
    "created_at": "2015-02-21T00:26:55.068Z",
    "region_id": 1,
    "os_template_id": 1,
    "initial_password": "xxxx",
    "owner_id": 1,
    "updated_at": "2015-02-21T00:35:29.192Z",
    "region_name": "New York 1",
    "os_template_name": "Ubuntu 11.10 Server x64",
    "ip_allocations": [{
        "version": 4,
        "first": "123.123.123.123",
        "last": "123.123.123.123",
        "gateway": "123.123.123.1",
        "prefixlen": 25
    }],
    "last_task": {
        "id": 1,
        "name": "VmKill",
        "progress": null,
        "status": "pending"
    },
    "package_id": 1,
    "package_name": "Budget",
    "unbilled_hours": 1,
    "transfer": 22410,
    "month_transfer": 22410,
    "virtual_machine_disk_ids": [
        88
    ]
}]

    Creates a new virtual machine. The POST body should be a JSON string describing the properties of the VM to be created, specifically, a unique name to refer to it by, and the OS template, region, and package IDs.

    Detailed information about the available options can be found by querying the API.

    • Success - 201 Created

    • Failure (Request) - 400 Bad Request

      Sent when the user fails to specify full data in the request body. The response will contain an error message describing what data was missing.

    JSON Schema

    {
    "name" : "xxxx",
    "os_template_id" : 1,
    "region_id" : 2,
    "package_id" : 2,
    "has_private_networking" : true,
    "has_ipv6" : true,
    "ssh_key_ids" : [1] #Optional
 }

    /virtual_machines/{id}

    A specific VM instance.

      Returns information about the specific VM in question, using the same schema as described above.

      • Success - 200 OK

        Returns a JSON object containing detailed information on the VM.

      • Failure (Bad ID) - 404 Not Found

        Sent when the specified ID does not correspond to any VM that the user has access to.

      This will permanently delete the VM in question. In order for the VM deletion to succeed, the VM must first be powered down from the command line, or the control panel.

      • Success - 204 No Content

      • Failure (VM Running) - 400 Bad Request

        Sent when the user attempts to delete a running VM.

      • Failure (Bad ID) - 404 Not Found

        Sent when the specified ID does not correspond to any VM that the user has access to.

      /virtual_machines/{id}/start

      Powers on the specified VM.

      • Success - 200 Accepted

        Returns JSON data describing the current VM.

      Example

      curl -X POST -H 'X-Api-Key: xxxx' https://api.vps247.com/virtual_machines/123/start

      /virtual_machines/{id}/stop

      Sends a shutdown signal to the specified VM, stopping it safely. However, in order to prevent data loss, it is advised that users power off their VMs from the command line instead.

      • Success - 200 Accepted

        Returns JSON data describing the current VM.

      • Failure (State) - 406 Not Acceptable

        Sent if the VM is not in a state where it can be started (i.e., it is already stopped).

      Example

      curl -X POST -H 'X-Api-Key: xxxx' api.vps247.com/virtual_machines/123/stop

      /virtual_machines/{id}/restart

      Sends a restart signal to the specified VM, equivalent to powering it down, and back on again.

      • Success - 200 Accepted

        Returns JSON data describing the current VM.

      • Failure (State) - 406 Not Acceptable

        Sent if the VM is in-between states (i.e., immediately subsequent to another start request).

      Example

      curl -X POST -H 'X-Api-Key: xxxx' https://api.vps247.com/virtual_machines/123/restart

      /virtual_machines/{id}/kill

      Hard-resets the VM. This is equivalent to removing the power from a running computer, and can result in data loss or coruption, and should be used only when the VM is not responding to other inputs.

      • Success - 200 Accepted

        Returns JSON data describing the current VM.

      • Failure (State) - 406 Not Acceptable

        Sent if the VM is in-between states (i.e., immediately subsequent to another kill request).

      Example

      curl -X POST -H 'X-Api-Key: xxxx' https://api.vps247.com/virtual_machines/123/kill