14. Hosts

A host identifies the host server that virtual machines are run on.

Only hosts on private cloud to which the calling account has access to are available through this API.

List available hosts

Returns a list of available hosts, along with basic statistics of them when available. The optional query string parameter zone can be set to limit the list to hosts on the specified private cloud.

CPU idle values in the host list statistics are given as an average percentage over past 15 minutes, and free memory is the current value in gigabytes.

Request

GET /1.3/host HTTP/1.1

Normal response

HTTP/1.1 200 OK

{
  "hosts": {
    "host": [
      {
        "id": 7653311107,
        "description": "My Host #1",
        "zone": "private-zone-id",
        "windows_enabled": "no",
        "stats": {
          "stat": [
            {
              "name": "cpu_idle",
              "timestamp": "2019-08-09T12:46:57Z",
              "value": 95.2
            },
            {
              "name": "memory_free",
              "timestamp": "2019-08-09T12:46:57Z",
              "value": 102
            }
          ]
        }
      },
      {
        "id": 8055964291,
        "description": "My Host #2",
        "zone": "private-zone-id",
        "windows_enabled": "no",
        "stats": {
          "stat": [
            {
              "name": "cpu_idle",
              "timestamp": "2019-08-09T12:46:57Z",
              "value": 80.1
            },
            {
              "name": "memory_free",
              "timestamp": "2019-08-09T12:46:57Z",
              "value": 61
            }
          ]
        }
      }
    ]
  }
}

Error responses

HTTP status	Error code	Description
403	ZONE_HOST_FORBIDDEN	Private cloud access denied.

Get host details

Returns detailed information about a specific host.

CPU idle values in the host list statistics are given as percentage on the specified timestamp, and free memory is the value in gigabytes on the specified timestamp.

Request

GET /1.3/host/{host_id} HTTP/1.1

Normal response

HTTP/1.1 200 OK

{
  "host": {
    "id": 7653311107,
    "description": "My Host #1",
    "zone": "private-zone-id",
    "windows_enabled": "no",
    "stats": {
      "stat": [
        {
          "name": "cpu_idle",
          "timestamp": "2019-08-09T12:46:57Z",
          "value": 95.2
        },
        {
          "name": "memory_free",
          "timestamp": "2019-08-09T12:46:57Z",
          "value": 102
        }
      ]
    }
  }
}

Error responses

HTTP status	Error code	Description
403	HOST_FORBIDDEN	Access denied to specified host information.
404	HOST_NOT_FOUND	The specified host does not exist.

Modify host details

Modifies description of a specific host.

Request

PATCH /1.3/host/{host_id} HTTP/1.1

Normal response

HTTP/1.1 200 OK

{
  "host" : {
    "description": "My New Host"
  }
}

Normal response

HTTP/1.1 200 OK

{
  "host": {
    "id": 7653311107,
    "description": "My New Host",
    "zone": "private-zone-id",
    "windows_enabled": "no",
    "stats": {
      "stat": [
        {
          "name": "cpu_idle",
          "timestamp": "2019-08-09T13:37:12Z",
          "value": 93.3
        },
        {
          "name": "memory_free",
          "timestamp": "2019-08-09T13:37:12Z",
          "value": 104
        }
      ]
    }
  }
}

Error responses

HTTP status	Error code	Description
403	HOST_FORBIDDEN	Access denied to modify information of specified host.
404	HOST_NOT_FOUND	The specified host does not exist.