Instances

An instance is a Genesis Cloud virtual machine. By sending requests to the instances endpoint, you can list, create and delete instances.

Instance Schema

id String - A unique identifier for each instance. This is automatically generated.
name String - The human-readable name set for the instance.
hostname String - The instance host name.
dns_name String - The instance DNS name.
type String - The instance type (eg. vcpu-8_memory-32g_nvidia-rtx-3080-1).
region String - The region identifier this instance exists in (eg. ARC-IS-HAF-1).
placement_option String - The placement option identifier (eg. AUTO).
image Object - The instance base image object.
floating_ip Object - The floating IP attached to the instance.
ssh_keys Array - The instance's ssh keys.
security_groups Array - The instance's security groups.
volumes Array - The instance's volumes.
is_protected String - The instance termination protection flag.
status String - The instance status. Possible values are creating, pending_payment, active, stopping, stopped, starting, resetting, error and deleting.
private_ip String - The instance private ip. It may take some time to be assigned after the instance is created.
public_ip String - The instance public ip. It may take some time to be assigned after the instance is created.
public_ip_type String _^Optional - static or dynamic. When set to static, the instance's public IP will not change between start and stop actions. Defaults to dynamic. Only available for legacy projects. Use the floating_ip field instead.
disk_size Integer - The storage size of the instance's boot volume given in GiB (Min: 80GiB).
created_at String - A time value given in ISO8601 combined date and time format that represents when the instance was created.
updated_at String - A time value given in ISO8601 combined date and time format that represents when the instance was updated.

Info for legacy projects and accounts

For legacy projects and accounts there is an additional status enqueued as well as other undocumented statuses. These can include but are not limited to copying, build, restarting, shutoff, updating and unknown.

Create an Instance

Please Note: Creating an instance results in costs according to Genesis Cloud's pricing. You can see all your billed resources in the billing dashboard.

To create a new instance, send a request to:

POST /compute/v1/instances (HTTP 201 - Created)

The attribute values that must be set to successfully create an instance are:

Body parameters

name String _^Required - The human-readable name set for the instance.
hostname String _^Required - The hostname of your instance.
type String _^Required - The instance type identifier, see Instance Types.
region String _^Required - The region identifier in which this instance should be created in, see Regions.
placement_option String _^Optional - The placement option identifier in which instances are physically located relative to each other within a zone. Defaults to AUTO.
image String _^Required - The image id, image slug or snapshot id. The image version can also specified together with the image slug in this format <image-slug>:<version>, see image schema.
floating_ip String _^Optional - The id of the floating IP to attach to the instance.
ssh_keys Array _^Required - An array of ssh key ids. This should not be provided if password authentication method is desired.
volumes Array _^Optional - An array of volume ids. Please Note: These should be ids for valid volumes with a status of available, see volume schema.
password String _^Optional - The password to access the instance. Your password must have a minimum length of 16 characters. Please Note: Only one of ssh_keys or password can be provided. Password is less secure - we recommend you use an SSH key-pair instead.
security_groups Array _^Optional - An array of security group ids. Please Note: Passing the empty array will result in an instance without any security groups.
is_protected Boolean _^Optional - Specifies if the instance is termination protected. When set to true, it's not possible to destroy the instance until it's switched to false. Set to true automatically for long-term billed instances. Defaults to false.
public_ip_type String _^Optional - static or dynamic. When set to static, the instance's public IP will not change between start and stop actions. Defaults to dynamic. Only available for legacy projects. Use the floating_ip field instead.
disk_size Integer _^Optional - The storage size of the instance's boot volume given in GiB (Min: 80GiB). If the field is not set, the default is 80GiB.
metadata Object _^Optional - Option to provide metadata.
- A startup_script is a plain text bash script or 'cloud-config' file that will be executed after the first instance boot. It is limited to 64 KiB in size. You can use it to configure your instance, e.g. installing the NVIDIA GPU driver. Learn more about startup scripts and installing the GPU driver.
- Provide custom user_data in a variety of formats. You can use it for example to provide a cloud-config file via the "text/cloud-config" type. The filename is optional, but it can be useful when debugging inside the instance.
  User data Schema
  - type String
  - filename String (optional)
  - content String

Info for legacy projects and accounts

For legacy projects and accounts, the only supported metadata field is startup_script.

{
  "name": "name",
  "hostname": "hostname",
  "type": "vcpu-8_memory-48g_nvidia-rtx-3090-2",
  "region": "ARC-IS-HAF-1",
  "image": "7b1644e2-d97d-4725-a927-0028bc60bc28",
  "floating_ip": "db1bf06d-528d-4fac-96d8-390798f83388",
  "ssh_keys": ["45bcd3ac-fccd-4eea-a812-21f01d665464"],
  "metadata": {
    "startup_script": "#!/bin/bash\nsudo apt update && sudo apt install iperf3"
  },
  "disk_size": 128
}

Response body

A Instance will be created using the provided information. The response body will contain a JSON object with standard attributes for your new Instance, see Instance Schema:

{
  "instance": {
    "id": "9e8ce501-d692-402c-8fca-5a8f5d8ddd57",
    "name": "name",
    "hostname": "hostname",
    "type": "vcpu-8_memory-48g_nvidia-rtx-3090-2",
    "region": "ARC-IS-HAF-1",
    "image": {
      "id": "ac26fa2b-c6d5-47a7-bc4e-5a219797e70f",
      "name": "Ubuntu 20.04"
    },
    "floating_ip": {
      "id": "db1bf06d-528d-4fac-96d8-390798f83388",
      "name": "<floating_ip_name>"
    },
    "ssh_keys": [
      {
        "id": "45bcd3ac-fccd-4eea-a812-21f01d665464",
        "name": "ssh-key-name"
      }
    ],
    "security_groups": [
      {
        "id": "fd537d69-9db7-4a44-83b8-96f79d10071a",
        "name": "standard"
      }
    ],
    "volumes": [
      {
        "id": "0580fb4c-de74-4b83-8bdb-1fd87d89f827",
        "name": "<volume_name>"
      }
    ],
    "is_protected": false,
    "status": "active",
    "private_ip": "192.168.10.124",
    "public_ip": "198.51.100.127",
    "disk_size": 128,
    "created_at": "2020-03-23T10:09:29.152Z",
    "updated_at": "2020-03-23T10:10:28.797Z"
  }
}

From a snapshot

If you want to create an instance from a given snapshot you can pass the snapshot id as the image property. Check how you can create snapshots here.

List all Instances

To list all the instances, send a GET request to /compute/v1/instances.

GET /compute/v1/instances (HTTP 200 - OK)

Query parameters

per_page Integer _^Optional - A positive integer lower or equal to 100 to select the number of items to return (default: 50).
page Integer _^Optional - A positive integer to choose the page to return.

Response body

The response will be a JSON object with pagination details and a key called instances. This will be set to an array of instance objects, each of which will contain the instance object, see Instance Schema:

{
  "instances": [
    {
      "id": "9e8ce501-d692-402c-8fca-5a8f5d8ddd57",
      "name": "name",
      "hostname": "hostname",
      "type": "vcpu-4_memory-12g_nvidia-rtx-3080-1",
      "region": "ARC-IS-HAF-1",
      "image": {
        "id": "ac26fa2b-c6d5-47a7-bc4e-5a219797e70f",
        "name": "Ubuntu 20.04"
      },
      "floating_ip": null,
      "ssh_keys": [
        {
          "id": "45bcd3ac-fccd-4eea-a812-21f01d665464",
          "name": "ssh-key-name"
        }
      ],
      "security_groups": [
        {
          "id": "fd537d69-9db7-4a44-83b8-96f79d10071a",
          "name": "standard"
        }
      ],
      "volumes": [
        {
          "id": "0580fb4c-de74-4b83-8bdb-1fd87d89f827",
          "name": "<volume_name>"
        }
      ],
      "is_protected": false,
      "status": "active",
      "private_ip": "192.168.10.124",
      "public_ip": "198.51.100.127",
      "disk_size": 128,
      "created_at": "2020-03-23T10:09:29.152Z",
      "updated_at": "2020-03-23T10:10:28.797Z"
    }
  ],
  "total_count": 1,
  "page": 1,
  "per_page": 50
}

Get Instance

Get details of an instance with the given ID.

GET /compute/v1/instances/{instance_id} (HTTP 200 - OK)

Path parameters:

instance_id String - Instance id

Response body

The response will be a JSON object that contains the instance attributes, see Instance Schema:

{
  "instance": {
    "id": "9e8ce501-d692-402c-8fca-5a8f5d8ddd57",
    "name": "name",
    "hostname": "hostname",
    "type": "vcpu-4_memory-12g_nvidia-rtx-3080-1",
    "region": "ARC-IS-HAF-1",
    "image": {
      "id": "ac26fa2b-c6d5-47a7-bc4e-5a219797e70f",
      "name": "Ubuntu 20.04"
    },
    "floating_ip": null,
    "ssh_keys": [
      {
        "id": "45bcd3ac-fccd-4eea-a812-21f01d665464",
        "name": "ssh-key-name"
      }
    ],
    "security_groups": [
      {
        "id": "00faf681-6f59-4c94-8523-28903f13da47",
        "name": "standard"
      }
    ],
    "volumes": [
      {
        "id": "0580fb4c-de74-4b83-8bdb-1fd87d89f827",
        "name": "<volume_name>"
      }
    ],
    "is_protected": false,
    "status": "active",
    "private_ip": "192.168.10.124",
    "public_ip": "198.51.100.127",
    "disk_size": 128,
    "created_at": "2020-03-23T10:09:29.152Z",
    "updated_at": "2020-03-23T10:10:28.797Z"
  }
}

Destroy an instance

Destroy an instance with the given ID. The data on the boot disk will be lost. Attached volumes are not affected. The billing will stop as soon as you request the instance destroy.

DELETE /compute/v1/instances/{instance_id}  (HTTP 204 - No content)

Path parameters:

instance_id String - Instance id

Snapshot an Instance

Takes a snapshot of the instance.

POST /compute/v1/instances/{instance_id}/snapshots (HTTP 201 - Created)

Path parameters:

instance_id String - Instance id

Body parameters

name String _^Required - The snapshot name.

{
  "name": "name"
}

Response body

The response will be a JSON object that contains the snapshot attributes, see Snapshot Schema:

{
  "snapshot": {
    "id": "ca73c941-7bd7-4d05-98d3-485e7980638b",
    "name": "snapshot",
    "region": "ARC-IS-HAF-1",
    "status": "created",
    "resource_id": "<instance-id>",
    "created_at": "2020-03-30T13:39:44.540Z"
  }
}

List Snapshots of an Instance

Lists all snapshots that were taken of this instance.

GET /compute/v1/instances/{instance_id}/snapshots (HTTP 200 - OK)

Path parameters:

instance_id String - Instance id

Response body

The response will be a JSON object with pagination details and a key called snapshots. This will be set to an array of instance snapshot objects, each of which will contain the instance snapshot object, see Snapshot Schema:

{
  "snapshots": [
    {
      "id": "ff942497-62f6-4a9d-8dc4-3766ebc2b8a2",
      "name": "snapshot name",
      "size": 128,
      "region": "ARC-IS-HAF-1",
      "status": "created",
      "resource_id": "<snapshotted-resource-id>",
      "created_at": "2020-04-06T10:47:46.786Z"
    }
  ],
  "total_count": 1,
  "page": 1,
  "per_page": 50
}

Attach/Detach Security Groups from an Instance

Attaching/Detaching a security group to an instance is possible by passing the full list of security groups IDs. This means, in order to add one additional security group you need to pass the list of current security groups plus the security group to be added. If no value is passed, the current list of security groups will be kept. Passing an empty array will detach all security groups.

PATCH /compute/v1/instances/{instance_id} (HTTP 200 - OK)

Path parameters:

instance_id String - Instance id.

Body parameters

security_groups Array _^Required - The list of security group IDs.

{
  "security_groups": [
    "fd537d69-9db7-4a44-83b8-96f79d10071a",
    "00faf681-6f59-4c94-8523-28903f13da47"
  ]
}

Response body

The response will be a JSON object that represents the instance object, see Instance Schema:

{
  "instance": {
    "id": "9e8ce501-d692-402c-8fca-5a8f5d8ddd57",
    "name": "name",
    "hostname": "hostname",
    "type": "vcpu-8_memory-48g_nvidia-rtx-3090-2",
    "region": "ARC-IS-HAF-1",
    "image": {
      "id": "ac26fa2b-c6d5-47a7-bc4e-5a219797e70f",
      "name": "Ubuntu 20.04"
    },
    "floating_ip": null,
    "ssh_keys": [
      {
        "id": "45bcd3ac-fccd-4eea-a812-21f01d665464",
        "name": "ssh-key-name"
      }
    ],
    "security_groups": [
      {
        "id": "fd537d69-9db7-4a44-83b8-96f79d10071a",
        "name": "standard"
      },
      {
        "id": "00faf681-6f59-4c94-8523-28903f13da47",
        "name": "example sg"
      }
    ],
    "volumes": [
      {
        "id": "0580fb4c-de74-4b83-8bdb-1fd87d89f827",
        "name": "<volume_name>"
      }
    ],
    "is_protected": false,
    "status": "active",
    "private_ip": "192.168.10.124",
    "public_ip": "198.51.100.127",
    "disk_size": 128,
    "created_at": "2020-03-23T10:09:29.152Z",
    "updated_at": "2020-03-23T10:10:28.797Z"
  }
}

Attach/Detach Volumes from an Instance

Attach/Detach a volume to an instance is possible by passing the full list of volumes IDs. This means, in order to add one additional volume you need to pass the list of current volumes plus the volume to be added.

PATCH /compute/v1/instances/{instance_id} (HTTP 200 - OK)

Path parameters:

instance_id String - Instance id.

Body parameters

volumes Array _^Required - The list of volume IDs.

{
  "volumes": ["0580fb4c-de74-4b83-8bdb-1fd87d89f827"]
}

Response body

The response will be a JSON object that represents the instance object, see Instance Schema:

{
  "instance": {
    "id": "9e8ce501-d692-402c-8fca-5a8f5d8ddd57",
    "name": "name",
    "hostname": "hostname",
    "type": "vcpu-8_memory-48g_nvidia-rtx-3090-2",
    "region": "ARC-IS-HAF-1",
    "image": {
      "id": "ac26fa2b-c6d5-47a7-bc4e-5a219797e70f",
      "name": "Ubuntu 20.04"
    },
    "floating_ip": null,
    "ssh_keys": [
      {
        "id": "45bcd3ac-fccd-4eea-a812-21f01d665464",
        "name": "ssh-key-name"
      }
    ],
    "security_groups": [
      {
        "id": "fd537d69-9db7-4a44-83b8-96f79d10071a",
        "name": "standard"
      },
      {
        "id": "00faf681-6f59-4c94-8523-28903f13da47",
        "name": "example sg"
      }
    ],
    "volumes": [
      {
        "id": "0580fb4c-de74-4b83-8bdb-1fd87d89f827",
        "name": "<volume_name>"
      }
    ],
    "is_protected": false,
    "status": "active",
    "private_ip": "192.168.10.124",
    "public_ip": "198.51.100.127",
    "disk_size": 128,
    "created_at": "2020-03-23T10:09:29.152Z",
    "updated_at": "2020-03-23T10:10:28.797Z"
  }
}

Update an Instance

Update the details of an Instance. You can update the instance's name and/or the is_protected flag. You can patch the instance by sending in the request only the properties you want to update.

PATCH /compute/v1/instances/{instance_id} (HTTP 200 - OK)

Path parameters:

instance_id String - Instance id.

Body parameters

name String _^Optional - The new name of the instance. The hostname is not affected.
is_protected Boolean _^Optional - Specifies if the instance is termination protected.
disk_size Integer _^Optional - The new storage size of the instance's boot volume given in GiB. Please note that the disk size can only be increased.

{
  "name": "My Genesis Cloud instance",
  "is_protected": true,
  "disk_size": 256
}

Response body

The response will be a JSON object that represents the instance object, see Instance Schema:

{
  "instance": {
    "id": "9e8ce501-d692-402c-8fca-5a8f5d8ddd57",
    "name": "My Genesis Cloud instance",
    "hostname": "hostname",
    "type": "vcpu-8_memory-48g_nvidia-rtx-3090-2",
    "region": "ARC-IS-HAF-1",
    "image": {
      "id": "ac26fa2b-c6d5-47a7-bc4e-5a219797e70f",
      "name": "Ubuntu 20.04"
    },
    "floating_ip": null,
    "ssh_keys": [
      {
        "id": "45bcd3ac-fccd-4eea-a812-21f01d665464",
        "name": "ssh-key-name"
      }
    ],
    "security_groups": [
      {
        "id": "fd537d69-9db7-4a44-83b8-96f79d10071a",
        "name": "standard"
      },
      {
        "id": "00faf681-6f59-4c94-8523-28903f13da47",
        "name": "example sg"
      }
    ],
    "volumes": [
      {
        "id": "0580fb4c-de74-4b83-8bdb-1fd87d89f827",
        "name": "<volume_name>"
      }
    ],
    "is_protected": true,
    "status": "active",
    "private_ip": "192.168.10.124",
    "public_ip": "198.51.100.127",
    "disk_size": 256,
    "created_at": "2020-03-23T10:09:29.152Z",
    "updated_at": "2020-03-23T10:10:28.797Z"
  }
}

Get Instance actions

List all actions that can currently be performed on a instance.

GET /compute/v1/instances/{instance_id}/actions (HTTP 200 - OK)

Path parameters:

instance_id String - Instance id

Response body

The response will be a JSON object that contains the instance actions:

actions Array - List all actions that can currently be performed on a instance.

{
  "actions": ["reset", "stop"]
}

Perform action

The action to perform on the instance.

POST /compute/v1/instances/{instance_id}/actions (HTTP 204 - No Content)

Body parameters

action String _^Required - The action to perform on the instance. Possible values: start, stop or reset.

{
  "action": "reset"
}

Examples (cURL)

# Create a new instance
curl -H "Authorization: Bearer $TOKEN" \
  -X POST "https://api.genesiscloud.com/compute/v1/instances" \
  -H "Content-Type: application/json" \
  --data-raw '{
    "name": "name",
    "hostname": "hostname",
    "type": "vcpu-4_memory-12g_nvidia-rtx-3080-1",
    "image": "ac26fa2b-c6d5-47a7-bc4e-5a219797e70f",
    "ssh_keys": ["45bcd3ac-fccd-4eea-a812-21f01d665464"]
  }'

# List all instances of an account
curl -H "Authorization: Bearer $TOKEN" \
  "https://api.genesiscloud.com/compute/v1/instances"

# Get instance by id
curl -H "Authorization: Bearer $TOKEN" \
  "https://api.genesiscloud.com/compute/v1/instances/<instance_id>"

# Destroy a instance
curl -H "Authorization: Bearer $TOKEN" \
  -X DELETE "https://api.genesiscloud.com/compute/v1/instances/<instance_id>"

# Snapshot an instance
curl -H "Authorization: Bearer $TOKEN" \
  -X POST "https://api.genesiscloud.com/compute/v1/instances/<instance_id>/snapshots" \
  -H "Content-Type: application/json" \
  --data-raw '{
    "name": "snapshot-name"
  }'

# List all Snapshots of an instance
curl -H "Authorization: Bearer $TOKEN" \
  "https://api.genesiscloud.com/compute/v1/instances/<instance_id>/snapshots"

# Update the security groups of an instance
curl -H "Authorization: Bearer $TOKEN" \
  -X PATCH "https://api.genesiscloud.com/compute/v1/instances/<instance_id>" \
  -H "Content-Type: application/json" \
  --data-raw '{
    "security_groups": ["fd537d69-9db7-4a44-83b8-96f79d10071a"]
  }'

# Update the volumes of an instance
curl -H "Authorization: Bearer $TOKEN" \
  -X PATCH "https://api.genesiscloud.com/compute/v1/instances/<instance_id>" \
  -H "Content-Type: application/json" \
  --data-raw '{
    "volumes": ["0580fb4c-de74-4b83-8bdb-1fd87d89f827"]
  }'

# Get instance actions
curl -H "Authorization: Bearer $TOKEN" \
  "https://api.genesiscloud.com/compute/v1/instances/<instance_id>/actions"

# Perform a reset action
curl -H "Authorization: Bearer $TOKEN" \
  -X POST "https://api.genesiscloud.com/compute/v1/instances/<instance_id>/actions" \
  -H "Content-Type: application/json" \
  --data-raw '{
    "action": "reset"
  }'

Instances

Instance Schema​

Create an Instance​

From a snapshot​

List all Instances​

Get Instance​

Destroy an instance​

Snapshot an Instance​

List Snapshots of an Instance​

Attach/Detach Security Groups from an Instance​

Attach/Detach Volumes from an Instance​

Update an Instance​

Get Instance actions​

Perform action​

Examples (cURL)​

Instance Schema

Create an Instance

From a snapshot

List all Instances

Get Instance

Destroy an instance

Snapshot an Instance

List Snapshots of an Instance

Attach/Detach Security Groups from an Instance

Attach/Detach Volumes from an Instance

Update an Instance

Get Instance actions

Perform action

Examples (cURL)