logo

Virtual Machines

Endpoints for managing virtual machines.

List Virtual Machines

Requires the virtual-machines-view capability.

SecuritybearerAuth and hubAuth
Request
query Parameters
meta
Array of strings

A comma-separated list of meta values. Meta values will show up under a resource's meta field. In the case of applying a meta to a collection of resources, each resource will have its own relevant meta data. In some rare cases, meta may not apply to individual resources, and may appear in the root document. These will be clearly labeled.

Items Enum: "domains" "ips"
include
Array of strings

A comma-separated list of include values. Included resources will show up under the root document's include field. In the case of applying an include to a collection of resources, if multiple resources share the same include, it will only appear once in the return.

Items Enum: "creators" "environments" "clusters" "containers"
object

Filter Field

The filter field is a key-value object, where the key is what you would like to filter, and the value is the value you're filtering for.

sort
Array of strings

An array of sort values. To sort descending, put a - in front of the value, e.g. -id.

object

In a list return, the data associated with the page number and size returned. 20 results per page, page 2 would be page[size]=20&page[number]=2

Responses
200

Returns a list of virtual machines.

default

General error response from the platform

get/v1/virtual-machines
Response samples
application/json
{
  • "data": [
    ],
  • "includes": {
    }
}

Create Virtual Machine

Requires the virtual-machines-deploy capability.

SecuritybearerAuth and hubAuth
Request
query Parameters
meta
Array of strings

A comma-separated list of meta values. Meta values will show up under a resource's meta field. In the case of applying a meta to a collection of resources, each resource will have its own relevant meta data. In some rare cases, meta may not apply to individual resources, and may appear in the root document. These will be clearly labeled.

Items Enum: "domains" "ips"
include
Array of strings

A comma-separated list of include values. Included resources will show up under the root document's include field. In the case of applying an include to a collection of resources, if multiple resources share the same include, it will only appear once in the return.

Items Enum: "creators" "environments" "clusters"
Request Body schema: application/json

Parameters for creating a new virtual machine.

identifier
string (Identifier)

A human-readable identifier used to refer to a resource, where using the official ID may be inconvenient. The identifier is automatically tokenized from the name/relevant field of the resource if one is not provided. For example, a container named "My Container" will have the identifier of my-container and is automatically created by the platform.

The identifier does not have to be unique.

name
required
string

A user-defined name for the virtual machine.

environment_id
required
string

The ID of the environment this virtual machine will be deployed to.

required
VirtualMachineImage (object) or VirtualMachineImage (object) or VirtualMachineImage (object) (VirtualMachineImage)
required
object (VirtualMachineConfig)

Defines the network and deployment configurations for a virtual machine.

lock
required
boolean

Prevents this virtual machine from being deleted when true.

Array of VirtualMachineVolumeConfig (objects) or null
base_disk_size
string

The size of the base disk. Must be between 10G and 100G.

object or null

Custom meta data. Not utilized by Cycle.

ssh_keys
Array of strings <objectid> (ID)

An array of SSH key IDs that should be applied to this virtual machine.

Responses
201

Returns the newly created virtual machine.

default

General error response from the platform

post/v1/virtual-machines
Request samples
application/json
{
  • "identifier": "string",
  • "name": "string",
  • "environment_id": "string",
  • "image": {
    },
  • "config": {
    },
  • "lock": true,
  • "volumes": [
    ],
  • "base_disk_size": "10G",
  • "annotations": {
    },
  • "ssh_keys": [
    ]
}
Response samples
application/json
{
  • "data": {
    },
  • "includes": {
    }
}

Get Virtual Machine

Retrieves a single virtual machine by ID.

Requires the virtual-machines-view capability.

SecuritybearerAuth and hubAuth
Request
path Parameters
virtualMachineId
required
string

The ID of the virtual machine.

query Parameters
meta
Array of strings

A comma-separated list of meta values. Meta values will show up under a resource's meta field. In the case of applying a meta to a collection of resources, each resource will have its own relevant meta data. In some rare cases, meta may not apply to individual resources, and may appear in the root document. These will be clearly labeled.

Items Enum: "domains" "ips"
include
Array of strings

A comma-separated list of include values. Included resources will show up under the root document's include field. In the case of applying an include to a collection of resources, if multiple resources share the same include, it will only appear once in the return.

Items Enum: "creators" "environments" "clusters" "containers"
Responses
200

Returns the requested virtual machine.

default

General error response from the platform

get/v1/virtual-machines/{virtualMachineId}
Response samples
application/json
{
  • "data": {
    },
  • "includes": {
    }
}

Delete Virtual Machine

Requires the virtual-machines-manage capability.

SecuritybearerAuth and hubAuth
Request
path Parameters
virtualMachineId
required
string

The ID of the virtual machine to delete.

Responses
202

Returns a job descriptor.

default

General error response from the platform

delete/v1/virtual-machines/{virtualMachineId}
Response samples
application/json
{
  • "data": {
    }
}

Create Virtual Machine Job

Used to perform different actions on a virtual machine.

Requires the following capabilities based on the task: start: virtual-machines-manage stop: virtual-machines-manage reconfigure: virtual-machines-manage rootpw.change: virtual-machines-manage ip.allocate: virtual-machines-manage ip.unallocate: virtual-machines-manage

SecuritybearerAuth and hubAuth
Request
path Parameters
virtualMachineId
required
string

The ID of the virtual machine.

Request Body schema: application/json

Parameters for creating a new virtual machine job.

action
required
string
Responses
202

Returns a job descriptor.

default

General error response from the platform

post/v1/virtual-machines/{virtualMachineId}/tasks
Request samples
application/json
{
  • "action": "start"
}
Response samples
application/json
{
  • "data": {
    }
}

Get Virtual Machine Base Images

Retrieves the list of available base images for virtual machines provided by Cycle.

SecuritybearerAuth and hubAuth
Responses
200

A map of virtual machine base images provided by Cycle keyed by an identifier.

default

General error response from the platform

get/v1/virtual-machines/images/base
Response samples
application/json
{
  • "data": {
    }
}

Generate Virtual Machine Serial-Over-SSH Credentials

Generates credentials for connecting to the serial console of a virtual machine via SSH.

Requires the virtual-machines-console capability.

SecuritybearerAuth and hubAuth
Request
path Parameters
virtualMachineId
required
string

The ID of the virtual machine.

Responses
200

Returns a serial-over-sos connection response.

default

General error response from the platform

get/v1/virtual-machines/{virtualMachineId}/sos
Response samples
application/json
{
  • "data": {
    }
}

Expire Serial-Over-SSH Credentials

Instantly expires any serial-over-SSH credentials generated for this virtual machine.

Requires the virtual-machines-console capability.

SecuritybearerAuth and hubAuth
Request
path Parameters
virtualMachineId
required
string

The ID of the virtual machine.

Responses
200

Returns the number of tokens removed.

default

General error response from the platform

delete/v1/virtual-machines/{virtualMachineId}/sos
Response samples
application/json
{
  • "data": {
    }
}

List Virtual Machine SSH Keys

Requires the virtual-machines-ssh-keys-manage capability.

SecuritybearerAuth and hubAuth
Request
query Parameters
object

Filter Field

The filter field is a key-value object, where the key is what you would like to filter, and the value is the value you're filtering for.

include
Array of strings

A comma-separated list of include values. Included resources will show up under the root document's include field. In the case of applying an include to a collection of resources, if multiple resources share the same include, it will only appear once in the return.

Items Enum: "creators" "environments"
sort
Array of strings

An array of sort values. To sort descending, put a - in front of the value, e.g. -id.

object

In a list return, the data associated with the page number and size returned. 20 results per page, page 2 would be page[size]=20&page[number]=2

Responses
200

Returns a list of virtual machine SSH keys.

default

General error response from the platform

get/v1/virtual-machines/ssh-keys
Response samples
application/json
{
  • "data": [
    ],
  • "includes": {
    }
}

Create Virtual Machine SSH Key

Requires the virtual-machines-ssh-keys-manage capability.

SecuritybearerAuth and hubAuth
Request
query Parameters
include
Array of strings

A comma-separated list of include values. Included resources will show up under the root document's include field. In the case of applying an include to a collection of resources, if multiple resources share the same include, it will only appear once in the return.

Items Enum: "creators" "environments"
Request Body schema: application/json

Parameters for creating a new virtual machine SSH key.

name
required
string

A user-defined name for the SSH key.

public_key
required
string

The public key of the SSH key.

environment_id
required
string <objectid> (ID)

A 24 character hex string used to identify a unique resource.

Responses
201

Returns the newly created SSH key.

default

General error response from the platform

post/v1/virtual-machines/ssh-keys
Request samples
application/json
{
  • "name": "string",
  • "public_key": "string",
  • "environment_id": "651586fca6078e98982dbd90"
}
Response samples
application/json
{
  • "data": {
    },
  • "includes": {
    }
}

Get Virtual Machine SSH Key

Retrieves a single virtual machine SSH key by ID.

Requires the virtual-machines-ssh-keys-manage capability.

SecuritybearerAuth and hubAuth
Request
path Parameters
sshKeyId
required
string

The ID of the virtual machine SSH key.

query Parameters
include
Array of strings

A comma-separated list of include values. Included resources will show up under the root document's include field. In the case of applying an include to a collection of resources, if multiple resources share the same include, it will only appear once in the return.

Items Enum: "creators" "environments"
Responses
200

Returns the requested virtual machine SSH key.

default

General error response from the platform

get/v1/virtual-machines/ssh-keys/{sshKeyId}
Response samples
application/json
{
  • "data": {
    },
  • "includes": {
    }
}

Delete Virtual Machine SSH Key

Requires the virtual-machines-ssh-keys-manage capability.

SecuritybearerAuth and hubAuth
Request
path Parameters
sshKeyId
required
string

The ID of the virtual machine SSH key to delete.

Responses
202

Returns a job descriptor.

default

General error response from the platform

delete/v1/virtual-machines/ssh-keys/{sshKeyId}
Response samples
application/json
{
  • "data": {
    }
}
➔ Next to Utility