Our API

API information is also available on Swagger:

https://api.my.vmgen.com/swagger/index.html

The VMgen API interface allows you to exchange data between your application and the VMgen virtual machines. Here, you can find information about our endpoints as well as examples of use.

Turning API on

Before you can use API endpoints, you will need to enable API first.

In order to do it:

1. Log in to the User Portal at https://my.vmgen.com/login

2. Navigate to the Account tab at https://my.vmgen.com/account/settings

3. When in the Settings tab, scroll down to the API section and click on Enable API:

 

Enable API

Account

GET /account

It gets the details related to your account. Remember that a single API key is related to one specific VMgen account.

Available parameters:

none

 

Example:

{
"credit": "1000.00",
"invoicing_model": "after_payment",
"billing_address": "FirstName LastName \\n City \\n Code \\n State \\n Country"
}

GET /invoices

It gets a list of invoices for your account for the current billing period (that is, the current month).

Available parameters:

none

Example:

 {
"id": 0,
"date": "string",
"status": "created",
"total_cost": 0
}

Locations

GET /locations

It gets a list of available locations.

Available parameters:

id

It’s the ID number of a location. Its variation that is used in other endpoints is the parameter location_id

Example:

{
"id": 0,
"name": "string",
"continent": "string"
}

GET /locations/{id}/packages/

It gets a list of available packages for a specific location.

Available parameters:

id

It’s the ID number of a location. Its variation that is used in other endpoints is the parameter location_id

 

Example:

 {
"name": "string",
"vcpus": 0,
"ram_GB": 0,
"disk_GB": 0
}

Packages

GET /locations/{id}/packages/

It gets a list of available packages for a specific location.

Available parameters:

id

It’s the ID number of a location. Its variation that is used in other endpoints is the parameter location_id

 

Example:

 {
"name": "string",
"vcpus": 0,
"ram_GB": 0,
"disk_GB": 0
}

Virtual Machines

GET /virtual-machines

It gets a list of a virtual machines for your account.

Available parameters:

none

 

Example:

 {
"id": 0,
"name": "string",
"fqdn": "string",
"state": "UP",
"uptime": "string",
"ipv4": "string",
"ipv6": "string",
"package": "string"
}

GET /virtual-machines/{id}/configuration

It gets the configuration for a machine of a given ID number.

Available parameters:

id

The ID number of a specific virtual machine of which you want to get configuration.

 

Example:

{
"id": 0,
"name": "string",
"fqdn": "string",
"state": "UP",
"uptime": "string",
"ipv4": "string",
"ipv6": "string",
"package": "string"
}

GET /virtual-machines/{id}/usage

It gets the bandwidth usage of a specific machine identified by its ID number for the current month.

Available parameters:

id

The ID number of a specific virtual machine of which you want to get configuration.

 

Example:

{
"date": "2021-07-13",
"in_MB": 0,
"out_MB": 0
}

GET /virtual-machines/{id}/networking

It gets the networking information for a specific virtual machine (identified by the ID number), such as the IP addresses or reverse DNS properties.

Available parameters:

id

The ID number of a specific virtual machine of which you want to get configuration.

 

Example:

 {
"ip_version": "IPv4",
"ip": "100.200.300.401",
"gateway": "100.200.300.400",
"netmask": "255.255.255.0",
"broadcast": "100.200.300.999",
"rev_dns": "test.machine.vmgen.com",
"is_primary": true
}

GET /virtual-machines/{id}/jobs

It gets a list of recent jobs performed by a specific virtual machine identified by its ID number.

Available parameters:

id

The ID number of a specific virtual machine for which you want to get recent jobs.

 

Example:

 {
"started_at": "2021-07-13T13:59:04.000000Z",
"last_updated_at": "2021-07-13T14:02:05.000000Z",
"event": "power_on",
"status": "unknown"
}

GET /virtual-machines/{id}/status

It gets the current status of a virtual machine of a specific ID.

Available parameters:

id

The ID number of a specific virtual machine for which you want to get recent jobs.

 

Example:

 {
"started_at": "2021-07-13T13:59:04.000000Z",
"last_updated_at": "2021-07-13T14:02:05.000000Z",
"event": "power_on",
"status": "unknown"
}

POST /virtual-machines/

It allows you to deploy a new virtual machine.

After deployment, you will see the VM’s ID number that you can use later to find out what the status of your new VM is.

You can deploy a new virtual machine in 2 ways:

The 1st method:

Use the package parameter. Note that if you do use it, you cannot use such parameters as cpu_cores, ram_GB, and storage_GB as they are ignored.

The 2nd method:

First, make sure you have this method enabled in your account settings. You do not use here the package parameter, but instead, you use the cpu_cores, ram_GB, and storage_GB parameters.

Remember that os_image_id or marketplace_id is required as well as one of the following:

    • root_password
    • ssh_keys_ids
    • ssh_keys

Available parameters:

id

The ID number of a specific virtual machine for which you want to get recent jobs.

 

Example:

 {
"started_at": "2021-07-13T13:59:04.000000Z",
"last_updated_at": "2021-07-13T14:02:05.000000Z",
"event": "power_on",
"status": "unknown"
}

POST /virtual-machines/{id}/command

It lets you run a command for a specific virtual machine identified by its ID number.

    • reboot
    • power on
    • power off

It also returns the parameter job_id which you can use for checking the status of a job of a specific ID:

/jobs/{job_id}

Available parameters:

id

The ID number of a specific virtual machine for which you would like to run a command.

 

Example:

{
"command": "reboot"
}

Success response example:

{
"job_status": "success",
"started_at": "2021-10-20T13:43:12.000000Z"
}

Error response example:

{
"message": "Something went wrong!"
}

POST /virtual-machines/{id}/jobs/{jobId}

It lets you retrieve the staus of a specific job performed by your virtual machine.

    Available parameters:

    id

    The ID number of a specific virtual machine for which you want to get the job status.

    job_id

    The ID number of a specific job performed by your virtual machine.

     

     

    Success Response Example:

    {
"job_status": "success",
"started_at": "2021-10-20T13:43:12.000000Z"
}

    DELETE /virtual-machines/{id}

    It allows to delete a virtual machine without a possibility to restore it (after performing this operation, all data related to the deleted virtual machine will be lost).

      Available parameters:

      id

      The ID number of a specific virtual machine for which you want to get the job status.

      
			
      
			
      
				
				
			
      
				
      
				
				
				
      
				
				
				
      OS Images
      

      GET /os-images
      

      It gets a list available OS images.
      

      Note that id is a unique identifier of a specific OS image and it appears as image_id in other endpoints.
      

      Available parameters:
      

      none
      

       
      

      Example:
      

      {
      "id": 0,
      "os": "string",
      "bits": "string",
      "user_script": true,
      "clound_init": true
      }
      
			
      
			
      
				
				
			
      
				
      
				
				
				
      
				
				
				
      SSH Keys
      

      GET /ssh-keys
      

      If you have SSH keys added to your VMgen account, this command will let you get a lis of those keys.
      

      Available parameters:
      

      none
      

      

      Example:
      

      {
      "id": 0,
      "created_at": "string",
      "name": "string",
      "content": "string"
      }
      

       
      
			
      
			
      
				
				
			
      
				
      
				
				
				
      
				
				
				
      Marketplace
      

      GET /marketplace
      

      It gets a list of marketplace items. You can use the parameter marketplace_id instead of os_id to request deployment of a virtual machine.
      

      Available parameters:
      

      none
      

      

      Example:
      

       {
"id": 0,
"description": "string",
"os_description": "string",
"script_content": "string",
"type": "user_data",
"base64": true
}
      
			
      
			
      
				
				
			
      
				
      
				
				
				
      
				
				
				
      User Data Scripts
      

      GET /user-data-scripts
      

      It gets user data scripts for your account. For deployment of a virtual machine, you can use version_id.
      

      Available parameters:
      

      none
      

      

      Example:
      

      {
      "version_id": 0,
      "type": "user_data",
      "description": "string",
      "content": "string"
      }
      

       
      

      POST /user-data-scripts
      

      Lets you save a new data script.
      

      Available parameters:
      

      none
      

      

      Example:
      

      {
      "description": "string",
      "script_content": "string",
      "base64": true,
      "type": "user_data"
      }
      

      

      Success response example:
      

      {
      "version_id": 99
      }
      

      Error response example:
      

      {
      "message": "Something went wrong!"
      }
      
			
      
			
      
				
				
			
      
				
      
				
				
				
      
				
				
				
      Support Tickets
      

      POST /tickets/
      

      It allows you to create a new support ticket that will be sent to VMgen via email.
      

      Available parameters:
      

      none
      

      

      Example:
      

      {
      "topic": "string",
      "text": "string",
      "reply_to_email": "string"
      }