Skip to main content

Virtual Machines

Run In Postman

API docs by Redocly

Virtual Machine Api Product - v1 (v1)

Virtual Machine Api Product

instances

Operations with instances, including create, delete, start, stop, reboot and other actions.

List all instances.

List Virtual Machine instances in the current tenant which is logged in.

Notes

  • You can use the extend argument to get more details from the inner objects like image or type.
query Parameters
_limit
integer ( Limit) <= 2147483647
Default: 50

limit the number of the results

_offset
integer ( Offset) [ 0 .. 2147483647 ]
Default: 0

pagination for the results limited

_sort
string ( Sort) ^(^[\w-]+:(asc|desc)(,[\w-]+:(asc|desc))*)?$
Default: "created_at:asc"

order of the results using informed fields

expand
Array of strings (Expand)
Default: ""

You can get more detailed info about: ['image', 'machine-type', 'machine-types', 'network']

header Parameters
x-tenant-id
required
string (X-Tenant-Id)

Responses

Response samples

Content type
application/json
{
  • "instances": [
    ]
}

Create an instance.

Creates a Virtual Machine instance in the current tenant which is logged in.

An instance is ready for you to use when it's in the running state.

Notes

  • For the image data, you can use the virtual-machine images list command to list all available images.
  • For the machine type data, you can use the virtual-machine machine-types list command to list all available machine types.
  • You can verify the state of your instance using the virtual-machine get command.

Rules

  • If you don't specify a VPC, the default VPC will be used. When the default VPC is not available, the command will fail.
  • If you don't specify an network interface, an default network interface will be created.
  • You can either specify an image id or an image name. If you specify both, the image id will be used.
  • You can either specify a machine type id or a machine type name. If you specify both, the machine type id will be used.
  • You can either specify an VPC id or an VPC name. If you specify both, the VPC id will be used.
  • The user data must be a Base64 encoded string.
header Parameters
x-tenant-id
required
string (X-Tenant-Id)
Request Body schema: application/json
required
name
required
string (Name) [ 1 .. 255 ] characters
required
ID (object) or Name (object) (Machine Type)
ssh_key_name
required
string (Ssh key Name) >= 0 characters
required
ID (object) or Name (object) (Image)
Availability Zone (string) or Availability Zone (null) (Availability Zone)
InstanceCreateRequestV1NetworkDefault (object) or null
Default: {"vpc":{"name":"default"},"associate_public_ip":true}
Used to perform automated configuration tasks. (string) or Used to perform automated configuration tasks. (null) (Used to perform automated configuration tasks.)

Responses

Request samples

Content type
application/json
{
  • "availability_zone": "br-regiao-1a",
  • "image": {
    },
  • "machine_type": {
    },
  • "name": "instance name",
  • "network": {
    },
  • "ssh_key_name": "keypair_name_here",
  • "user_data": "some_base64_script"
}

Response samples

Content type
application/json
{
  • "id": "9ec75090-2872-4f51-8111-53d05d96d2c6"
}

Attach network interface to an instance.

Attach network interface to an instance for a default project.

header Parameters
x-tenant-id
required
string (X-Tenant-Id)
Request Body schema: application/json
required
required
ID (object) or Name (object) (Instance)
required
object (NICRequestInterfaceField)

Responses

Request samples

Content type
application/json
{
  • "instance": {
    },
  • "network": {
    }
}

Response samples

Content type
application/json
{
  • "slug": "string",
  • "message": "string",
  • "details": { }
}

Detach a non primary network interface from an instance.

Detach a non primary network interface from an instance for a default project

header Parameters
x-tenant-id
required
string (X-Tenant-Id)
Request Body schema: application/json
required
required
ID (object) or Name (object) (Instance)
required
object (NICRequestInterfaceField)

Responses

Request samples

Content type
application/json
{
  • "instance": {
    },
  • "network": {
    }
}

Response samples

Content type
application/json
{
  • "slug": "string",
  • "message": "string",
  • "details": { }
}

Delete an instance.

Deletes permanently an instance with the id provided in the current tenant which is logged in.

Notes

  • You can use the virtual-machine list command to retrieve all instances, so
  • you can get the id of the instance that you want to delete.

Result

  • The attached ports will be deleted as well.
  • The attached volumes will be detached.
path Parameters
id
required
string <uuid> (Id)

Instance id - for help use ./mgc virtual-machines instances list .

query Parameters
delete_public_ip
boolean (Delete Public Ip)
Default: false

Flag default value false.

header Parameters
x-tenant-id
required
string (X-Tenant-Id)

Responses

Response samples

Content type
application/json
{
  • "slug": "string",
  • "message": "string",
  • "details": { }
}

Retrieve the details of a specific instance.

Get an instance details for the current tenant which is logged in.

Notes

  • You can use the virtual-machine list command to retrieve all instances, so you can get the id of the instance that you want to get details.

  • You can use the expand argument to get more details from the inner objects like image or type.

path Parameters
id
required
string (Id)

Instance id - for help use ./mgc virtual-machines instances list .

query Parameters
expand
Array of strings (Expand)
Default: ""

You can get more detailed info about: ['image', 'machine-type', 'machine-types', 'network']

header Parameters
x-tenant-id
required
string (X-Tenant-Id)

Responses

Response samples

Content type
application/json
{
  • "availability_zone": "br-regiao-1a",
  • "created_at": "2022-06-10T18:33:12Z",
  • "error": {
    },
  • "id": "2ae0b896-855c-456c-b4a5-c8f4e6d2f4f6",
  • "image": {
    },
  • "machine_type": {
    },
  • "name": "instance name",
  • "network": {
    },
  • "ssh_key_name": "keypair_name_here",
  • "state": "running",
  • "status": "completed",
  • "updated_at": "2022-06-11T18:33:12Z",
  • "user_data": "some_base_64_str"
}

Reboot an instance.

Reboots a Virtual Machine instance with the id provided in the current tenant which is logged in.

Notes

  • You can use the virtual-machine list command to retrieve all instances, so you can get the id of the instance that you want to reboot.

Rules

  • The instance must be in the running or suspend state.
path Parameters
id
required
string <uuid> (Id)

Instance id - for help use ./mgc virtual-machines instances list .

header Parameters
x-tenant-id
required
string (X-Tenant-Id)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Renames an instance.

Renames a Virtual Machine instance with the id provided in the current tenant which is logged in.

Notes

  • You can use the virtual-machine list command to retrieve all instances, so you can get the id of the instance that you want to rename.
path Parameters
id
required
string (Id)

Instance id - for help use ./mgc virtual-machines instances list .

header Parameters
x-tenant-id
required
string (X-Tenant-Id)
Request Body schema: application/json
required
name
required
string (Name) [ 1 .. 255 ] characters

New name

Responses

Request samples

Content type
application/json
{
  • "name": "new instance name"
}

Response samples

Content type
application/json
{
  • "slug": "string",
  • "message": "string",
  • "details": { }
}

Changes an instance machine-type.

Changes a Virtual Machine instance machine type with the id provided in the current tenant which is logged in.

Notes

  • You can use the virtual-machine list command to retrieve all instances, so you can get the id of the instance that you want to change the machine type.

Rules

  • The instance must be in the running or stopped state.
  • The new machine type must be compatible with the current machine type.
  • The new machine type must be available in the same region as the current machine type.
  • You must provide either the machine type id or the machine type name, if you provide both, the machine type id will be used.
path Parameters
id
required
string <uuid> (Id)

Instance id - for help use ./mgc virtual-machines instances list .

header Parameters
x-tenant-id
required
string (X-Tenant-Id)
Request Body schema: application/json
required
required
ID (object) or Name (object) (Machine Type)
Any of
id
required
string (Id) [ 1 .. 255 ] characters

Responses

Request samples

Content type
application/json
{
  • "machine_type": {
    }
}

Response samples

Content type
application/json
{
  • "slug": "string",
  • "message": "string",
  • "details": { }
}

Starts an instance.

Starts a Virtual Machine instance with the id provided in the current tenant which is logged in.

Notes

  • You can use the virtual-machine list command to retrieve all instances, so you can get the id of the instance that you want to start.

Rules

  • The instance must be in the stopped or suspended states.
path Parameters
id
required
string <uuid> (Id)

Instance id - for help use ./mgc virtual-machines instances list .

header Parameters
x-tenant-id
required
string (X-Tenant-Id)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Stops an instance.

Stops a Virtual Machine instance with the id provided in the current tenant which is logged in.

Notes

  • You can use the virtual-machine list command to retrieve all instances, so you can get the id of the instance that you want to stop.

Rules

  • The instance must be in the running state.
path Parameters
id
required
string <uuid> (Id)

Instance id - for help use ./mgc virtual-machines instances list .

header Parameters
x-tenant-id
required
string (X-Tenant-Id)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Suspends instance.

Suspends a Virtual Machine instance with the id provided in the current tenant which is logged in.

Notes

  • You can use the virtual-machine list command to retrieve all instances, so you can get the id of the instance that you want to suspend.

Rules

  • The instance must be in the running state.
path Parameters
id
required
string <uuid> (Id)

Instance id - for help use ./mgc virtual-machines instances list .

header Parameters
x-tenant-id
required
string (X-Tenant-Id)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

images

Operations with images for instances.

Retrieves all images.

Retrieve a list of images allowed for the current region.

query Parameters
_limit
integer ( Limit) <= 2147483647
Default: 50
_offset
integer ( Offset) [ 0 .. 2147483647 ]
Default: 0
_sort
string ( Sort) ^(^[\w-]+:(asc|desc)(,[\w-]+:(asc|desc))*)?$
Default: "platform:asc,end_life_at:desc"

Responses

Response samples

Content type
application/json
{
  • "images": [
    ]
}

machine-types

Operations with machine types for instances.

Retrieves all machine-types.

Retrieves a list of machine types allowed for the current tenant which is logged in.

query Parameters
_limit
integer ( Limit) <= 2147483647
Default: 50

limit the number of the results

_offset
integer ( Offset) [ 0 .. 2147483647 ]
Default: 0

pagination for the results limited

_sort
string ( Sort) ^(^[\w-]+:(asc|desc)(,[\w-]+:(asc|desc))*)?$
Default: "created_at:asc"

order of the results using informed fields

Responses

Response samples

Content type
application/json
{
  • "machine_types": [
    ]
}

snapshots

Operations with snapshots for instances.

Lists all snapshots.

List all snapshots in the current tenant which is logged in.

Notes

  • You can use the expand argument to get more details from the inner objects like image and machine types.
query Parameters
_limit
integer ( Limit) <= 2147483647
Default: 50

limit the number of the results

_offset
integer ( Offset) [ 0 .. 2147483647 ]
Default: 0

pagination for the results limited

_sort
string ( Sort) ^(^[\w-]+:(asc|desc)(,[\w-]+:(asc|desc))*)?$
Default: "created_at:asc"

order of the results using informed fields

expand
Array of strings (Expand)
Default: ""

You can get more detailed info about: ['image', 'machine-type']

header Parameters
x-tenant-id
required
string (X-Tenant-Id)

Responses

Response samples

Content type
application/json
{
  • "snapshots": [
    ]
}

Create a snapshot of an instance.

Create a snapshot of a Virtual Machine in the current tenant which is logged in.
A Snapshot is ready for restore when it's in available state.

Notes

  • You can verify the state of snapshot using the snapshot get command,
  • To create a snapshot it's mandatory inform a valid and unique name.

Rules

  • It's only possible to create a snapshot of a valid virtual machine.
  • It's not possible to create 2 snapshots with the same name.
  • You can inform ID or Name from a Virtual Machine if both informed the priority will be ID.
header Parameters
x-tenant-id
required
string (X-Tenant-Id)
Request Body schema: application/json
required
name
required
string (Name) [ 1 .. 255 ] characters
required
ID (object) or Name (object) (Instance)

Responses

Request samples

Content type
application/json
{
  • "instance": {
    },
  • "name": "snapshot name"
}

Response samples

Content type
application/json
{
  • "id": "9ec75090-2872-4f51-8111-53d05d96d2c6"
}

Delete a Snapshot.

Deletes an snapshot with the id provided in the current tenant which is logged in.

Notes

  • You can use the Snapshots list command to retrieve all snapshots, so
  • you can get the id of the snapshot that you want to delete.
path Parameters
id
required
string <uuid> (Id)
header Parameters
x-tenant-id
required
string (X-Tenant-Id)

Responses

Response samples

Content type
application/json
{
  • "slug": "string",
  • "message": "string",
  • "details": { }
}

Retrieve the details of an snapshot.

Get an snapshot details for the current tenant which is logged in.

Notes

  • You can use the snapshots list command to retrieve all snapshots, so you can get the id of the snapshot that you want to get details.

  • You can use the expand argument to get more details from the inner objects like image or type.

path Parameters
id
required
string (Id)
query Parameters
expand
Array of strings (Expand)
Default: ""

You can get more detailed info about: ['image', 'machine-type']

header Parameters
x-tenant-id
required
string (X-Tenant-Id)

Responses

Response samples

Content type
application/json
{
  • "created_at": "2022-06-10T18:33:12Z",
  • "id": "4830bfbe-0362-4ebb-a8ba-f36be4b4bc6a",
  • "instance": {
    },
  • "name": "snapshot name",
  • "size": 1000,
  • "state": "available",
  • "status": "completed",
  • "updated_at": "2022-06-11T18:33:12Z"
}

Restore a snapshot to an instance.

Restore a snapshot of an instance with the current tenant which is logged in.

Notes

  • You can check the snapshot state using snapshot list command.
  • Use "machine-types list" to see all machine types available.

Rules

  • A Snapshot is ready to restore when it's in available state.
  • To restore a snapshot you have to inform the new instance settings.
  • You must choose a machine-type that has a disk equal or larger than the original instance.
path Parameters
id
required
string (Id)
header Parameters
x-tenant-id
required
string (X-Tenant-Id)
Request Body schema: application/json
required
name
required
string (Name) [ 1 .. 255 ] characters
required
ID (object) or Name (object) (Machine Type)
ssh_key_name
required
string (Ssh Key Name) >= 0 characters
Availability Zone (string) or Availability Zone (null) (Availability Zone)
InstanceCreateRequestV1NetworkDefault (object) or null
Default: {"vpc":{"name":"default"},"associate_public_ip":true}
User Data (string) or User Data (null) (User Data)

Responses

Request samples

Content type
application/json
{
  • "availability_zone": "br-regiao-1a",
  • "machine_type": {
    },
  • "name": "instance name",
  • "network": {
    },
  • "ssh_key_name": "keypair_name_here",
  • "user_data": "some_base64_script"
}

Response samples

Content type
application/json
{
  • "id": "9ec75090-2872-4f51-8111-53d05d96d2c6"
}

Renames a snapshot.

Renames a Snapshot with the id provided in the current tenant which is logged in.

Notes

  • You can use the snapshots list command to retrieve all snapshots, so you can get the id of the snapshot that you want to rename.
path Parameters
id
required
string (Id)
header Parameters
x-tenant-id
required
string (X-Tenant-Id)
Request Body schema: application/json
required
name
required
string (Name) [ 1 .. 255 ] characters

Responses

Request samples

Content type
application/json
{
  • "name": "new snapshot name"
}

Response samples

Content type
application/json
{
  • "slug": "string",
  • "message": "string",
  • "details": { }
}

backups

Lists all backups in the current tenant.

List Virtual Machine backups in the current tenant which is logged in.

Notes

  • You can use the extend argument to get more details from the inner objects like image or type.
query Parameters
_limit
integer ( Limit) <= 2147483647
Default: 50

limit the number of the results

_offset
integer ( Offset) [ 0 .. 2147483647 ]
Default: 0

pagination for the results limited

_sort
string ( Sort) ^(^[\w-]+:(asc|desc)(,[\w-]+:(asc|desc))*)?$
Default: "created_at:asc"

order of the results using informed fields

expand
Array of strings (Expand)
Default: ""

You can get more detailed info about: ['instance']

header Parameters
x-tenant-id
required
string (X-Tenant-Id)

Responses

Response samples

Content type
application/json
{
  • "backups": [
    ]
}

Create a backup of a virtual machine asynchronously.

Create a backup of a Virtual Machine with the current tenant which is logged in.

A Backup is ready for restore when it's in completed status.

Rules

  • It's possible to create a maximum of 100 backups per virtual machine.
  • In case quota reached, choose a backup to remove.
  • You can inform ID or Name from a Virtual Machine if both informed the priority will be ID.
  • It's only possible to create a backup of a valid virtual machine.
  • Each backup must have a unique name. It's not possible to create backups with the same name.
header Parameters
x-tenant-id
required
string (X-Tenant-Id)
Request Body schema: application/json
required
name
required
string (Name) [ 1 .. 255 ] characters
required
ID (object) or Name (object) (Instance)

Responses

Request samples

Content type
application/json
{
  • "instance": {
    },
  • "name": "backup name"
}

Response samples

Content type
application/json
{
  • "id": "9ec75090-2872-4f51-8111-53d05d96d2c6"
}

Delete a backup of a virtual machine asynchronously.

delete a backup from instance

path Parameters
id
required
string <uuid> (Id)
header Parameters
x-tenant-id
required
string (X-Tenant-Id)

Responses

Response samples

Content type
application/json
{
  • "slug": "string",
  • "message": "string",
  • "details": { }
}

Retrieve the details of a backup.

Get a backup details for the current tenant which is logged in.

Notes

  • You can use the backup list command to retrieve all backups, so you can get the id of the backup that you want to get details.

  • You can use the expand argument to get more details from the object like instance.

path Parameters
id
required
string (Id)
query Parameters
expand
Array of strings (Expand)
Default: ""

You can get more detailed info about: ['instance']

header Parameters
x-tenant-id
required
string (X-Tenant-Id)

Responses

Response samples

Content type
application/json
{
  • "backup_type": "daily",
  • "created_at": "2022-06-10T18:33:12Z",
  • "id": "2ae0b896-855c-456c-b4a5-c8f4e6d2f4f6",
  • "instance": {
    },
  • "min_disk": 10,
  • "name": "backup name",
  • "size": 1000,
  • "state": "available",
  • "status": "completed",
  • "updated_at": "2022-06-11T18:33:12Z"
}

Copy a backup of a virtual machine asynchronously.

Copy a backup region

path Parameters
id
required
string <uuid> (Id)
header Parameters
x-tenant-id
required
string (X-Tenant-Id)
Request Body schema: application/json
required
region
required
string (Regions)
Enum: "br-se1" "br-se-1" "br-ne-1"

Responses

Request samples

Content type
application/json
{
  • "region": "br-ne-1"
}

Response samples

Content type
application/json
{
  • "slug": "string",
  • "message": "string",
  • "details": { }
}

Renames a backup

Renames a backup with the id provided in the current tenant which is logged in.

Rules

  • You can use the backup list command to retrieve all backups, so you can get the id of the backup that you want to rename.
  • A Backup can only renamed when it's in completed status.
  • Each backup must have a unique name.
path Parameters
id
required
string (Id)
header Parameters
x-tenant-id
required
string (X-Tenant-Id)
Request Body schema: application/json
required
name
required
string (Name) [ 1 .. 255 ] characters

Responses

Request samples

Content type
application/json
{
  • "name": "new backup name"
}

Response samples

Content type
application/json
{
  • "slug": "string",
  • "message": "string",
  • "details": { }
}

Restore a backup to a virtual machine

Restore a backup of a Virtual Machine with the current tenant which is logged in.
A Backup is ready for restore when it's in completed status.

Notes

  • You can verify the status of backup using the backup list command.
  • Use machine-types list to see all machine types available.

Rules

  • To restore a backup you have to inform the new virtual machine information.
  • You can choose a machine-type that has a disk equal or larger than the minimum disk of the backup.
path Parameters
id
required
string <uuid> (Id)
header Parameters
x-tenant-id
required
string (X-Tenant-Id)
Request Body schema: application/json
required
name
required
string (Name) [ 1 .. 255 ] characters
required
ID (object) or Name (object) (Machine Type)
ssh_key_name
required
string (Ssh Key Name)
Availability Zone (string) or Availability Zone (null) (Availability Zone)
required
object (InstanceCreateRequestV1NetworkDefault)
User Data (string) or User Data (null) (User Data)

Responses

Request samples

Content type
application/json
{
  • "availability_zone": "br-regiao-1a",
  • "machine_type": {
    },
  • "name": "instance name",
  • "network": {
    },
  • "ssh_key_name": "keypair_name_here",
  • "user_data": "some_base64_script"
}

Response samples

Content type
application/json
{
  • "id": "9ec75090-2872-4f51-8111-53d05d96d2c6"
}