Hypervisors

Retrieve hypervisors

GET/compute/hypervisors

Paged list of hypervisors with their group, network interfaces and storage.

Request

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

Number of results to return. Range between 1 and 200. Defaults to 20.

Example: 20
pageinteger#

Page of results to return, starting at 1. The response carries current_page, last_page, per_page, total and the next and previous page URLs.

Range: at least 1
Example: 1

Request Code Samples

curl --location --request GET 'https://cp.domain.com/api/v1/compute/hypervisors?results=20&page=1' \
--header 'Authorization: Bearer <token>' \
--header 'Accept: application/json'
wget --quiet --output-document=- \
  --method=GET \
  --header='Authorization: Bearer <token>' \
  --header='Accept: application/json' \
  'https://cp.domain.com/api/v1/compute/hypervisors?results=20&page=1'
http GET 'https://cp.domain.com/api/v1/compute/hypervisors?results=20&page=1' \
  'Authorization: Bearer <token>' \
  'Accept: application/json'
const response = await fetch("https://cp.domain.com/api/v1/compute/hypervisors?results=20&page=1", {
    method: "GET",
    headers: {
        "Authorization": "Bearer <token>",
        "Accept": "application/json",
    },
});

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

const response = await axios({
    method: "get",
    url: "https://cp.domain.com/api/v1/compute/hypervisors?results=20&page=1",
    headers: {
        "Authorization": "Bearer <token>",
        "Accept": "application/json",
    },
});

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

const req = https.request({
    hostname: "cp.domain.com",
    path: "/api/v1/compute/hypervisors?results=20&page=1",
    method: "GET",
    headers: {
        "Authorization": "Bearer <token>",
        "Accept": "application/json",
    },
}, (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.end();
import requests

url = "https://cp.domain.com/api/v1/compute/hypervisors?results=20&page=1"
headers = {
    "Authorization": "Bearer <token>",
    "Accept": "application/json",
}

response = requests.request("GET", url, headers=headers)

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",
}

conn.request("GET", "/api/v1/compute/hypervisors?results=20&page=1", None, 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/compute/hypervisors?results=20&page=1',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => array(
        'Authorization: Bearer <token>',
        'Accept: 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('GET', 'https://cp.domain.com/api/v1/compute/hypervisors?results=20&page=1', [
    'headers' => [
        'Authorization' => 'Bearer <token>',
        'Accept' => 'application/json',
    ],
]);

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

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

func main() {
    url := "https://cp.domain.com/api/v1/compute/hypervisors?results=20&page=1"
    req, _ := http.NewRequest("GET", url, nil)
    req.Header.Add("Authorization", "Bearer <token>")
    req.Header.Add("Accept", "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/compute/hypervisors?results=20&page=1"))
            .header("Authorization", "Bearer <token>")
            .header("Accept", "application/json")
            .method("GET", HttpRequest.BodyPublishers.noBody())
            .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();

        Request request = new Request.Builder()
            .url("https://cp.domain.com/api/v1/compute/hypervisors?results=20&page=1")
            .method("GET", null)
            .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("GET"), "https://cp.domain.com/api/v1/compute/hypervisors?results=20&page=1");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", "<token>");
request.Headers.Accept.Add(new MediaTypeWithQualityHeaderValue("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/compute/hypervisors?results=20&page=1")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer <token>"
request["Accept"] = "application/json"

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/compute/hypervisors?results=20&page=1")!)
request.httpMethod = "GET"
request.setValue("Bearer <token>", forHTTPHeaderField: "Authorization")
request.setValue("application/json", forHTTPHeaderField: "Accept")

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::GET, "https://cp.domain.com/api/v1/compute/hypervisors?results=20&page=1")
        .bearer_auth("<token>")
        .header("Accept", "application/json")
        .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::GET, "https://cp.domain.com/api/v1/compute/hypervisors?results=20&page=1")
        .bearer_auth("<token>")
        .header("Accept", "application/json")
        .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

fun main() {
    val client = OkHttpClient()
    val request = Request.Builder()
        .url("https://cp.domain.com/api/v1/compute/hypervisors?results=20&page=1")
        .method("GET", null)
        .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('GET', Uri.parse('https://cp.domain.com/api/v1/compute/hypervisors?results=20&page=1'));
  request.headers['Authorization'] = 'Bearer <token>';
  request.headers['Accept'] = 'application/json';

  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");

    curl_easy_setopt(curl, CURLOPT_URL, "https://cp.domain.com/api/v1/compute/hypervisors?results=20&page=1");
    curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "GET");
    curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);

    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"
}

$response = Invoke-RestMethod -Uri "https://cp.domain.com/api/v1/compute/hypervisors?results=20&page=1" -Method GET -Headers $headers
$response | ConvertTo-Json -Depth 10
GET /api/v1/compute/hypervisors?results=20&page=1 HTTP/1.1
Host: cp.domain.com
Authorization: Bearer <token>
Accept: application/json

Responses

200

A page of results.

#
application/json
Pagination & object
current_pageinteger#
first_page_urlstring#
frominteger#
last_pageinteger#
last_page_urlstring#
next_page_urlstring#nullable
pathstring#
per_pageinteger#
prev_page_urlstring#nullable
tointeger#
totalinteger#
dataarray[Hypervisor]#
Hypervisor fields
idinteger#
commissionedinteger#
ipstring#
ipAltstring#nullable
hostnamestring#nullable
portinteger#
sshPortinteger#
namestring#
maintenanceboolean#
enabledboolean#
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)
groupobject#
fields
descriptionstring#nullable
idinteger#
namestring#
defaultboolean#
enabledboolean#
distributionTypeinteger#
createdstring <date-time>#
updatedstring <date-time>#
maxServersinteger#
maxCpuinteger#
maxMemoryinteger#
networksarray[object]#
item fields
typestring#
idinteger#
bridgestring#
primaryboolean#
defaultboolean#
createdstring <date-time>#
updatedstring <date-time>#
storagearray[any]#
createdstring <date-time>#
updatedstring <date-time>#
prohibitboolean#

When true the scheduler will not place new servers on the hypervisor.

Since 7.1.0

The remaining writable properties, under the names PUT /compute/hypervisors/{hypervisorId} accepts. Only on GET /compute/hypervisors/{hypervisorId}, not in the paged list.

Since 7.1.0
Example
{
    "current_page": 1,
    "data": [
        {
            "id": 1,
            "commissioned": 3,
            "ip": "192.168.4.10",
            "ipAlt": null,
            "hostname": null,
            "port": 8892,
            "sshPort": 22,
            "name": "PHV 1 (RED)",
            "maintenance": false,
            "enabled": true,
            "nfType": 4,
            "group": {
                "id": 1,
                "name": "Default",
                "description": "Default hypervisor group",
                "default": true,
                "enabled": true,
                "distributionType": 5,
                "created": "2024-03-12T22:21:32+00:00",
                "updated": "2024-04-12T20:56:04+00:00"
            },
            "maxServers": 0,
            "maxCpu": 4,
            "maxMemory": 6004,
            "networks": [
                {
                    "id": 1,
                    "type": "simpleBridge",
                    "bridge": "br0",
                    "primary": true,
                    "default": true,
                    "created": "2024-03-12T22:37:15+00:00",
                    "updated": "2024-03-12T22:37:40+00:00"
                }
            ],
            "storage": [],
            "created": "2024-03-12T22:37:15+00:00",
            "updated": "2024-05-10T11:27:52+00:00"
        },
        {
            "id": 2,
            "commissioned": 3,
            "ip": "192.168.4.9",
            "ipAlt": null,
            "hostname": null,
            "port": 8892,
            "sshPort": 22,
            "name": "PHV 2 (BLUE)",
            "maintenance": false,
            "enabled": true,
            "nfType": 4,
            "group": {
                "id": 1,
                "name": "Default",
                "description": "Default hypervisor group",
                "default": true,
                "enabled": true,
                "distributionType": 5,
                "created": "2024-03-12T22:21:32+00:00",
                "updated": "2024-04-12T20:56:04+00:00"
            },
            "maxServers": 0,
            "maxCpu": 28,
            "maxMemory": 10000,
            "networks": [
                {
                    "id": 2,
                    "type": "simpleBridge",
                    "bridge": "br0",
                    "primary": true,
                    "default": true,
                    "created": "2024-03-16T19:31:43+00:00",
                    "updated": "2024-03-16T19:32:46+00:00"
                }
            ],
            "storage": [],
            "created": "2024-03-16T19:31:43+00:00",
            "updated": "2024-04-26T16:41:51+00:00"
        },
        {
            "id": 3,
            "commissioned": 3,
            "ip": "192.168.4.12",
            "ipAlt": null,
            "hostname": null,
            "port": 8892,
            "sshPort": 22,
            "name": "BHV 9",
            "maintenance": false,
            "enabled": true,
            "nfType": 4,
            "group": {
                "id": 1,
                "name": "Default",
                "description": "Default hypervisor group",
                "default": true,
                "enabled": true,
                "distributionType": 5,
                "created": "2024-03-12T22:21:32+00:00",
                "updated": "2024-04-12T20:56:04+00:00"
            },
            "maxServers": 0,
            "maxCpu": 64,
            "maxMemory": 27913,
            "networks": [
                {
                    "id": 3,
                    "type": "simpleBridge",
                    "bridge": "br0",
                    "primary": true,
                    "default": true,
                    "created": "2024-03-29T20:10:22+00:00",
                    "updated": "2024-04-09T11:32:14+00:00"
                }
            ],
            "storage": [],
            "created": "2024-03-29T20:10:22+00:00",
            "updated": "2024-04-16T10:44:21+00:00"
        },
        {
            "id": 4,
            "commissioned": 3,
            "ip": "192.168.4.11",
            "ipAlt": null,
            "hostname": null,
            "port": 8892,
            "sshPort": 22,
            "name": "BHV 8",
            "maintenance": false,
            "enabled": true,
            "nfType": 4,
            "group": {
                "id": 1,
                "name": "Default",
                "description": "Default hypervisor group",
                "default": true,
                "enabled": true,
                "distributionType": 5,
                "created": "2024-03-12T22:21:32+00:00",
                "updated": "2024-04-12T20:56:04+00:00"
            },
            "maxServers": 0,
            "maxCpu": 16,
            "maxMemory": 27913,
            "networks": [
                {
                    "id": 4,
                    "type": "macVTap",
                    "bridge": "eth0",
                    "primary": true,
                    "default": true,
                    "created": "2024-03-29T20:10:42+00:00",
                    "updated": "2024-03-29T20:10:42+00:00"
                }
            ],
            "storage": [],
            "created": "2024-03-29T20:10:42+00:00",
            "updated": "2024-04-16T10:44:21+00:00"
        },
        {
            "id": 6,
            "commissioned": 3,
            "ip": "192.168.4.2",
            "ipAlt": "123.123.123.121",
            "hostname": null,
            "port": 8892,
            "sshPort": 22,
            "name": "BHV 1",
            "maintenance": false,
            "enabled": true,
            "nfType": 4,
            "group": {
                "id": 2,
                "name": "Test",
                "description": null,
                "default": false,
                "enabled": true,
                "distributionType": 13,
                "created": "2024-10-08T13:23:28+00:00",
                "updated": "2024-10-08T13:23:42+00:00"
            },
            "maxServers": 0,
            "maxCpu": 128,
            "maxMemory": 29419,
            "networks": [
                {
                    "id": 6,
                    "type": "simpleBridge",
                    "bridge": "br0",
                    "primary": true,
                    "default": true,
                    "created": "2024-03-30T09:53:38+00:00",
                    "updated": "2025-01-15T13:31:56+00:00"
                },
                {
                    "id": 17,
                    "type": "lvBridgeOVS",
                    "bridge": "bhv1",
                    "primary": false,
                    "default": false,
                    "created": "2024-05-17T11:25:57+00:00",
                    "updated": "2024-05-17T11:25:57+00:00"
                }
            ],
            "storage": [],
            "created": "2024-03-30T09:53:38+00:00",
            "updated": "2024-12-06T21:25:54+00:00"
        }
    ],
    "first_page_url": "https://192.168.3.11/api/v1/compute/hypervisors?results=5&page=1",
    "from": 1,
    "last_page": 3,
    "last_page_url": "https://192.168.3.11/api/v1/compute/hypervisors?results=5&page=3",
    "links": [
        {
            "url": null,
            "label": "&laquo; Previous",
            "active": false
        },
        {
            "url": "https://192.168.3.11/api/v1/compute/hypervisors?results=5&page=1",
            "label": "1",
            "active": true
        },
        {
            "url": "https://192.168.3.11/api/v1/compute/hypervisors?results=5&page=2",
            "label": "2",
            "active": false
        },
        {
            "url": "https://192.168.3.11/api/v1/compute/hypervisors?results=5&page=3",
            "label": "3",
            "active": false
        },
        {
            "url": "https://192.168.3.11/api/v1/compute/hypervisors?results=5&page=2",
            "label": "Next &raquo;",
            "active": false
        }
    ],
    "next_page_url": "https://192.168.3.11/api/v1/compute/hypervisors?results=5&page=2",
    "path": "https://192.168.3.11/api/v1/compute/hypervisors",
    "per_page": 5,
    "prev_page_url": null,
    "to": 5,
    "total": 14
}
401

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

#
No response body.
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.0Storage entries report their own created and updated timestamps instead of the last network interface's.