NAV
Shell Go Python

Introduction

Welcome to the Virtomize an automation tool for simplifying the creation and mangement for virtual resources on hypervisors.

Installation

Thank you for choosing Virtomize!

The following information will help you installing and configure our software on your hypervisor.

Virtomize comes as a pre-configured virtual appliance which you need to import into your cluster.

You can find the latest release in our download section

import ova

using govc cli tool

# govc env example
export GOVC_USERNAME=administrator@vsphere.local
export GOVC_PASSWORD=vcenterpassword
export GOVC_URL=https://vcenter.example.com/sdk/
export GOVC_INSECURE=true
./govc import.ova -ds=datastore1 -name=virtomize /path/to/virtomize-latest.ova

You can find more Information in the GOVC USAGE

via ESXI/VCenter WebUI

Importing via WebUI sometimes takes very long, up to multiple hours. Therefore, impot via govc and console should be the preferred install method.

login

troubleshooting

configure cluster

Our software uses the hypervisor API to connect to your cluster so make sure the system can reach your hypervisor.

add a new cluster

# example
Username: root
Password: mysecurepassword
Protocoll: HTTPS
# using the domain path
Cluster Address: my-esxi.local
# or some ip address
Cluster Address: 192.168.0.200
Datastore: datastore1
Folder: isos

user and cluster permissions

Our software does not need full rights on your cluster so it makes sense to not use the root or admin user.

VMware

Instead create a new user and a new role with the following rights:

create a role with the following rights and create a user for your cluster using this role

Datastore

Folder

Host

Network

Resource

Virtual machine

Usage

This section gives you a short introduction to your new installed software

logins

The default login is for virtomize appliance:

The default login for installed operating systems:

As always the passwords should be changed to something secure after installation.

create/import a virtual machine

This section will be added soon

profiles

This section will be added soon

create and manage templates

create virtual machine from template

settings

This section will be added soon

user management

callbacks

synchronize

API

Authentication

#### POST
curl -k https://<ipaddress>/rest/v1/token \
     -d "grant_type=client_credentials" \
     -d "client_id=username" \
     -d "client_secret=password"


#### GET
curl -k https://<ipaddress>/rest/v1/token?grant_type=client_credentials&client_id=username&client_secret=password

#### POST
curl -k https://<ipaddress>/rest/v1/destroy \
     -d "access_token=<mytoken>"

Authentication by requesting an OAuth token is required in order to use the API.

A token can be requested via /token and destroyed via /destroy

HTTP Request

GET /token POST /token POST /destroy

Return values and errors

The api always returns a JSON which contains the result of the operation. In case of an error, the JSON contains the errors, as well as some additional information.

An error returns JSON like this:

{
  "errors": [
    "missing parameter: name",
    "missing parameter: iso"
  ],
  "timestamp": 1257894000000000000, 
  "statuscode": 400,
  "instance": "/operatingsystems"
}  

Help


#### GET
curl -k https://<ipaddress>/rest/v1

An overview of the API paths is available under /. No authorization is required for this path.

HTTP Request

GET /

Backup (get)

curl -k -X GET \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/backup

Backup

HTTP Request

GET /backup

HTTP Result

binary : object

Name Type Description
file application/octet-stream file download

Backup (recover)

curl -k -X POST \
	-H "Authorization: Bearer <mytoken>" \
	-F 'backup=@path/to/file' \
	https://<ipaddress>/rest/v1/backup

Recover

HTTP Request

POST /backup

Name Type Description Required
backup application/octet-stream backup file true

HTTP Result

json : object

Name Type Description
msg string general message

Callbacks (create)

curl -k -X POST \
	-H "Authorization: Bearer <mytoken>" \
	-d "callbackurl=<string value>" \
	-d "errorcallbackurl=<string value>" \
	-d "installcallbackurl=<string value>" \
	-d "deletecallbackurl=<string value>" \
	-d "notes=<string value>" \
	https://<ipaddress>/rest/v1/callbacks

Create Callbacks

HTTP Request

POST /callbacks

Name Type Description Required
callbackurl string url used when operation succeeded true
errorcallbackurl string url used when operation failed true
installcallbackurl string url used when installation starts false
deletecallbackurl string url used after system is deleted false
notes string additional notes false

HTTP Result

json : object

Name Type Description
key int callbacks identifier
callbackurl string url used for successful install
errorcallbackurl string url used for errors on install
installcallbackurl string url used when installation starts
deletecallbackurl string url used after system is deleted
notes string additional notes

Callbacks (delete)

curl -k -X DELETE \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/callbacks/<key>

Delete Callbacks

HTTP Request

DELETE /callbacks/:key

Name Type Description Required
key int callback identifier true

HTTP Result

json : object

Name Type Description
msg string general message
key int resource identifier

Callbacks (read all)

curl -k -X GET \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/callbacks

Read All Callbacks

HTTP Request

GET /callbacks

HTTP Result

json : array

Name Type Description
key int callbacks identifier
callbackurl string url used for successful install
errorcallbackurl string url used for errors on install
installcallbackurl string url used when installation starts
deletecallbackurl string url used after system is deleted
notes string additional notes

Callbacks (read)

curl -k -X GET \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/callbacks/<key>

Read Callbacks

HTTP Request

GET /callbacks/:key

Name Type Description Required
key int callback identifier true

HTTP Result

json : object

Name Type Description
key int callbacks identifier
callbackurl string url used for successful install
errorcallbackurl string url used for errors on install
installcallbackurl string url used when installation starts
deletecallbackurl string url used after system is deleted
notes string additional notes

Callbacks (update)

curl -k -X PUT \
	-H "Authorization: Bearer <mytoken>" \
	-d "callbackurl=<string value>" \
	-d "errorcallbackurl=<string value>" \
	-d "installcallbackurl=<string value>" \
	-d "deletecallbackurl=<string value>" \
	-d "notes=<string value>" \
	https://<ipaddress>/rest/v1/callbacks/<key>

Update Callbacks

HTTP Request

PUT /callbacks/:key

Name Type Description Required
callbackurl string url used when operation succeeded true
errorcallbackurl string url used when operation failed true
key int callback identifier true
installcallbackurl string url used when installation starts false
deletecallbackurl string url used after system is deleted false
notes string additional notes false

HTTP Result

json : object

Name Type Description
key int callbacks identifier
callbackurl string url used for successful install
errorcallbackurl string url used for errors on install
installcallbackurl string url used when installation starts
deletecallbackurl string url used after system is deleted
notes string additional notes

Clustercredentials (create)

curl -k -X POST \
	-H "Authorization: Bearer <mytoken>" \
	-d "name=<string value>" \
	-d "username=<string value>" \
	-d "password=<string value>" \
	-d "url=<string value>" \
	-d "insecure=<true|false>" \
	-d "http=<true|false>" \
	https://<ipaddress>/rest/v1/clustercredentials

Create Cluster Credentials

HTTP Request

POST /clustercredentials

Name Type Description Required
name string credentials name true
username string username used for authentication true
password string password used for authentication true
url string url used for authentication true
insecure bool verify TLS if url is https (true or false) false
http bool use http instead of https protocol false

HTTP Result

json : object

Name Type Description
key int credentials identifier
name string credentials name
username string username
url string resource url
insecure bool verify tls connection ( true or false )
http bool use http instead of https protocol

Clustercredentials (delete)

curl -k -X DELETE \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/clustercredentials/<key>

Delete Cluster Credentials

HTTP Request

DELETE /clustercredentials/:key

Name Type Description Required
key int credentials identifier true

HTTP Result

json : object

Name Type Description
msg string general message
key int resource identifier

Clustercredentials (read all)

curl -k -X GET \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/clustercredentials

Read All Cluster Credentials

HTTP Request

GET /clustercredentials

HTTP Result

json : array

Name Type Description
key int credentials identifier
name string credentials name
username string username
url string resource url
insecure bool verify tls connection ( true or false )
http bool use http instead of https protocol

Clustercredentials (read)

curl -k -X GET \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/clustercredentials/<key>

Read Cluster Credentials

HTTP Request

GET /clustercredentials/:key

Name Type Description Required
key int credentials identifier true

HTTP Result

json : object

Name Type Description
key int credentials identifier
name string credentials name
username string username
url string resource url
insecure bool verify tls connection ( true or false )
http bool use http instead of https protocol

Clustercredentials (test)

curl -k -X POST \
	-H "Authorization: Bearer <mytoken>" \
	-d "type=<string value>" \
	https://<ipaddress>/rest/v1/clustercredentials/<key>/test

Test Cluster Credentials

HTTP Request

POST /clustercredentials/:key/test

Name Type Description Required
key int credentials identifier true
type string type of the cluster true

HTTP Result

json : object

Name Type Description
msg string general message
key int resource identifier

Clustercredentials (update)

curl -k -X PUT \
	-H "Authorization: Bearer <mytoken>" \
	-d "name=<string value>" \
	-d "username=<string value>" \
	-d "password=<string value>" \
	-d "url=<string value>" \
	-d "insecure=<true|false>" \
	-d "http=<true|false>" \
	https://<ipaddress>/rest/v1/clustercredentials/<key>

Update Cluster Credentials

HTTP Request

PUT /clustercredentials/:key

Name Type Description Required
name string credentials name true
username string username used for authentication true
password string password used for authentication true
url string url used for authentication true
key int credentials identifier true
insecure bool verify TLS if url is https (true or false) false
http bool use http instead of https protocol false

HTTP Result

json : object

Name Type Description
key int credentials identifier
name string credentials name
username string username
url string resource url
insecure bool verify tls connection ( true or false )
http bool use http instead of https protocol

Clusterdefaults (create)

curl -k -X POST \
	-H "Authorization: Bearer <mytoken>" \
	-d "datacenter=<string value>" \
	-d "ressourcepool=<string value>" \
	-d "host=<string value>" \
	-d "datastore=<string value>" \
	https://<ipaddress>/rest/v1/clusterdefaults

Create Cluster Defaults

HTTP Request

POST /clusterdefaults

Name Type Description Required
datacenter string default datacenter used false
ressourcepool string default ressource pool used false
host string default host used false
datastore string default datastore used false

HTTP Result

json : object

Name Type Description
key int cluster default settings identifier
datacenter string default datacenter
ressourcepool string default ressourcepool
host string default host system
datastore string default datastore

Clusterdefaults (delete)

curl -k -X DELETE \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/clusterdefaults/<key>

Delete Cluster Defaults

HTTP Request

DELETE /clusterdefaults/:key

Name Type Description Required
key int clusterdefaults identifier true

HTTP Result

json : object

Name Type Description
msg string general message
key int resource identifier

Clusterdefaults (read all)

curl -k -X GET \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/clusterdefaults

Read All Cluster Defaults

HTTP Request

GET /clusterdefaults

HTTP Result

json : array

Name Type Description
key int cluster default settings identifier
datacenter string default datacenter
ressourcepool string default ressourcepool
host string default host system
datastore string default datastore

Clusterdefaults (read)

curl -k -X GET \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/clusterdefaults/<key>

Read Cluster Defaults

HTTP Request

GET /clusterdefaults/:key

Name Type Description Required
key int clusterdefaults identifier true

HTTP Result

json : object

Name Type Description
key int cluster default settings identifier
datacenter string default datacenter
ressourcepool string default ressourcepool
host string default host system
datastore string default datastore

Clusterdefaults (update)

curl -k -X PUT \
	-H "Authorization: Bearer <mytoken>" \
	-d "datacenter=<string value>" \
	-d "ressourcepool=<string value>" \
	-d "host=<string value>" \
	-d "datastore=<string value>" \
	https://<ipaddress>/rest/v1/clusterdefaults/<key>

Update Cluster Defaults

HTTP Request

PUT /clusterdefaults/:key

Name Type Description Required
key int clusterdefaults identifier true
datacenter string default datacenter used false
ressourcepool string default ressource pool used false
host string default host used false
datastore string default datastore used false

HTTP Result

json : object

Name Type Description
key int cluster default settings identifier
datacenter string default datacenter
ressourcepool string default ressourcepool
host string default host system
datastore string default datastore

Clusters datastores (read)

curl -k -X GET \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/clusters/<key>/datastores

Read Datastores

HTTP Request

GET /clusters/:key/datastores

Name Type Description Required
key int cluster identifier true

HTTP Result

json : array

Name Type Description
name string datastore name
type string datastore type
capacity int64 datastore capacity
freespace int64 datastore freespace

Clusters imagesync (create)

curl -k -X POST \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/clusters/<key>/imagesync

Sync Images

HTTP Request

POST /clusters/:key/imagesync

Name Type Description Required
key int cluster identifier true

HTTP Result

json : array

Name Type Description
name string image name
oskey int operating system identifier
status string image status

Clusters import (create)

curl -k -X POST \
	-H "Authorization: Bearer <mytoken>" \
	-d "owner=<owner group of the virtual machine>" \
	-d "vmnames[0]=<string value>" \
	-d "vmnames[1]=<string value>" \
	https://<ipaddress>/rest/v1/clusters/<key>/import

Sync Cluster VMto Inventory

HTTP Request

POST /clusters/:key/import

Name Type Description Required
key int key of the cluster true
owner int owner group of the virtual machine true
vmnames []string names of virtual machines to sync from cluster true

HTTP Result

json : array

Name Type Description
name string name of the imported virtual machine
key int resource identifier

Clusters import (read)

curl -k -X GET \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/clusters/<key>/import

Read All Virtual Machines From Cluster

HTTP Request

GET /clusters/:key/import

Name Type Description Required
key int cluster identifier true

HTTP Result

json : array

Name Type Description
name string virtual machine name
cpu int cpu count
ram string ram size in MB
disc string disc size
datastore string used datastore (can be set to auto for auto selecting datastore)
guestid string configured guest id
networks []string network name list
uuid string a unique identifier of the vm on the cluster

Clusters networksync (create)

curl -k -X POST \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/clusters/<key>/networksync

Networks From Cluster

HTTP Request

POST /clusters/:key/networksync

Name Type Description Required
key int cluster identifier true

HTTP Result

json : object

Name Type Description
networkstatus []interfaces.NetStatus network status message list

Clusters synchronize (create)

curl -k -X POST \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/clusters/<key>/synchronize

Defaults From Cluster

HTTP Request

POST /clusters/:key/synchronize

Name Type Description Required
key int cluster identifier true

HTTP Result

json : object

Name Type Description
msg string general message
key int resource identifier

Clusters (create)

curl -k -X POST \
	-H "Authorization: Bearer <mytoken>" \
	-d "name=<string value>" \
	-d "credentialskey=<credentials identifier>" \
	-d "type=<string value>" \
	-d "defaultskey=<cluster defaults identifier>" \
	-d "callbacks[0]=<callback identifier>" \
	-d "callbacks[1]=<callback identifier>" \
	https://<ipaddress>/rest/v1/clusters

Create Clusters

HTTP Request

POST /clusters

Name Type Description Required
name string name of the cluster true
credentialskey int credentials identifier true
type string type of cluster true
defaultskey int cluster defaults identifier false
callbacks []int callback identifier list false

HTTP Result

json : object

Name Type Description
key int cluster identifier
name string cluster name
type string cluster type (e.g: vmware, proxmox, …)
credentialskey int credentials identifier (connection and authentication information)
defaultskey int defaults identifier (default cluster configuration)
callbacks []int callbacks identifier list

Clusters (delete)

curl -k -X DELETE \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/clusters/<key>

Delete Clusters

HTTP Request

DELETE /clusters/:key

Name Type Description Required
key int cluster identifier true

HTTP Result

json : object

Name Type Description
msg string a general result message
key int a resource identifier belonging to the result

Clusters (read all)

curl -k -X GET \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/clusters

Read All Clusters

HTTP Request

GET /clusters

HTTP Result

json : array

Name Type Description
key int cluster identifier
name string cluster name
type string cluster type (e.g: vmware, proxmox, …)
credentialskey int credentials identifier (connection and authentication information)
defaultskey int defaults identifier (default cluster configuration)
callbacks []int callbacks identifier list

Clusters (read)

curl -k -X GET \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/clusters/<key>

Read Clusters

HTTP Request

GET /clusters/:key

Name Type Description Required
key int cluster identifier true

HTTP Result

json : object

Name Type Description
key int cluster identifier
name string cluster name
type string cluster type (e.g: vmware, proxmox, …)
credentialskey int credentials identifier (connection and authentication information)
defaultskey int defaults identifier (default cluster configuration)
callbacks []int callbacks identifier list

Clusters (update)

curl -k -X PUT \
	-H "Authorization: Bearer <mytoken>" \
	-d "name=<string value>" \
	-d "credentialskey=<credentials identifier>" \
	-d "type=<string value>" \
	-d "defaultskey=<cluster defaults identifier>" \
	-d "callbacks[0]=<callback identifier>" \
	-d "callbacks[1]=<callback identifier>" \
	https://<ipaddress>/rest/v1/clusters/<key>

Update Clusters

HTTP Request

PUT /clusters/:key

Name Type Description Required
name string name of the cluster true
credentialskey int credentials identifier true
type string type of cluster true
key int cluster identifier true
defaultskey int cluster defaults identifier false
callbacks []int callback identifier list false

HTTP Result

json : object

Name Type Description
key int cluster identifier
name string cluster name
type string cluster type (e.g: vmware, proxmox, …)
credentialskey int credentials identifier (connection and authentication information)
defaultskey int defaults identifier (default cluster configuration)
callbacks []int callbacks identifier list

Eula (read all)

curl -k -X GET \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/eula

Read EULA

HTTP Request

GET /eula

HTTP Result

json : object

Name Type Description
eulade string end user license agreement german
eulaen string end user license agreement english

Eula accept (create)

curl -k -X POST \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/eula/accept

Accept EULA

HTTP Request

POST /eula/accept

HTTP Result

json : object

Name Type Description
msg string general message

License (delete)

curl -k -X DELETE \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/license

Delete License

HTTP Request

DELETE /license

HTTP Result

json : object

Name Type Description
msg string general message

License (read all)

curl -k -X GET \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/license

Read License

HTTP Request

GET /license

HTTP Result

json : object

Name Type Description
license string license string
customerid string customer identifier
virtualmachines int virtual machine contingent assigned to this license
issued timestamp issue date, timestamp is stored as unix nano timestamp
expires timestamp expiration date, timestamp is stored as unix nano timestamp

License (update)

curl -k -X PUT \
	-H "Authorization: Bearer <mytoken>" \
	-d "license=<string value>" \
	https://<ipaddress>/rest/v1/license

Update License

HTTP Request

PUT /license

Name Type Description Required
license string License string true

HTTP Result

json : object

Name Type Description
license string license string
customerid string customer identifier
virtualmachines int virtual machine contingent assigned to this license
issued timestamp issue date, timestamp is stored as unix nano timestamp
expires timestamp expiration date, timestamp is stored as unix nano timestamp

Logs (create)

curl -k -X POST \
	-H "Authorization: Bearer <mytoken>" \
	-d "services[0]=<string value>" \
	-d "services[1]=<string value>" \
	-d "levels[0]=<string value>" \
	-d "levels[1]=<string value>" \
	-d "starttime=value" \
	-d "endtime=value" \
	-d "pseudonymization=<true|false>" \
	https://<ipaddress>/rest/v1/logs

Read Logs

HTTP Request

POST /logs

Name Type Description Required
services []string services list false
levels []string service log levels false
starttime timestamp log starttime, timestamp is stored as unix nano timestamp false
endtime timestamp log endtime, timestamp is stored as unix nano timestamp false
pseudonymization bool show logs pseudonymized false

HTTP Result

json : object

Name Type Description

Networks getfreeip (read)

curl -k -X GET \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/networks/<key>/getfreeip

Read Free IP

HTTP Request

GET /networks/:key/getfreeip

Name Type Description Required
key int network identifier true

HTTP Result

json : object

Name Type Description
ip string ip address

Networks (create)

curl -k -X POST \
	-H "Authorization: Bearer <mytoken>" \
	-d "name=<string value>" \
	-d "cluster=<cluster id used to identify the cluster>" \
	-d "dhcp=<true|false>" \
	-d "cidr=<string value>" \
	-d "ipreservation=<string value>" \
	-d "gateway=<string value>" \
	-d "dns=<string value>" \
	-d "zonedomain=<string value>" \
	-d "nointernet=<true|false>" \
	https://<ipaddress>/rest/v1/networks

Create Networks

HTTP Request

POST /networks

Name Type Description Required
name string network name used on cluster to identifier the network true
cluster int cluster id used to identify the cluster true
dhcp bool dynamic host control protocol (true or false) true
cidr string classless inter domain routing definition e.g: 10.10.10.10/24 false
ipreservation string a reserved address space for virtomize software to predict the next free IP address false
gateway string gateway IP address or full qualified domain name false
dns string domain name system IP address or full qualified domain name false
zonedomain string sets the domain for whole dns zone false
nointernet bool if network has no internet connection false

HTTP Result

json : object

Name Type Description
key int network identifier
cluster int cluster identifier
name string network name
cidr string classless inter domain routing string
ipreservationcidr string a reserved address space for virtomize software to predict the next free IP address
gateway string gateway ip
zonedomain string global zone domain
dns string domain name server ip
dhcp bool true or false
nointernet bool set to true if network has not internet connection

Networks (delete)

curl -k -X DELETE \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/networks/<key>

Delete Networks

HTTP Request

DELETE /networks/:key

Name Type Description Required
key int network identifier true

HTTP Result

json : object

Name Type Description
msg string a general result message
key int a resource identifier belonging to the result

Networks (read all)

curl -k -X GET \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/networks

Read All Networks

HTTP Request

GET /networks

HTTP Result

json : array

Name Type Description
key int network identifier
cluster int cluster identifier
name string network name
cidr string classless inter domain routing string
ipreservationcidr string a reserved address space for virtomize software to predict the next free IP address
gateway string gateway ip
zonedomain string global zone domain
dns string domain name server ip
dhcp bool true or false
nointernet bool set to true if network has not internet connection

Networks (read)

curl -k -X GET \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/networks/<key>

Read Networks

HTTP Request

GET /networks/:key

Name Type Description Required
key int network identifier true

HTTP Result

json : object

Name Type Description
key int network identifier
cluster int cluster identifier
name string network name
cidr string classless inter domain routing string
ipreservationcidr string a reserved address space for virtomize software to predict the next free IP address
gateway string gateway ip
zonedomain string global zone domain
dns string domain name server ip
dhcp bool true or false
nointernet bool set to true if network has not internet connection

Networks (update)

curl -k -X PUT \
	-H "Authorization: Bearer <mytoken>" \
	-d "name=<string value>" \
	-d "cluster=<cluster id used to identify the cluster>" \
	-d "dhcp=<true|false>" \
	-d "cidr=<string value>" \
	-d "ipreservation=<string value>" \
	-d "gateway=<string value>" \
	-d "dns=<string value>" \
	-d "zonedomain=<string value>" \
	-d "nointernet=<true|false>" \
	https://<ipaddress>/rest/v1/networks/<key>

Update Networks

HTTP Request

PUT /networks/:key

Name Type Description Required
name string network name used on cluster to identifier the network true
cluster int cluster id used to identify the cluster true
dhcp bool dynamic host control protocol (true or false) true
key int network identifier true
cidr string classless inter domain routing definition e.g: 10.10.10.10/24 false
ipreservation string a reserved address space for virtomize software to predict the next free IP address false
gateway string gateway IP address or full qualified domain name false
dns string domain name system IP address or full qualified domain name false
zonedomain string sets the domain for whole dns zone false
nointernet bool if network has no internet connection false

HTTP Result

json : object

Name Type Description
key int network identifier
cluster int cluster identifier
name string network name
cidr string classless inter domain routing string
ipreservationcidr string a reserved address space for virtomize software to predict the next free IP address
gateway string gateway ip
zonedomain string global zone domain
dns string domain name server ip
dhcp bool true or false
nointernet bool set to true if network has not internet connection

Notificationfilter (create)

curl -k -X POST \
	-H "Authorization: Bearer <mytoken>" \
	-d "type=<string value>" \
	-d "to=<string value>" \
	-d "userkey=<user identifier>" \
	-d "filter[0]=<string value>" \
	-d "filter[1]=<string value>" \
	https://<ipaddress>/rest/v1/notificationfilter

Create Notification Filter

HTTP Request

POST /notificationfilter

Name Type Description Required
type string notification type e.g. mail, whatsapp, telegram, etc true
to string to address depending on type email address, phone number, etc true
userkey int user identifier true
filter []string filter for message types info, warning, error, critical true

HTTP Result

json : object

Name Type Description
key int notification filter identifier
userkey int user identifier
type string notification type e.g. mail, whatsapp, telegram, etc
to string to address depending on type email address, phone number, etc
filter []string filter for message types info, warning, error, critical

Notificationfilter (delete)

curl -k -X DELETE \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/notificationfilter/<key>

Delete Notification Filter

HTTP Request

DELETE /notificationfilter/:key

Name Type Description Required
key int notification filter identifier true

HTTP Result

json : object

Name Type Description
msg string general message

Notificationfilter (read all)

curl -k -X GET \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/notificationfilter

Read All Notification Filter

HTTP Request

GET /notificationfilter

HTTP Result

json : array

Name Type Description
key int notification filter identifier
userkey int user identifier
type string notification type e.g. mail, whatsapp, telegram, etc
to string to address depending on type email address, phone number, etc
filter []string filter for message types info, warning, error, critical

Notificationfilter (read)

curl -k -X GET \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/notificationfilter/<key>

Read Notification Filter

HTTP Request

GET /notificationfilter/:key

Name Type Description Required
key int notification filter identifier true

HTTP Result

json : object

Name Type Description
key int notification filter identifier
userkey int user identifier
type string notification type e.g. mail, whatsapp, telegram, etc
to string to address depending on type email address, phone number, etc
filter []string filter for message types info, warning, error, critical

Notificationfilter (update)

curl -k -X PUT \
	-H "Authorization: Bearer <mytoken>" \
	-d "type=<string value>" \
	-d "to=<string value>" \
	-d "userkey=<user identifier>" \
	-d "filter[0]=<string value>" \
	-d "filter[1]=<string value>" \
	https://<ipaddress>/rest/v1/notificationfilter/<key>

Update Notification Filter

HTTP Request

PUT /notificationfilter/:key

Name Type Description Required
key int notification filter identifier true
type string notification type e.g. mail, whatsapp, telegram, etc true
to string to address depending on type email address, phone number, etc true
userkey int user identifier true
filter []string filter for message types info, warning, error, critical true

HTTP Result

json : object

Name Type Description
key int notification filter identifier
userkey int user identifier
type string notification type e.g. mail, whatsapp, telegram, etc
to string to address depending on type email address, phone number, etc
filter []string filter for message types info, warning, error, critical

Operatingsystems (read all)

curl -k -X GET \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/operatingsystems

Read All Operating Systems

HTTP Request

GET /operatingsystems

HTTP Result

json : array

Name Type Description
key int operating system identifier
name string operating system name
minimumcpu int minimum cpu required by this os
minimumram string minimum ram required by this os
minimumdisc string minimum disc required by this os
recommendedcpu int recommended cpu required by this os
recommendedram string recommended ram required by this os
recommendeddisc string recommended disc required by this os

Operatingsystems (read)

curl -k -X GET \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/operatingsystems/<key>

Read Operating Systems

HTTP Request

GET /operatingsystems/:key

Name Type Description Required
key int operating system identifier true

HTTP Result

json : object

Name Type Description
key int operating system identifier
name string operating system name
minimumcpu int minimum cpu required by this os
minimumram string minimum ram required by this os
minimumdisc string minimum disc required by this os
recommendedcpu int recommended cpu required by this os
recommendedram string recommended ram required by this os
recommendeddisc string recommended disc required by this os

Permissiongroups (read all)

curl -k -X GET \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/permissiongroups

Read All Permission Groups

HTTP Request

GET /permissiongroups

HTTP Result

json : array

Name Type Description
name string permission group name
permissions []string permission rights list

Profiles (create)

curl -k -X POST \
	-H "Authorization: Bearer <mytoken>" \
	-d "name=<string value>" \
	-d "cpu=<cpu count>" \
	-d "ram=<string value>" \
	-d "oskey=<operating system identifier>" \
	-d "clusterkey=<cluster identifier>" \
	-d "disc=<string value>" \
	-d "datastore=<string value>" \
	-d "networks[0]=<network identifier>" \
	-d "networks[1]=<network identifier>" \
	https://<ipaddress>/rest/v1/profiles

Create Virtual Machine Profiles

HTTP Request

POST /profiles

Name Type Description Required
name string profile name true
cpu int cpu count true
ram string ram size true
oskey int operating system identifier true
clusterkey int cluster identifier true
disc string disc size true
datastore string datastore true
networks []int network identifier list true

HTTP Result

json : object

Name Type Description
key int profile identifier
name string profile name
cpu int cpu count
ram string ram size
disc string disc size
datastore string used datastore (can be set to auto for auto selecting datastore)
oskey int operating system identifier
clusterkey int cluster identifier
networks []int network identifier list

Profiles (delete)

curl -k -X DELETE \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/profiles/<key>

Delete Virtual Machine Profiles

HTTP Request

DELETE /profiles/:key

Name Type Description Required
key int profile identifier true

HTTP Result

json : object

Name Type Description
msg string a general result message
key int a resource identifier belonging to the result

Profiles (read all)

curl -k -X GET \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/profiles

Read All Virtual Machine Profiles

HTTP Request

GET /profiles

HTTP Result

json : array

Name Type Description
key int profile identifier
name string profile name
cpu int cpu count
ram string ram size
disc string disc size
datastore string used datastore (can be set to auto for auto selecting datastore)
oskey int operating system identifier
clusterkey int cluster identifier
networks []int network identifier list

Profiles (read)

curl -k -X GET \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/profiles/<key>

Read Virtual Machine Profiles

HTTP Request

GET /profiles/:key

Name Type Description Required
key int profile identifier true

HTTP Result

json : object

Name Type Description
key int profile identifier
name string profile name
cpu int cpu count
ram string ram size
disc string disc size
datastore string used datastore (can be set to auto for auto selecting datastore)
oskey int operating system identifier
clusterkey int cluster identifier
networks []int network identifier list

Profiles (update)

curl -k -X PUT \
	-H "Authorization: Bearer <mytoken>" \
	-d "name=<string value>" \
	-d "cpu=<cpu count>" \
	-d "ram=<string value>" \
	-d "oskey=<operating system identifier>" \
	-d "clusterkey=<cluster identifier>" \
	-d "disc=<string value>" \
	-d "datastore=<string value>" \
	-d "networks[0]=<network identifier>" \
	-d "networks[1]=<network identifier>" \
	https://<ipaddress>/rest/v1/profiles/<key>

Update Virtual Machine Profiles

HTTP Request

PUT /profiles/:key

Name Type Description Required
key int profile identifier true
name string profile name true
cpu int cpu count true
ram string ram size true
oskey int operating system identifier true
clusterkey int cluster identifier true
disc string disc size true
datastore string datastore true
networks []int network identifier list true

HTTP Result

json : object

Name Type Description
key int profile identifier
name string profile name
cpu int cpu count
ram string ram size
disc string disc size
datastore string used datastore (can be set to auto for auto selecting datastore)
oskey int operating system identifier
clusterkey int cluster identifier
networks []int network identifier list

Resourcecontingents (create)

curl -k -X POST \
	-H "Authorization: Bearer <mytoken>" \
	-d "usergroupkey=<user group identifier>" \
	-d "cpulimit=<cpu limit>" \
	-d "memorylimit=<string value>" \
	-d "disclimit=<string value>" \
	-d "vmlimit=<virtual machine limit>" \
	https://<ipaddress>/rest/v1/resourcecontingents

Create Resource Contingents

HTTP Request

POST /resourcecontingents

Name Type Description Required
usergroupkey int user group identifier true
cpulimit int cpu limit true
memorylimit string memory limit true
disclimit string disc limit true
vmlimit int virtual machine limit true

HTTP Result

json : object

Name Type Description
key int contingent identifier
usergroupkey int identifier of the user group this contingent belongs to
cpulimit int upper cpu limit
disclimit string upper disc limit
memorylimit string upper memory limit
vmlimit int virtual machine limit

Resourcecontingents (delete)

curl -k -X DELETE \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/resourcecontingents/<key>

Delete Resource Contingents

HTTP Request

DELETE /resourcecontingents/:key

Name Type Description Required
key int contingent identifier true

HTTP Result

json : object

Name Type Description
msg string general message

Resourcecontingents (read all)

curl -k -X GET \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/resourcecontingents

Read All Resource Contingents

HTTP Request

GET /resourcecontingents

HTTP Result

json : array

Name Type Description
key int contingent identifier
usergroupkey int identifier of the user group this contingent belongs to
cpulimit int upper cpu limit
disclimit string upper disc limit
memorylimit string upper memory limit
vmlimit int virtual machine limit

Resourcecontingents (read)

curl -k -X GET \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/resourcecontingents/<key>

Read Resource Contingents

HTTP Request

GET /resourcecontingents/:key

Name Type Description Required
key int contingent identifier true

HTTP Result

json : object

Name Type Description
key int contingent identifier
usergroupkey int identifier of the user group this contingent belongs to
cpulimit int upper cpu limit
disclimit string upper disc limit
memorylimit string upper memory limit
vmlimit int virtual machine limit

Resourcecontingents (update)

curl -k -X PUT \
	-H "Authorization: Bearer <mytoken>" \
	-d "usergroupkey=<user group identifier>" \
	-d "cpulimit=<cpu limit>" \
	-d "memorylimit=<string value>" \
	-d "disclimit=<string value>" \
	-d "vmlimit=<virtual machine limit>" \
	https://<ipaddress>/rest/v1/resourcecontingents/<key>

Update Resource Contingents

HTTP Request

PUT /resourcecontingents/:key

Name Type Description Required
key int contingent identifier true
usergroupkey int user group identifier true
cpulimit int cpu limit true
memorylimit string memory limit true
disclimit string disc limit true
vmlimit int virtual machine limit true

HTTP Result

json : object

Name Type Description
key int contingent identifier
usergroupkey int identifier of the user group this contingent belongs to
cpulimit int upper cpu limit
disclimit string upper disc limit
memorylimit string upper memory limit
vmlimit int virtual machine limit

Servicesettings (read all)

curl -k -X GET \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/servicesettings

Read Service Settings

HTTP Request

GET /servicesettings

HTTP Result

json : object

Name Type Description
core string core service log level
inventory string inventory service log level
integrator string integrator service log level
configurator string configurator service log level
ipxebuilder string ipxe-builder service log level
logcollector string logcollector service log level
notification string notification service log level

Servicesettings (update)

curl -k -X PUT \
	-H "Authorization: Bearer <mytoken>" \
	-d "service=<string value>" \
	-d "loglevel=<string value>" \
	https://<ipaddress>/rest/v1/servicesettings

Update Service Settings

HTTP Request

PUT /servicesettings

Name Type Description Required
service string service name true
loglevel string service log level true

HTTP Result

json : object

Name Type Description
loglevel string service log level

Setting (delete)

curl -k -X DELETE \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/setting

Delete Setting

HTTP Request

DELETE /setting

HTTP Result

json : object

Name Type Description
msg string general message

Setting (read all)

curl -k -X GET \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/setting

Read Setting

HTTP Request

GET /setting

HTTP Result

json : object

Name Type Description
installtimeout duration installation timeout, duration is stored as a nanosecond count
regexfilter string regex filter used for datastore auto select
ignorefilter []string ignore filter used to ignore datastores when using auto select
loglevelcore string core service log level
loglevelconfigurator string configurator service log level
loglevelinventory string inventory service log level
loglevelintegrator string integrator service log level
loglevellogcollector string log collector service log level
loglevelnotification string notificaiton service log level
loglevelipxebuilder string ipxe-build service log level

Setting (update)

curl -k -X PUT \
	-H "Authorization: Bearer <mytoken>" \
	-d "regexfilter=<string value>" \
	-d "ignorefilter[0]=<string value>" \
	-d "ignorefilter[1]=<string value>" \
	-d "installtimeout=value" \
	-d "loglevelcore=<string value>" \
	-d "loglevelconfigurator=<string value>" \
	-d "loglevelinventory=<string value>" \
	-d "loglevelintegrator=<string value>" \
	-d "loglevellogcollector=<string value>" \
	-d "loglevelnotification=<string value>" \
	-d "loglevelipxebuilder=<string value>" \
	https://<ipaddress>/rest/v1/setting

Update Setting

HTTP Request

PUT /setting

Name Type Description Required
regexfilter string regex filter used for datastore=auto mode false
ignorefilter []string ignore filters used for datastore=auto mode false
installtimeout duration installation timeout in minutes (default 40m), duration is stored as a nanosecond count false
loglevelcore string core service log level false
loglevelconfigurator string configurator service log level false
loglevelinventory string inventory service log level false
loglevelintegrator string integrator service log level false
loglevellogcollector string log collector service log level false
loglevelnotification string notification service log level false
loglevelipxebuilder string ipxe-build service log level false

HTTP Result

json : object

Name Type Description
installtimeout duration installation timeout, duration is stored as a nanosecond count
regexfilter string regex filter used for datastore auto select
ignorefilter []string ignore filter used to ignore datastores when using auto select
loglevelcore string core service log level
loglevelconfigurator string configurator service log level
loglevelinventory string inventory service log level
loglevelintegrator string integrator service log level
loglevellogcollector string log collector service log level
loglevelnotification string notificaiton service log level
loglevelipxebuilder string ipxe-build service log level

Setting notification (delete)

curl -k -X DELETE \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/setting/notification

Delete Notification Setting

HTTP Request

DELETE /setting/notification

HTTP Result

json : object

Name Type Description
msg string general message

Setting notification (read all)

curl -k -X GET \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/setting/notification

Read Notification Setting

HTTP Request

GET /setting/notification

HTTP Result

json : object

Name Type Description
mailserver string mailserver used for notifications
mailport int mailserver port used for notifications
username string username used for authentication

Setting notification (update)

curl -k -X PUT \
	-H "Authorization: Bearer <mytoken>" \
	-d "mailserver=<string value>" \
	-d "mailport=<port number used for mailserver e.g. 465>" \
	-d "username=<string value>" \
	-d "password=<string value>" \
	https://<ipaddress>/rest/v1/setting/notification

Update Notification Setting

HTTP Request

PUT /setting/notification

Name Type Description Required
mailserver string mailserver used for sending notifications via e-mail false
mailport int port number used for mailserver e.g. 465 false
username string username used for authentication false
password string password used for authentication (stored encrypted) false

HTTP Result

json : object

Name Type Description
mailserver string mailserver used for notifications
mailport int mailserver port used for notifications
username string username used for authentication

Token (create)

curl -k -X POST \
	-H "Authorization: Bearer <mytoken>" \
	-d "grand_type=<string value>" \
	-d "client_id=<string value>" \
	-d "client_secret=<string value>" \
	https://<ipaddress>/rest/v1/token

request oauth token

HTTP Request

POST /token

Name Type Description Required
grand_type string client_credentials false
client_id string client ID false
client_secret string client secret false

HTTP Result

json : object

Name Type Description
access_token string token
expires_in int expiration in seconds
token_type string token type

Token (destroy)

curl -k -X POST \
	-H "Authorization: Bearer <mytoken>" \
	-d "access_token=<string value>" \
	https://<ipaddress>/rest/v1/destroy

destroy oauth token

HTTP Request

POST /destroy

Name Type Description Required
access_token string token false

HTTP Result

json : object

Name Type Description
message string response message

Update (create)

curl -k -X POST \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/update

Perform Update

HTTP Request

POST /update

HTTP Result

json : object

Name Type Description
currentversion string the current software version
availableversion string available update version
updateavailable bool true if update is possible false otherwise
scheduled bool true if update is scheduled false otherwise

Update (read all)

curl -k -X GET \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/update

Read Update

HTTP Request

GET /update

HTTP Result

json : object

Name Type Description
currentversion string the current software version
availableversion string available update version
updateavailable bool true if update is possible false otherwise

Usergroups (create)

curl -k -X POST \
	-H "Authorization: Bearer <mytoken>" \
	-d "groupname=<string value>" \
	-d "users[0]=<of users in this group>" \
	-d "users[1]=<of users in this group>" \
	-d "networks[0]=<of networks visible to the group>" \
	-d "networks[1]=<of networks visible to the group>" \
	-d "clusters[0]=<of clusters visible to the group>" \
	-d "clusters[1]=<of clusters visible to the group>" \
	https://<ipaddress>/rest/v1/usergroups

Create User Groups

HTTP Request

POST /usergroups

Name Type Description Required
groupname string username true
users []int list of users in this group true
networks []int list of networks visible to the group false
clusters []int list of clusters visible to the group false

HTTP Result

json : object

Name Type Description
key int user identifier
groupname string username
users []int list of users belonging to this group
networks []int list of networks visibile to the group
clusters []int list of clusters visible to the group

Usergroups (delete)

curl -k -X DELETE \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/usergroups/<key>

Delete User Groups

HTTP Request

DELETE /usergroups/:key

Name Type Description Required
key int user groups identifier true

HTTP Result

json : object

Name Type Description
msg string general message

Usergroups (read all)

curl -k -X GET \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/usergroups

Read All User Groups

HTTP Request

GET /usergroups

HTTP Result

json : array

Name Type Description
key int user identifier
groupname string username
users []int list of users belonging to this group
networks []int list of networks visibile to the group
clusters []int list of clusters visible to the group

Usergroups (read)

curl -k -X GET \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/usergroups/<key>

Read User Groups

HTTP Request

GET /usergroups/:key

Name Type Description Required
key int user groups identifier true

HTTP Result

json : object

Name Type Description
key int user identifier
groupname string username
users []int list of users belonging to this group
networks []int list of networks visibile to the group
clusters []int list of clusters visible to the group

Usergroups (update)

curl -k -X PUT \
	-H "Authorization: Bearer <mytoken>" \
	-d "groupname=<string value>" \
	-d "users[0]=<of users in this group>" \
	-d "users[1]=<of users in this group>" \
	-d "networks[0]=<of networks visible to the group>" \
	-d "networks[1]=<of networks visible to the group>" \
	-d "clusters[0]=<of clusters visible to the group>" \
	-d "clusters[1]=<of clusters visible to the group>" \
	https://<ipaddress>/rest/v1/usergroups/<key>

Update User Groups

HTTP Request

PUT /usergroups/:key

Name Type Description Required
key int user group identifier true
groupname string username true
users []int list of users in this group true
networks []int list of networks visible to the group false
clusters []int list of clusters visible to the group false

HTTP Result

json : object

Name Type Description
key int user identifier
groupname string username
users []int list of users belonging to this group
networks []int list of networks visibile to the group
clusters []int list of clusters visible to the group

Users permissions (update)

curl -k -X PUT \
	-H "Authorization: Bearer <mytoken>" \
	-d "permissiongroups[0]=<string value>" \
	-d "permissiongroups[1]=<string value>" \
	https://<ipaddress>/rest/v1/users/<key>/permissions

Update User Permissions

HTTP Request

PUT /users/:key/permissions

Name Type Description Required
key int user identifier true
permissiongroups []string permissions true

HTTP Result

json : object

Name Type Description
key int user identifier
username string username
permissions []string list of all individual permissions
permissionsgroups []string list of grouped permission

Users (create)

curl -k -X POST \
	-H "Authorization: Bearer <mytoken>" \
	-d "username=<string value>" \
	-d "password=<string value>" \
	https://<ipaddress>/rest/v1/users

Create Users

HTTP Request

POST /users

Name Type Description Required
username string username true
password string password true

HTTP Result

json : object

Name Type Description
key int user identifier
username string username
permissions []string list of all individual permissions
permissionsgroups []string list of grouped permission

Users (delete)

curl -k -X DELETE \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/users/<key>

Delete Users

HTTP Request

DELETE /users/:key

Name Type Description Required
key int user identifier true

HTTP Result

json : object

Name Type Description
msg string general message

Users (read all)

curl -k -X GET \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/users

Read All Users

HTTP Request

GET /users

HTTP Result

json : array

Name Type Description
key int user identifier
username string username
permissions []string list of all individual permissions
permissionsgroups []string list of grouped permission

Users (read)

curl -k -X GET \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/users/<key>

Read Users

HTTP Request

GET /users/:key

Name Type Description Required
key int user identifier true

HTTP Result

json : object

Name Type Description
key int user identifier
username string username
permissions []string list of all individual permissions
permissionsgroups []string list of grouped permission

Users (update)

curl -k -X PUT \
	-H "Authorization: Bearer <mytoken>" \
	-d "username=<string value>" \
	-d "password=<string value>" \
	https://<ipaddress>/rest/v1/users/<key>

Update Users

HTTP Request

PUT /users/:key

Name Type Description Required
key int user identifier true
username string username true
password string password true

HTTP Result

json : object

Name Type Description
key int user identifier
username string username
permissions []string list of all individual permissions
permissionsgroups []string list of grouped permission

Users current (read all)

curl -k -X GET \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/users/current

Read Current User

HTTP Request

GET /users/current

HTTP Result

json : object

Name Type Description
key int user identifier
username string username
permissions []string list of all individual permissions
permissionsgroups []string list of grouped permission

Version (read all)

curl -k -X GET \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/version

Version

HTTP Request

GET /version

HTTP Result

json : object

Name Type Description
version string semantic version string

Virtualmachinenetworks (create)

curl -k -X POST \
	-H "Authorization: Bearer <mytoken>" \
	-d "vmkey=<virtual machine identifier>" \
	-d "netkey=<network identifier>" \
	-d "ip=<string value>" \
	-d "mac=<string value>" \
	-d "domains[0]=<string value>" \
	-d "domains[1]=<string value>" \
	https://<ipaddress>/rest/v1/virtualmachinenetworks

Create Virtual Machine Networks

HTTP Request

POST /virtualmachinenetworks

Name Type Description Required
vmkey int virtual machine identifier true
netkey int network identifier true
ip string ip address false
mac string mac address false
domains []string domains (fqdn) list false

HTTP Result

json : object

Name Type Description
key int virtual machine network identifier
vmkey int virtual machine identifier
netkey int network identifier
ip net.IP assigned ip address
mac string network interface mac address
domains []string domain (fqdn) list

Virtualmachinenetworks (delete)

curl -k -X DELETE \
	-H "Authorization: Bearer <mytoken>" \
	-d "vmkey=<virtual machine identifier>" \
	https://<ipaddress>/rest/v1/virtualmachinenetworks/<key>

Delete Virtual Machine Networks

HTTP Request

DELETE /virtualmachinenetworks/:key

Name Type Description Required
key int virtual machine network identifier true
vmkey int virtual machine identifier true

HTTP Result

json : object

Name Type Description
msg string network specific message
key int virtual machine network identifier
vmkey int virtual machine identifier

Virtualmachinenetworks (read all)

curl -k -X GET \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/virtualmachinenetworks

Read All Virtual Machine Networks

HTTP Request

GET /virtualmachinenetworks

HTTP Result

json : array

Name Type Description
key int virtual machine network identifier
vmkey int virtual machine identifier
netkey int network identifier
ip net.IP assigned ip address
mac string network interface mac address
domains []string domain (fqdn) list

Virtualmachinenetworks (read)

curl -k -X GET \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/virtualmachinenetworks/<key>

Read Virtual Machine Networks

HTTP Request

GET /virtualmachinenetworks/:key

Name Type Description Required
key int virtual machine identifier true

HTTP Result

json : array

Name Type Description
key int virtual machine network identifier
vmkey int virtual machine identifier
netkey int network identifier
ip net.IP assigned ip address
mac string network interface mac address
domains []string domain (fqdn) list

Virtualmachinenetworks (update)

curl -k -X PUT \
	-H "Authorization: Bearer <mytoken>" \
	-d "vmkey=<virtual machine identifier>" \
	-d "netkey=<network identifier>" \
	-d "ip=<string value>" \
	-d "mac=<string value>" \
	-d "domains[0]=<string value>" \
	-d "domains[1]=<string value>" \
	https://<ipaddress>/rest/v1/virtualmachinenetworks/<key>

Update Virtual Machine Networks

HTTP Request

PUT /virtualmachinenetworks/:key

Name Type Description Required
key int virtual machine network identifier true
vmkey int virtual machine identifier true
netkey int network identifier true
ip string ip address false
mac string mac address false
domains []string domains (fqdn) list false

HTTP Result

json : object

Name Type Description
key int virtual machine network identifier
vmkey int virtual machine identifier
netkey int network identifier
ip net.IP assigned ip address
mac string network interface mac address
domains []string domain (fqdn) list

Virtualmachines snapshots (read)

curl -k -X GET \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/virtualmachines/<key>/snapshots

Read All Snap Shots

HTTP Request

GET /virtualmachines/:key/snapshots

Name Type Description Required
key int virtual machine identifier true

HTTP Result

json : array

Name Type Description
vmkey int virtual machine identifier
name string snapshot name
key int hypervisor specific snapshot identifier
id string hypervisor specific internal unique name identifier
description string snapshot description
creationdate timestamp snapshot creation date, timestamp is stored as unix nano timestamp
path string path to the snapshot in the snapshot tree
iscurrent bool indicates if this snapshot is the current snapshot

Virtualmachines (create)

curl -k -X POST \
	-H "Authorization: Bearer <mytoken>" \
	-d "name=<string value>" \
	-d "owner=<the owner of this virtual machine>" \
	-d "cpu=<number of cpus>" \
	-d "ram=<string value>" \
	-d "oskey=<operating system identifier>" \
	-d "clusterkey=<cluster identifier>" \
	-d "disc=<string value>" \
	-d "datastore=<string value>" \
	https://<ipaddress>/rest/v1/virtualmachines

Create Virtual Machines

HTTP Request

POST /virtualmachines

Name Type Description Required
name string name of virtual machine true
owner int the owner of this virtual machine true
cpu int number of cpus true
ram string random access memory size true
oskey int operating system identifier true
clusterkey int cluster identifier true
disc string disc space size true
datastore string datastore used on cluster true

HTTP Result

json : object

Name Type Description
key int virtual machine identifier
owner int the owner of this virtual machine
name string virtual machine name
cpu int cpu count
ram string ram size
disc string disc size
datastore string used datastore (can be set to auto for auto selecting datastore)
oskey int operating system identifier
clusterkey int cluster identifier
networks []int network identifier list
deployed bool indicate whether the virtual machine was deployed on the cluster
scheduleddeletion timestamp data of forced deletion, this is set if when deleting a virtual machine fails to allow the software to try again unit the deletion is forced on this date, timestamp is stored as unix nano timestamp
installparameters int install parameters identifier

Virtualmachines (delete)

curl -k -X DELETE \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/virtualmachines/<key>

Delete Virtual Machines

HTTP Request

DELETE /virtualmachines/:key

Name Type Description Required
key int virtual machine identifier true

HTTP Result

json : object

Name Type Description
msg string general message
key int resource identifier

Virtualmachines (from profile)

curl -k -X POST \
	-H "Authorization: Bearer <mytoken>" \
	-d "owner=<the user group to which contingent the vm is counted>" \
	-d "name=<string value>" \
	-d "cpu=<number of cpus>" \
	-d "ram=<string value>" \
	-d "disc=<string value>" \
	-d "thickprovisioning=<true|false>" \
	https://<ipaddress>/rest/v1/profiles/<key>/createvirtualmachine

Create Virtual Machine From Profile

HTTP Request

POST /profiles/:key/createvirtualmachine

Name Type Description Required
key int profile identifier true
owner int the user group to which contingent the vm is counted true
name string name of virtual machine true
cpu int number of cpus false
ram string random access memory size false
disc string disc space size false
thickprovisioning bool enable thick provisioning, default is thin false

HTTP Result

json : object

Name Type Description
msg string virtual machine status description
status string virtual machine status
key int virtual machine identifier

Virtualmachines (info)

curl -k -X GET \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/virtualmachines/<key>/info

Read Virtual Machine Info

HTTP Request

GET /virtualmachines/:key/info

Name Type Description Required
key int virtual machine identifier true

HTTP Result

json : object

Name Type Description
name string virtual machine name
powerstate string virtual machine power state
ips []string list of ip addresses used by the virtual machine

Virtualmachines (install)

curl -k -X POST \
	-H "Authorization: Bearer <mytoken>" \
	-d "thickprovisioning=<true|false>" \
	-d "locale=<string value>" \
	-d "keyboard=<string value>" \
	-d "password=<string value>" \
	https://<ipaddress>/rest/v1/virtualmachines/<key>/install

Install Virtual Machine

HTTP Request

POST /virtualmachines/:key/install

Name Type Description Required
key int virtual machine identifier true
thickprovisioning bool enable thick provisioning for hard discs, the default is thin provisioning false
locale string set locale string false
keyboard string set keymap string false
password string set root password using a sha-512 hash for linux (e.g. mkpasswd -m sha-512) false

HTTP Result

json : object

Name Type Description
msg string general message
statuscode int http status code

Virtualmachines (poweroff)

curl -k -X POST \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/virtualmachines/<key>/poweroff

Power Off VM

HTTP Request

POST /virtualmachines/:key/poweroff

Name Type Description Required
key int virtual machine identifier true

HTTP Result

json : object

Name Type Description
msg string general message
statuscode int http status code

Virtualmachines (poweron)

curl -k -X POST \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/virtualmachines/<key>/poweron

Power On VM

HTTP Request

POST /virtualmachines/:key/poweron

Name Type Description Required
key int virtual machine identifier true

HTTP Result

json : object

Name Type Description
msg string general message
statuscode int http status code

Virtualmachines (read all)

curl -k -X GET \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/virtualmachines

Read All Virtual Machines

HTTP Request

GET /virtualmachines

HTTP Result

json : array

Name Type Description
key int virtual machine identifier
owner int the owner of this virtual machine
name string virtual machine name
cpu int cpu count
ram string ram size
disc string disc size
datastore string used datastore (can be set to auto for auto selecting datastore)
oskey int operating system identifier
clusterkey int cluster identifier
networks []int network identifier list
deployed bool indicate whether the virtual machine was deployed on the cluster
scheduleddeletion timestamp data of forced deletion, this is set if when deleting a virtual machine fails to allow the software to try again unit the deletion is forced on this date, timestamp is stored as unix nano timestamp
installparameters int install parameters identifier

Virtualmachines (read)

curl -k -X GET \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/virtualmachines/<key>

Read Virtual Machines

HTTP Request

GET /virtualmachines/:key

Name Type Description Required
key int virtual machine identifier true

HTTP Result

json : object

Name Type Description
key int virtual machine identifier
owner int the owner of this virtual machine
name string virtual machine name
cpu int cpu count
ram string ram size
disc string disc size
datastore string used datastore (can be set to auto for auto selecting datastore)
oskey int operating system identifier
clusterkey int cluster identifier
networks []int network identifier list
deployed bool indicate whether the virtual machine was deployed on the cluster
scheduleddeletion timestamp data of forced deletion, this is set if when deleting a virtual machine fails to allow the software to try again unit the deletion is forced on this date, timestamp is stored as unix nano timestamp
installparameters int install parameters identifier

Virtualmachines (update)

curl -k -X PUT \
	-H "Authorization: Bearer <mytoken>" \
	-d "name=<string value>" \
	-d "owner=<new owner group of the virtual machine>" \
	-d "cpu=<number of cpus>" \
	-d "ram=<string value>" \
	-d "oskey=<operating system identifier>" \
	-d "clusterkey=<cluster identifier>" \
	-d "disc=<string value>" \
	-d "datastore=<string value>" \
	https://<ipaddress>/rest/v1/virtualmachines/<key>

Update Virtual Machines

HTTP Request

PUT /virtualmachines/:key

Name Type Description Required
name string name of virtual machine true
owner int new owner group of the virtual machine true
cpu int number of cpus true
ram string random access memory size true
oskey int operating system identifier true
clusterkey int cluster identifier true
disc string disc space size true
datastore string datastore used on cluster true
key int virtual machine identifier true

HTTP Result

json : object

Name Type Description
key int virtual machine identifier
owner int the owner of this virtual machine
name string virtual machine name
cpu int cpu count
ram string ram size
disc string disc size
datastore string used datastore (can be set to auto for auto selecting datastore)
oskey int operating system identifier
clusterkey int cluster identifier
networks []int network identifier list
deployed bool indicate whether the virtual machine was deployed on the cluster
scheduleddeletion timestamp data of forced deletion, this is set if when deleting a virtual machine fails to allow the software to try again unit the deletion is forced on this date, timestamp is stored as unix nano timestamp
installparameters int install parameters identifier

Virtualmachines :vmkey snapshots restore (create)

curl -k -X POST \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/virtualmachines/:vmkey/snapshots/<key>/restore

Restore Snap Shots

HTTP Request

POST /virtualmachines/:vmkey/snapshots/:key/restore

Name Type Description Required
vmkey int virtual machine identifier true
key int snapshot key true

HTTP Result

json : object

Name Type Description
msg string general message
statuscode int http status code

Virtualmachines :vmkey snapshots (create)

curl -k -X POST \
	-H "Authorization: Bearer <mytoken>" \
	-d "name=<string value>" \
	-d "description=<string value>" \
	-d "includememory=<true|false>" \
	https://<ipaddress>/rest/v1/virtualmachines/:vmkey/snapshots

Create Snap Shots

HTTP Request

POST /virtualmachines/:vmkey/snapshots

Name Type Description Required
vmkey int virtual machine identifier true
name string snapshot name true
description string snapshot description false
includememory bool Include memory state false

HTTP Result

json : object

Name Type Description
vmkey int virtual machine identifier
name string snapshot name
key int hypervisor specific snapshot identifier
id string hypervisor specific internal unique name identifier
description string snapshot description
creationdate timestamp snapshot creation date, timestamp is stored as unix nano timestamp
path string path to the snapshot in the snapshot tree
iscurrent bool indicates if this snapshot is the current snapshot

Virtualmachines :vmkey snapshots (delete)

curl -k -X DELETE \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/virtualmachines/:vmkey/snapshots/<key>

Delete Snap Shots

HTTP Request

DELETE /virtualmachines/:vmkey/snapshots/:key

Name Type Description Required
vmkey int virtual machine identifier true
key int snapshot key true

HTTP Result

json : object

Name Type Description
msg string general message
statuscode int http status code

Virtualmachines :vmkey snapshots (read)

curl -k -X GET \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/virtualmachines/:vmkey/snapshots/<key>

Read Snap Shots

HTTP Request

GET /virtualmachines/:vmkey/snapshots/:key

Name Type Description Required
vmkey int virtual machine identifier true
key int snapshot key true

HTTP Result

json : object

Name Type Description
vmkey int virtual machine identifier
name string snapshot name
key int hypervisor specific snapshot identifier
id string hypervisor specific internal unique name identifier
description string snapshot description
creationdate timestamp snapshot creation date, timestamp is stored as unix nano timestamp
path string path to the snapshot in the snapshot tree
iscurrent bool indicates if this snapshot is the current snapshot

Virtualmachines :vmkey snapshots (update)

curl -k -X PUT \
	-H "Authorization: Bearer <mytoken>" \
	-d "description=<string value>" \
	-d "name=<string value>" \
	https://<ipaddress>/rest/v1/virtualmachines/:vmkey/snapshots/<key>

Update Snap Shots

HTTP Request

PUT /virtualmachines/:vmkey/snapshots/:key

Name Type Description Required
vmkey int virtual machine identifier true
key int snapshot key true
description string snapshot description false
name string snapshot name false

HTTP Result

json : object

Name Type Description
msg string general message
statuscode int http status code

Virtualmachines :vmkey snapshots updatehardware (create)

curl -k -X POST \
	-H "Authorization: Bearer <mytoken>" \
	-d "keys[0]=<snapshot key>" \
	-d "keys[1]=<snapshot key>" \
	https://<ipaddress>/rest/v1/virtualmachines/:vmkey/snapshots/updatehardware

Apply Current Hardware To Snap Shots

HTTP Request

POST /virtualmachines/:vmkey/snapshots/updatehardware

Name Type Description Required
vmkey int virtual machine identifier true
keys []int snapshot key true

HTTP Result

json : object

Name Type Description
msg string general message
statuscode int http status code

Virtualmachines parameter (read)

curl -k -X GET \
	-H "Authorization: Bearer <mytoken>" \
	https://<ipaddress>/rest/v1/virtualmachines/parameter/<key>

Read Install Parameters

HTTP Request

GET /virtualmachines/parameter/:key

Name Type Description Required
key int installation parameter identifier true

HTTP Result

json : object

Name Type Description
key int installation parameter identifier
locale string set locale string
keyboard string set keymap string
password string password hash (sha-512) used for installation