Servers

Build a server

POST/servers/{serverId}/build

Install an operating system template on a created server. The install is queued; follow it through the queue endpoint.

Request

Authorization
Provide your bearer token in the Authorization header when making requests to protected resources.
Example: Authorization: Bearer ********************
Path Params#
serverIdinteger#required

A valid server ID as shown in VirtFusion.

Example: 9
Body Paramsapplication/json#

Template and installation options. operatingSystemId is a template ID from the templates endpoint, sshKeys lists SSH key IDs, and email sends the login details to the owner.

object
operatingSystemIdinteger#required

A valid operating system template ID.

namestring#

Server name.

hostnamestring#

Server Hostname.

sshKeysarray[integer]#

An array of SSH keys.

vncboolean#

Enable/disable.

ipv6boolean#

Enable/disable.

emailboolean#

Enable/disable.

timezonestring#

Optional guest timezone, e.g. Europe/London, applied through cloud-init where the template supports it.

swapnumber#

Values of 256, 512, 768, 1, 1.5, 2, 3, 4, 5,6 8

Example
{
    "operatingSystemId": 1,
    "name": "server 1",
    "hostname": "server1.domain.com",
    "sshKeys": [
        1,
        2,
        3,
        4
    ],
    "vnc": false,
    "ipv6": false,
    "swap": 512,
    "email": true
}

Request Code Samples

curl --location --request POST 'https://cp.domain.com/api/v1/servers/9/build' \
--header 'Authorization: Bearer <token>' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
    "operatingSystemId": 1,
    "name": "server 1",
    "hostname": "server1.domain.com",
    "sshKeys": [
        1,
        2,
        3,
        4
    ],
    "vnc": false,
    "ipv6": false,
    "swap": 512,
    "email": true
}'
wget --quiet --output-document=- \
  --method=POST \
  --header='Authorization: Bearer <token>' \
  --header='Accept: application/json' \
  --header='Content-Type: application/json' \
  --body-data='{
    "operatingSystemId": 1,
    "name": "server 1",
    "hostname": "server1.domain.com",
    "sshKeys": [
        1,
        2,
        3,
        4
    ],
    "vnc": false,
    "ipv6": false,
    "swap": 512,
    "email": true
}' \
  'https://cp.domain.com/api/v1/servers/9/build'
http POST 'https://cp.domain.com/api/v1/servers/9/build' \
  'Authorization: Bearer <token>' \
  'Accept: application/json' \
  'Content-Type: application/json' <<< '{
    "operatingSystemId": 1,
    "name": "server 1",
    "hostname": "server1.domain.com",
    "sshKeys": [
        1,
        2,
        3,
        4
    ],
    "vnc": false,
    "ipv6": false,
    "swap": 512,
    "email": true
}'
const response = await fetch("https://cp.domain.com/api/v1/servers/9/build", {
    method: "POST",
    headers: {
        "Authorization": "Bearer <token>",
        "Accept": "application/json",
        "Content-Type": "application/json",
    },
    body: JSON.stringify({
        "operatingSystemId": 1,
        "name": "server 1",
        "hostname": "server1.domain.com",
        "sshKeys": [
            1,
            2,
            3,
            4
        ],
        "vnc": false,
        "ipv6": false,
        "swap": 512,
        "email": true
    }),
});

const data = await response.json();
console.log(response.status, data);
import axios from "axios";

const response = await axios({
    method: "post",
    url: "https://cp.domain.com/api/v1/servers/9/build",
    headers: {
        "Authorization": "Bearer <token>",
        "Accept": "application/json",
        "Content-Type": "application/json",
    },
    data: {
        "operatingSystemId": 1,
        "name": "server 1",
        "hostname": "server1.domain.com",
        "sshKeys": [
            1,
            2,
            3,
            4
        ],
        "vnc": false,
        "ipv6": false,
        "swap": 512,
        "email": true
    },
});

console.log(response.status, response.data);
const https = require("https");

const payload = JSON.stringify({
    "operatingSystemId": 1,
    "name": "server 1",
    "hostname": "server1.domain.com",
    "sshKeys": [
        1,
        2,
        3,
        4
    ],
    "vnc": false,
    "ipv6": false,
    "swap": 512,
    "email": true
});

const req = https.request({
    hostname: "cp.domain.com",
    path: "/api/v1/servers/9/build",
    method: "POST",
    headers: {
        "Authorization": "Bearer <token>",
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Content-Length": Buffer.byteLength(payload),
    },
}, (res) => {
    let data = "";
    res.on("data", (chunk) => (data += chunk));
    res.on("end", () => console.log(res.statusCode, JSON.parse(data)));
});

req.on("error", (err) => console.error(err));
req.write(payload);
req.end();
import requests

url = "https://cp.domain.com/api/v1/servers/9/build"
headers = {
    "Authorization": "Bearer <token>",
    "Accept": "application/json",
    "Content-Type": "application/json",
}
payload = {
    "operatingSystemId": 1,
    "name": "server 1",
    "hostname": "server1.domain.com",
    "sshKeys": [
        1,
        2,
        3,
        4,
    ],
    "vnc": False,
    "ipv6": False,
    "swap": 512,
    "email": True,
}

response = requests.request("POST", url, headers=headers, json=payload)

print(response.status_code)
print(response.json())
import http.client
import json

conn = http.client.HTTPSConnection("cp.domain.com")
headers = {
    "Authorization": "Bearer <token>",
    "Accept": "application/json",
    "Content-Type": "application/json",
}
payload = json.dumps({
    "operatingSystemId": 1,
    "name": "server 1",
    "hostname": "server1.domain.com",
    "sshKeys": [
        1,
        2,
        3,
        4,
    ],
    "vnc": False,
    "ipv6": False,
    "swap": 512,
    "email": True,
})

conn.request("POST", "/api/v1/servers/9/build", payload, headers)
response = conn.getresponse()

print(response.status)
print(json.loads(response.read()))
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://cp.domain.com/api/v1/servers/9/build',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => json_encode([
        'operatingSystemId' => 1,
        'name' => 'server 1',
        'hostname' => 'server1.domain.com',
        'sshKeys' => [
            1,
            2,
            3,
            4,
        ],
        'vnc' => false,
        'ipv6' => false,
        'swap' => 512,
        'email' => true,
    ]),
    CURLOPT_HTTPHEADER => array(
        'Authorization: Bearer <token>',
        'Accept: application/json',
        'Content-Type: application/json'
    ),
));

$response = curl_exec($curl);
curl_close($curl);

echo $response;
<?php

require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client();

$response = $client->request('POST', 'https://cp.domain.com/api/v1/servers/9/build', [
    'headers' => [
        'Authorization' => 'Bearer <token>',
        'Accept' => 'application/json',
    ],
    'json' => [
        'operatingSystemId' => 1,
        'name' => 'server 1',
        'hostname' => 'server1.domain.com',
        'sshKeys' => [
            1,
            2,
            3,
            4,
        ],
        'vnc' => false,
        'ipv6' => false,
        'swap' => 512,
        'email' => true,
    ],
]);

echo $response->getStatusCode() . "\n";
echo $response->getBody();
package main

import (
    "fmt"
    "io"
    "net/http"
    "strings"
)

func main() {
    url := "https://cp.domain.com/api/v1/servers/9/build"
    payload := strings.NewReader(`{
    "operatingSystemId": 1,
    "name": "server 1",
    "hostname": "server1.domain.com",
    "sshKeys": [
        1,
        2,
        3,
        4
    ],
    "vnc": false,
    "ipv6": false,
    "swap": 512,
    "email": true
}`)
    req, _ := http.NewRequest("POST", url, payload)
    req.Header.Add("Authorization", "Bearer <token>")
    req.Header.Add("Accept", "application/json")
    req.Header.Add("Content-Type", "application/json")

    res, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer res.Body.Close()

    body, _ := io.ReadAll(res.Body)
    fmt.Println(res.StatusCode, string(body))
}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://cp.domain.com/api/v1/servers/9/build"))
            .header("Authorization", "Bearer <token>")
            .header("Accept", "application/json")
            .header("Content-Type", "application/json")
            .method("POST", HttpRequest.BodyPublishers.ofString("{\"operatingSystemId\":1,\"name\":\"server 1\",\"hostname\":\"server1.domain.com\",\"sshKeys\":[1,2,3,4],\"vnc\":false,\"ipv6\":false,\"swap\":512,\"email\":true}"))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.statusCode());
        System.out.println(response.body());
    }
}
import okhttp3.*;

public class Main {
    public static void main(String[] args) throws Exception {
        OkHttpClient client = new OkHttpClient();

        MediaType json = MediaType.get("application/json");
        RequestBody body = RequestBody.create("{\"operatingSystemId\":1,\"name\":\"server 1\",\"hostname\":\"server1.domain.com\",\"sshKeys\":[1,2,3,4],\"vnc\":false,\"ipv6\":false,\"swap\":512,\"email\":true}", json);

        Request request = new Request.Builder()
            .url("https://cp.domain.com/api/v1/servers/9/build")
            .method("POST", body)
            .addHeader("Authorization", "Bearer <token>")
            .addHeader("Accept", "application/json")
            .build();

        try (Response response = client.newCall(request).execute()) {
            System.out.println(response.code());
            System.out.println(response.body().string());
        }
    }
}
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("POST"), "https://cp.domain.com/api/v1/servers/9/build");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", "<token>");
request.Headers.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
request.Content = new StringContent("{\"operatingSystemId\":1,\"name\":\"server 1\",\"hostname\":\"server1.domain.com\",\"sshKeys\":[1,2,3,4],\"vnc\":false,\"ipv6\":false,\"swap\":512,\"email\":true}", Encoding.UTF8, "application/json");

var response = await client.SendAsync(request);
Console.WriteLine((int)response.StatusCode);
Console.WriteLine(await response.Content.ReadAsStringAsync());
require "net/http"
require "json"

uri = URI("https://cp.domain.com/api/v1/servers/9/build")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer <token>"
request["Accept"] = "application/json"
request["Content-Type"] = "application/json"
request.body = "{\"operatingSystemId\":1,\"name\":\"server 1\",\"hostname\":\"server1.domain.com\",\"sshKeys\":[1,2,3,4],\"vnc\":false,\"ipv6\":false,\"swap\":512,\"email\":true}"

response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
  http.request(request)
end

puts response.code
puts JSON.pretty_generate(JSON.parse(response.body))
import Foundation

var request = URLRequest(url: URL(string: "https://cp.domain.com/api/v1/servers/9/build")!)
request.httpMethod = "POST"
request.setValue("Bearer <token>", forHTTPHeaderField: "Authorization")
request.setValue("application/json", forHTTPHeaderField: "Accept")
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
request.httpBody = "{\"operatingSystemId\":1,\"name\":\"server 1\",\"hostname\":\"server1.domain.com\",\"sshKeys\":[1,2,3,4],\"vnc\":false,\"ipv6\":false,\"swap\":512,\"email\":true}".data(using: .utf8)

let task = URLSession.shared.dataTask(with: request) { data, response, error in
    guard let data = data, error == nil else { print(error ?? "request failed"); return }
    print((response as! HTTPURLResponse).statusCode)
    print(String(data: data, encoding: .utf8) ?? "")
}
task.resume()
// Cargo.toml: reqwest = { version = "0.12", features = ["blocking", "json"] }, serde_json = "1"
use reqwest::blocking::Client;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new();
    let response = client
        .request(reqwest::Method::POST, "https://cp.domain.com/api/v1/servers/9/build")
        .bearer_auth("<token>")
        .header("Accept", "application/json")
        .header("Content-Type", "application/json")
        .body(r#"{
    "operatingSystemId": 1,
    "name": "server 1",
    "hostname": "server1.domain.com",
    "sshKeys": [
        1,
        2,
        3,
        4
    ],
    "vnc": false,
    "ipv6": false,
    "swap": 512,
    "email": true
}"#)
        .send()?;

    println!("{}", response.status());
    let json: serde_json::Value = response.json()?;
    println!("{}", serde_json::to_string_pretty(&json)?);
    Ok(())
}
// Cargo.toml: reqwest = { version = "0.12", features = ["json"] }, tokio = { version = "1", features = ["full"] }, serde_json = "1"
use reqwest::Client;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new();
    let response = client
        .request(reqwest::Method::POST, "https://cp.domain.com/api/v1/servers/9/build")
        .bearer_auth("<token>")
        .header("Accept", "application/json")
        .header("Content-Type", "application/json")
        .body(r#"{
    "operatingSystemId": 1,
    "name": "server 1",
    "hostname": "server1.domain.com",
    "sshKeys": [
        1,
        2,
        3,
        4
    ],
    "vnc": false,
    "ipv6": false,
    "swap": 512,
    "email": true
}"#)
        .send()
        .await?;

    println!("{}", response.status());
    let json: serde_json::Value = response.json().await?;
    println!("{}", serde_json::to_string_pretty(&json)?);
    Ok(())
}
import okhttp3.MediaType.Companion.toMediaType
import okhttp3.OkHttpClient
import okhttp3.Request
import okhttp3.RequestBody.Companion.toRequestBody

fun main() {
    val client = OkHttpClient()
    val body = """{
    "operatingSystemId": 1,
    "name": "server 1",
    "hostname": "server1.domain.com",
    "sshKeys": [
        1,
        2,
        3,
        4
    ],
    "vnc": false,
    "ipv6": false,
    "swap": 512,
    "email": true
}""".toRequestBody("application/json".toMediaType())
    val request = Request.Builder()
        .url("https://cp.domain.com/api/v1/servers/9/build")
        .method("POST", body)
        .addHeader("Authorization", "Bearer <token>")
        .addHeader("Accept", "application/json")
        .build()

    client.newCall(request).execute().use { response ->
        println(response.code)
        println(response.body?.string())
    }
}
// pubspec.yaml: http: ^1.2.0
import 'dart:convert';
import 'package:http/http.dart' as http;

Future<void> main() async {
  final request = http.Request('POST', Uri.parse('https://cp.domain.com/api/v1/servers/9/build'));
  request.headers['Authorization'] = 'Bearer <token>';
  request.headers['Accept'] = 'application/json';
  request.headers['Content-Type'] = 'application/json';
  request.body = r'''{
    "operatingSystemId": 1,
    "name": "server 1",
    "hostname": "server1.domain.com",
    "sshKeys": [
        1,
        2,
        3,
        4
    ],
    "vnc": false,
    "ipv6": false,
    "swap": 512,
    "email": true
}''';

  final response = await http.Response.fromStream(await request.send());
  print(response.statusCode);
  print(const JsonEncoder.withIndent('  ').convert(jsonDecode(response.body)));
}
#include <stdio.h>
#include <curl/curl.h>

int main(void) {
    CURL *curl = curl_easy_init();
    if (!curl) return 1;

    struct curl_slist *headers = NULL;
    headers = curl_slist_append(headers, "Authorization: Bearer <token>");
    headers = curl_slist_append(headers, "Accept: application/json");
    headers = curl_slist_append(headers, "Content-Type: application/json");

    curl_easy_setopt(curl, CURLOPT_URL, "https://cp.domain.com/api/v1/servers/9/build");
    curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "POST");
    curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
    curl_easy_setopt(curl, CURLOPT_POSTFIELDS, "{\"operatingSystemId\":1,\"name\":\"server 1\",\"hostname\":\"server1.domain.com\",\"sshKeys\":[1,2,3,4],\"vnc\":false,\"ipv6\":false,\"swap\":512,\"email\":true}");

    CURLcode result = curl_easy_perform(curl);
    if (result != CURLE_OK) fprintf(stderr, "%s\n", curl_easy_strerror(result));

    curl_slist_free_all(headers);
    curl_easy_cleanup(curl);
    return result == CURLE_OK ? 0 : 1;
}
$headers = @{
    Authorization = "Bearer <token>"
    Accept        = "application/json"
}

$body = @'
{
    "operatingSystemId": 1,
    "name": "server 1",
    "hostname": "server1.domain.com",
    "sshKeys": [
        1,
        2,
        3,
        4
    ],
    "vnc": false,
    "ipv6": false,
    "swap": 512,
    "email": true
}
'@

$response = Invoke-RestMethod -Uri "https://cp.domain.com/api/v1/servers/9/build" -Method POST -Headers $headers -ContentType "application/json" -Body $body
$response | ConvertTo-Json -Depth 10
POST /api/v1/servers/9/build HTTP/1.1
Host: cp.domain.com
Authorization: Bearer <token>
Accept: application/json
Content-Type: application/json
Content-Length: 232

{
    "operatingSystemId": 1,
    "name": "server 1",
    "hostname": "server1.domain.com",
    "sshKeys": [
        1,
        2,
        3,
        4
    ],
    "vnc": false,
    "ipv6": false,
    "swap": 512,
    "email": true
}

Responses

200

OK.

#
application/json
object
dataServer#

A server with its full configuration, resources, network and state.

Server fields
idinteger#
ownerIdinteger#
hypervisorIdinteger#
archinteger#
namestring#
selfServiceinteger#
selfServiceSettingsarray[any]#
hostnamestring#nullable
commissionStatusinteger#
uuidstring#
statestring#
migratableboolean#
timezonestring#
migrateLevelinteger#
deleteLevelinteger#
configLevelinteger#
backupLevelinteger#
elevatedboolean#

See GET /servers/{serverId}/elevate.

rescueinteger#

0, or the id of the rescue image the server is booted into. See GET /servers/{serverId}/rescue.

resourcePackIdinteger#nullable
backupManagerobject#
fields
enabledboolean#
resourcePackobject#nullable
elevateIdinteger#nullable
elevateboolean#
destroyableboolean#
rebuildboolean#
suspendedboolean#
protectedboolean#
buildFailedboolean#
primaryNetworkDhcp4boolean#
primaryNetworkDhcp6boolean#
builtstring <date-time>#nullable
createdstring <date-time>#
updatedstring <date-time>#
trafficobject#
fields
bytesPerGbinteger#

The byte definition of a traffic gigabyte in effect, either 1000000000 for decimal or 1073741824 for binary. The allowance figures below are in that definition. Operators choose it in the virtualization settings; decimal is the default. Added in 7.1.0.

publicobject#
fields
countMethodinteger#
policyobject#
fields
directioninteger#
actioninteger#
throttleIninteger#
throttleOutinteger#
alert1integer#
alert2integer#
sourceobject#
fields
directionstring#
actionstring#
throttleInstring#
throttleOutstring#
alert1string#
alert2string#
currentPeriodobject#
fields
startstring <date-time>#
endstring <date-time>#
limitinteger#
settingsobject#
fields
osTemplateInstallboolean#
osTemplateInstallIdinteger#
encryptedPasswordstring#
backupPlaninteger#nullable
uefiboolean#
uefiTypeinteger#
cloudInitboolean#
cloudInitTypeinteger#
configany#

Shape varies; see the example.

userConfigarray[any]#
bootOrderarray[string]#
tpmTypeinteger#
fsFreezeinteger#
networkBootboolean#
bootMenuinteger#
customISOinteger#
securityDriverinteger#
memBalloonobject#
fields
modelinteger#
autoDeflateinteger#
freePageReportinginteger#
hypervobject#
fields
enabledboolean#
passthroughboolean#
relaxedinteger#
vapicinteger#
spinlocksinteger#
vpindexinteger#
runtimeinteger#
synicinteger#
stimerinteger#
resetinteger#
vendorIdinteger#
frequenciesinteger#
reenlightenmentinteger#
tlbflushinteger#
ipiinteger#
evmcsinteger#
vendorIdValuestring#
spinlocksValueinteger#
clockEnabledinteger#
extendedobject#
fields
cpuFlagsobject#
fields
topoextstring#
svmstring#
vmxstring#
machineTypestring#
pciPortsinteger#
resourcesobject#
fields
memoryinteger#
storageinteger#
trafficinteger#
cpuCoresinteger#
trafficCountDirectioninteger#

Which direction counts towards the allowance.

ValueMeaning
0Inherit from the hypervisor, then the global setting
1Inbound and outbound
2Inbound only
3Outbound only
Since 7.1.0
trafficLimitActioninteger#

What happens when the allowance is reached.

ValueMeaning
1Nothing
2Throttle the network
nullInherit
Since 7.1.0
trafficLimitThrottleIninteger#nullable

Inbound throttle speed in kB/s; null inherits.

Since 7.1.0
trafficLimitThrottleOutinteger#nullable

Outbound throttle speed in kB/s; null inherits.

Since 7.1.0
trafficLimitNotification1integer#nullable

First usage alert as a percentage of the allowance; null inherits.

Since 7.1.0
trafficLimitNotification2integer#nullable

Second usage alert as a percentage of the allowance; null inherits.

Since 7.1.0
decryptedPasswordstring#
cpuobject#
fields
typestring#
coresinteger#
typeExactstring#
sharesinteger#
throttleinteger#
topologyobject#
fields
enabledboolean#
socketsinteger#
coresinteger#
threadsinteger#
diesinteger#
customXMLobject#
fields
domainobject#
fields
xmlstring#
enabledboolean#
osobject#
fields
xmlstring#
enabledboolean#
devicesobject#
fields
xmlstring#
enabledboolean#
featuresobject#
fields
xmlstring#
enabledboolean#
clockobject#
fields
xmlstring#
enabledboolean#
cpuTuneobject#
fields
xmlstring#
enabledboolean#
qemuCommandlinearray[any]#
qemuAgentobject#
fields
osobject#
fields
screenstring#
mediaobject#
fields
isoMountedboolean#
isoTypestring#
isoNamestring#
isoFilenamestring#
isoUrlstring#
isoDownloadboolean#
backupPlanobject#
fields
idinteger#nullable
namestring#nullable
vncobject#
fields
ipstring#
portinteger#
enabledboolean#
networkobject#
fields
interfacesarray[object]#
item fields
typestring#
idinteger#
orderinteger#
enabledboolean#
taginteger#
namestring#
driverinteger#nullable

The network interface model; null uses the hypervisor default.

ValueMeaning
1virtio
2e1000
3rtl8139
processQueuesboolean#nullable
macstring#
ipv4ToMacboolean#nullable
ipv6ToMacboolean#nullable
inTrafficCountboolean#
outTrafficCountboolean#
inAverageinteger#
inPeakinteger#
inBurstinteger#
outAverageinteger#
outPeakinteger#
outBurstinteger#
ipFilterboolean#
vlansarray[any]#
ipFilterTypestring#nullable
portIsolatedboolean#
ipv4_resolver_1integer#
ipv4_resolver_2integer#
ipv6_resolver_1integer#
ipv6_resolver_2integer#
networkProfileinteger#
dhcpV4integer#
dhcpV6integer#
firewallEnabledboolean#
hypervisorNetworkinteger#
isNatboolean#
natboolean#
firewallarray[any]#
hypervisorConnectivityobject#
fields
typestring#
idinteger#
bridgestring#
mtuinteger#nullable
primaryboolean#
defaultboolean#
ipWhitelistarray[object]#
item fields
typeinteger#
idinteger#
ipstring#
maskinteger#
actionsarray[any]#
ipv4array[object]#
item fields
idinteger#
orderinteger#
enabledboolean#
blockIdinteger#
addressstring#
gatewaystring#
netmaskstring#
resolver1string#
resolver2string#
rdnsstring#nullable
macstring#nullable
ipv6array[object]#
item fields
idinteger#
blockobject#
fields
idinteger#
namestring#
orderinteger#
enabledboolean#
addressesarray[any]#
addressesDetailedarray[any]#
subnetstring#
cidrinteger#
exhaustedboolean#
gatewaystring#
resolver1string#
resolver2string#
routeNetboolean#
secondaryInterfacesarray[object]#
item fields
typestring#
idinteger#
enabledboolean#
orderinteger#
taginteger#
namestring#
driverinteger#

The network interface model; null uses the hypervisor default.

ValueMeaning
1virtio
2e1000
3rtl8139
processQueuesboolean#nullable
macstring#
ipv4ToMacboolean#nullable
ipv6ToMacboolean#nullable
inTrafficCountboolean#
outTrafficCountboolean#
inAverageinteger#
inPeakinteger#
inBurstinteger#
outAverageinteger#
outPeakinteger#
outBurstinteger#
ipFilterboolean#
vlansarray[any]#
ipFilterTypestring#
portIsolatedboolean#
ipv4_resolver_1integer#
ipv4_resolver_2integer#
ipv6_resolver_1integer#
ipv6_resolver_2integer#
networkProfileinteger#
dhcpV4integer#
dhcpV6integer#
firewallEnabledboolean#
hypervisorNetworkinteger#
isNatboolean#
natboolean#
firewallarray[any]#
hypervisorConnectivityobject#
fields
typestring#
idinteger#
bridgestring#
mtuinteger#nullable
primaryboolean#
defaultboolean#
ipWhitelistarray[any]#
actionsarray[any]#
ipv4array[object]#
item fields
idinteger#
orderinteger#
enabledboolean#
addressstring#
gatewaystring#
netmaskstring#
resolver1string#
resolver2string#
rdnsstring#nullable
macstring#nullable
ipv6array[object]#
item fields
idinteger#
blockobject#
fields
idinteger#
namestring#
orderinteger#
enabledboolean#
addressesarray[any]#
addressesDetailedarray[any]#
subnetstring#
cidrinteger#
exhaustedboolean#
gatewaystring#
resolver1string#
resolver2string#
routeNetboolean#
storagearray[object]#
item fields
typestring#
_idinteger#
idinteger#
cachestring#nullable
busstring#nullable
capacityinteger#
drivestring#
datastoreDiskIdinteger#nullable
filesystemstring#nullable
iopsobject#
fields
readinteger#nullable
writeinteger#nullable
bytesobject#
fields
readinteger#nullable
writeinteger#nullable
profileinteger#
statusinteger#
enabledboolean#
primaryboolean#
createdstring <date-time>#
updatedstring <date-time>#
datastorearray[any]#
namestring#
filenamestring#
hypervisorStorageIdinteger#nullable
localboolean#
locationTypestring#
pathstring#
hypervisorAssetsarray[any]#
hypervisorobject#
fields
idinteger#
ipstring#
hostnamestring#nullable
portinteger#
maintenanceboolean#
groupIdinteger#
groupobject#
fields
namestring#
iconstring#nullable
timezonestring#
forceIPv6boolean#
vncListenTypeinteger#
displayNamestring#nullable
cpuSetstring#nullable
nfTypeinteger#

The network filter (firewall) implementation for servers on the hypervisor.

ValueMeaning
0None
1Libvirt
2Native standard
3Native performance, IPv4
4Native performance, IPv4 and IPv6
5Native privacy (experimental)
backupStorageTypeinteger#

Which backup storage the hypervisor may use.

ValueMeaning
1None
2Directly assigned storage only
3Group assigned storage only
4Group and directly assigned storage
defaultDiskTypestring#
defaultDiskCacheTypestring#
defaultCPUstring#
defaultMachineTypestring#
createdstring <date-time>#
updatedstring <date-time>#
namestring#
dataDirstring#
resourcesobject#
fields
serversobject#
fields
unitsstring#
maxinteger#
allocatedinteger#
freeinteger#
percentinteger#nullable
memoryobject#
fields
unitsstring#
maxinteger#
allocatedinteger#
freeinteger#
percentnumber#
cpuCoresobject#
fields
unitsstring#
maxinteger#
allocatedinteger#
freeinteger#
percentnumber#
localStorageobject#
fields
enabledinteger#
namestring#
storageTypeinteger#
unitsstring#
maxinteger#
allocatedinteger#
freeinteger#
percentnumber#
otherStoragearray[object]#
item fields
idinteger#
namestring#
enabledinteger#
pathstring#nullable
unitsstring#
storageTypeinteger#
isDatastoreboolean#
maxinteger#
allocatedinteger#
freeinteger#
percentnumber#
ownerobject#
fields
idinteger#
adminboolean#
extRelationIdinteger#nullable
namestring#
emailstring#
timezonestring#
suspendedboolean#
twoFactorAuthboolean#
createdstring <date-time>#
updatedstring <date-time>#
sshKeysarray[object]#
item fields
typestring#
idinteger#
ownerIdinteger#
namestring#
publicstring#
enabledboolean#
createdstring <date-time>#
sharedUsersarray[any]#
tasksobject#
fields
activeboolean#
lastOnstring#nullable
actionsobject#
fields
pendingarray[object]#
item fields
idinteger#
actionstring#
requiresarray[string]#
collectedboolean#
completeboolean#
failedboolean#
payloadobject#
fields
diskobject#
fields
idinteger#
disk_storage_idinteger#nullable
createdstring <date-time>#
remoteStateboolean#
Example
{
    "data": {
        "id": 9,
        "ownerId": 3,
        "hypervisorId": 6,
        "arch": 1,
        "name": "server 1",
        "selfService": 0,
        "selfServiceSettings": [],
        "hostname": "server1.domain.com",
        "commissionStatus": 1,
        "uuid": "5de5a89b-b707-41bf-a051-7af1a4e67795",
        "state": "queued",
        "migratable": true,
        "timezone": "_default",
        "migrateLevel": 0,
        "deleteLevel": 0,
        "configLevel": 1,
        "backupLevel": 0,
        "elevated": false,
        "rescue": 0,
        "resourcePackId": null,
        "backupManager": {
            "enabled": false
        },
        "resourcePack": null,
        "elevateId": null,
        "elevate": false,
        "destroyable": true,
        "rebuild": false,
        "suspended": false,
        "protected": false,
        "buildFailed": false,
        "primaryNetworkDhcp4": false,
        "primaryNetworkDhcp6": false,
        "built": "2024-11-29T19:32:17+00:00",
        "created": "2024-04-11T17:22:19+00:00",
        "updated": "2025-01-20T13:32:44+00:00",
        "traffic": {
            "public": {
                "countMethod": 1,
                "policy": {
                    "direction": 1,
                    "action": 2,
                    "throttleIn": 625,
                    "throttleOut": 625,
                    "alert1": 80,
                    "alert2": 95,
                    "source": {
                        "direction": "global",
                        "action": "hypervisor",
                        "throttleIn": "global",
                        "throttleOut": "global",
                        "alert1": "global",
                        "alert2": "global"
                    }
                },
                "currentPeriod": {
                    "start": "2025-01-11T00:00:00.000000Z",
                    "end": "2025-02-10T23:59:59.999999Z",
                    "limit": 200
                }
            }
        },
        "settings": {
            "osTemplateInstall": true,
            "osTemplateInstallId": 1,
            "encryptedPassword": "eyJpdiI6IjVsdWVBMzNNWnVXZzlYMjhlTUMzSXc9PSIsInZhbHVlIjoiT2E3SDNmVTVCOW1GK1RCd0h6YjZwZnIva1ZHbU9rQU1VL1hsQSthcUVRYz0iLCJtYWMiOiIzMzdmNjkxOTcwMjkxYmM2ZmNlMjgyMzdkMTQzMDY2OWY1ZTBlYjExYzA1MjdjMzZmMTU1ZTVlMGFiMWY2ZmJlIiwidGFnIjoiIn0=",
            "backupPlan": null,
            "uefi": false,
            "uefiType": 0,
            "cloudInit": true,
            "cloudInitType": 1,
            "config": {
                "cloud.init": {
                    "on.all": {
                        "user.data": {
                            "runcmd": [
                                "DEBIAN_FRONTEND=noninteractive /usr/bin/apt-get --option=Dpkg::Options::=--force-confold --option=Dpkg::options::=--force-unsafe-io --assume-yes --quiet update",
                                "DEBIAN_FRONTEND=noninteractive /usr/bin/apt-get --option=Dpkg::Options::=--force-confold --option=Dpkg::options::=--force-unsafe-io --assume-yes --quiet dist-upgrade"
                            ]
                        }
                    },
                    "on.password": {
                        "user.data": []
                    },
                    "on.sshkey": {
                        "user.data": []
                    },
                    "on.allpre": {
                        "user.data": []
                    },
                    "on.allpost": {
                        "user.data": []
                    },
                    "on.network": [],
                    "on.network.libvirtrouted": []
                }
            },
            "userConfig": [],
            "bootOrder": [
                "hd",
                "cdrom"
            ],
            "tpmType": 0,
            "fsFreeze": 1,
            "networkBoot": false,
            "bootMenu": 1,
            "customISO": 1,
            "securityDriver": 3,
            "memBalloon": {
                "model": 1,
                "autoDeflate": 0,
                "freePageReporting": 0
            },
            "hyperv": {
                "enabled": false,
                "passthrough": false,
                "relaxed": 0,
                "vapic": 0,
                "spinlocks": 0,
                "vpindex": 0,
                "runtime": 0,
                "synic": 0,
                "stimer": 0,
                "reset": 0,
                "vendorId": 0,
                "frequencies": 0,
                "reenlightenment": 0,
                "tlbflush": 0,
                "ipi": 0,
                "evmcs": 0,
                "vendorIdValue": "KVM VM",
                "spinlocksValue": 8191,
                "clockEnabled": 0
            },
            "extended": {
                "cpuFlags": {
                    "topoext": "1",
                    "svm": "1",
                    "vmx": "1"
                }
            },
            "machineType": "inherit",
            "pciPorts": 16,
            "resources": {
                "memory": 2048,
                "storage": 10,
                "traffic": 200,
                "cpuCores": 1,
                "trafficCountDirection": 0,
                "trafficLimitAction": 2,
                "trafficLimitThrottleIn": null,
                "trafficLimitThrottleOut": null,
                "trafficLimitNotification1": null,
                "trafficLimitNotification2": null
            },
            "decryptedPassword": "uv1dmfUUaENhNpbrGUwD"
        },
        "cpu": {
            "cores": 1,
            "type": "inherit",
            "typeExact": "host-model",
            "shares": 1024,
            "throttle": 0,
            "topology": {
                "enabled": false,
                "sockets": 1,
                "cores": 1,
                "threads": 1,
                "dies": 1
            }
        },
        "customXML": {
            "domain": {
                "xml": "",
                "enabled": false
            },
            "os": {
                "xml": "",
                "enabled": false
            },
            "devices": {
                "xml": "",
                "enabled": false
            },
            "features": {
                "xml": "",
                "enabled": false
            },
            "clock": {
                "xml": "",
                "enabled": false
            },
            "cpuTune": {
                "xml": "",
                "enabled": false
            }
        },
        "qemuCommandline": [],
        "qemuAgent": {
            "os": {
                "screen": "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"
            }
        },
        "media": {
            "isoMounted": false,
            "isoType": "local",
            "isoName": "",
            "isoFilename": "",
            "isoUrl": "",
            "isoDownload": false
        },
        "backupPlan": {
            "id": null,
            "name": null
        },
        "vnc": {
            "ip": "192.168.4.2",
            "port": 5901,
            "enabled": false
        },
        "network": {
            "interfaces": [
                {
                    "id": 9,
                    "order": 1,
                    "enabled": true,
                    "tag": 4238114467,
                    "name": "eth0",
                    "type": "public",
                    "driver": 1,
                    "processQueues": null,
                    "mac": "00:C3:BA:23:37:B3",
                    "ipv4ToMac": null,
                    "ipv6ToMac": null,
                    "inTrafficCount": true,
                    "outTrafficCount": false,
                    "inAverage": 0,
                    "inPeak": 0,
                    "inBurst": 0,
                    "outAverage": 0,
                    "outPeak": 0,
                    "outBurst": 0,
                    "ipFilter": true,
                    "vlans": [],
                    "ipFilterType": "4",
                    "portIsolated": false,
                    "ipv4_resolver_1": 1,
                    "ipv4_resolver_2": 2,
                    "ipv6_resolver_1": 1,
                    "ipv6_resolver_2": 2,
                    "networkProfile": 0,
                    "dhcpV4": 0,
                    "dhcpV6": 0,
                    "firewallEnabled": false,
                    "hypervisorNetwork": 6,
                    "isNat": false,
                    "nat": false,
                    "firewall": [],
                    "hypervisorConnectivity": {
                        "id": 6,
                        "type": "simpleBridge",
                        "bridge": "br0",
                        "mtu": null,
                        "primary": true,
                        "default": true
                    },
                    "ipWhitelist": [
                        {
                            "id": 1,
                            "type": 4,
                            "ip": "100.100.100.100",
                            "mask": 32
                        },
                        {
                            "id": 2,
                            "type": 4,
                            "ip": "10.0.0.10",
                            "mask": 32
                        }
                    ],
                    "actions": [],
                    "ipv4": [
                        {
                            "id": 22,
                            "order": 1,
                            "enabled": true,
                            "blockId": 1,
                            "address": "192.168.4.21",
                            "gateway": "192.168.4.1",
                            "netmask": "255.255.254.0",
                            "resolver1": "8.8.8.8",
                            "resolver2": "8.8.4.4",
                            "rdns": null,
                            "mac": null
                        },
                        {
                            "id": 37,
                            "order": 2,
                            "enabled": true,
                            "blockId": 1,
                            "address": "192.168.4.36",
                            "gateway": "192.168.4.1",
                            "netmask": "255.255.254.0",
                            "resolver1": "8.8.8.8",
                            "resolver2": "8.8.4.4",
                            "rdns": null,
                            "mac": null
                        },
                        {
                            "id": 38,
                            "order": 3,
                            "enabled": true,
                            "blockId": 1,
                            "address": "192.168.4.37",
                            "gateway": "192.168.4.1",
                            "netmask": "255.255.254.0",
                            "resolver1": "8.8.8.8",
                            "resolver2": "8.8.4.4",
                            "rdns": null,
                            "mac": null
                        }
                    ],
                    "ipv6": []
                }
            ],
            "secondaryInterfaces": []
        },
        "storage": [
            {
                "_id": 11,
                "id": 1,
                "cache": null,
                "bus": null,
                "capacity": 10,
                "drive": "a",
                "datastoreDiskId": null,
                "filesystem": null,
                "iops": {
                    "read": null,
                    "write": null
                },
                "bytes": {
                    "read": null,
                    "write": null
                },
                "type": "qcow2",
                "profile": 0,
                "status": 3,
                "enabled": true,
                "primary": true,
                "created": "2024-04-11T17:22:19+00:00",
                "updated": "2024-04-11T17:22:19+00:00",
                "datastore": [],
                "name": "5de5a89b-b707-41bf-a051-7af1a4e67795_1",
                "filename": "5de5a89b-b707-41bf-a051-7af1a4e67795_1.img",
                "hypervisorStorageId": null,
                "local": true,
                "locationType": "mountpoint",
                "path": "/home/vf-data/disk"
            }
        ],
        "hypervisorAssets": [],
        "hypervisor": {
            "id": 6,
            "ip": "192.168.4.2",
            "hostname": null,
            "port": 8892,
            "maintenance": false,
            "groupId": 2,
            "group": {
                "name": "Test",
                "icon": null
            },
            "timezone": "Europe/London",
            "forceIPv6": false,
            "vncListenType": 1,
            "displayName": null,
            "cpuSet": null,
            "nfType": 4,
            "backupStorageType": 2,
            "defaultDiskType": "inherit",
            "defaultDiskCacheType": "inherit",
            "defaultCPU": "inherit",
            "defaultMachineType": "inherit",
            "created": "2024-03-30T09:53:38+00:00",
            "updated": "2024-12-06T21:25:54+00:00",
            "name": "BHV 1",
            "dataDir": "/home/vf-data",
            "resources": {
                "servers": {
                    "units": "#",
                    "max": 0,
                    "allocated": 5,
                    "free": -5,
                    "percent": null
                },
                "memory": {
                    "units": "MB",
                    "max": 29419,
                    "allocated": 7168,
                    "free": 22251,
                    "percent": 24.4
                },
                "cpuCores": {
                    "units": "#",
                    "max": 128,
                    "allocated": 6,
                    "free": 122,
                    "percent": 4.7
                },
                "localStorage": {
                    "enabled": 1,
                    "name": "Local (Default mountpoint)",
                    "storageType": 1,
                    "units": "GB",
                    "max": 1000,
                    "allocated": 141,
                    "free": 859,
                    "percent": 14.1
                },
                "otherStorage": []
            }
        },
        "owner": {
            "id": 3,
            "admin": false,
            "extRelationId": 1,
            "name": "jon Doe",
            "email": "jon@doe.com",
            "timezone": "Europe/London",
            "suspended": false,
            "twoFactorAuth": false,
            "created": "2025-01-20T12:48:20+00:00",
            "updated": "2025-01-20T13:00:38+00:00"
        },
        "sshKeys": [],
        "sharedUsers": [],
        "tasks": {
            "active": true,
            "lastOn": "2024-11-29 19:32:17",
            "actions": {
                "pending": []
            }
        }
    }
}
401

The bearer token is missing, invalid, or expired. The response has no body.

#
No response body.
404

The server was not found.

#
application/json
ErrorMessage
msgstring#
Example
{
    "msg": "server not found"
}
422

A build parameter failed validation; errors names each failing rule (for example a ho…

#
application/json

A build parameter failed validation; errors names each failing rule (for example a hostname without a dot, or a name shorter than 3 characters).

Error
errorsarray[string]#
Example
{
    "errors": [
        "Invalid request"
    ]
}
423

The server cannot be built in its current state (already built, building, or not commis…

#
application/json

The server cannot be built in its current state (already built, building, or not commissioned).

ErrorMessage
msgstring#
Example
{
    "msg": "server is not ready to build"
}
429

Too many requests. Either the token's requests per minute are used up (see the `X-RateL…

#
application/json

Too many requests. Either the token's requests per minute are used up (see the X-RateLimit-* headers) or the calling address has failed authentication 10 times in a minute (the body then includes retry_after_seconds). Retry-After gives the seconds to wait.

object
errorsarray[string]#
retry_after_secondsinteger#

Seconds to wait before retrying. Present on the failed-authentication limit only.

Response headers
Retry-Afterinteger

Seconds to wait before retrying.

X-RateLimit-Limitinteger

The token's requests per minute (token limit only).

X-RateLimit-Remaininginteger

Requests left in the current minute (token limit only).

X-RateLimit-Resetinteger

Unix timestamp at which the minute resets (token limit only).

Examples
{
    "errors": [
        "Too Many Requests"
    ]
}
{
    "errors": [
        "Too many authentication attempts. Try again later."
    ],
    "retry_after_seconds": 42
}

Changes

  • 7.1.0BreakingA server ID that does not exist answers 404 instead of 520, and a validation failure names the failing rule instead of an empty errors list.