--- title: "Perform actions with a virtual machine" method: POST path: "/v1/vms/{vmId}/actions" tags: ["Virtual machines"] --- # Perform actions with a virtual machine `POST /v1/vms/{vmId}/actions` ## Request - Base URL: `https://api.emma.ms/external` - URL: `https://api.emma.ms/external/v1/vms/{vmId}/actions` - Auth: HTTP bearer This method performs several actions with a virtual machine: - Start a virtual machine - Shutdown a virtual machine - Reboot a virtual machine - Transfer a virtual machine - Clone a virtual machine - Edit compute resources of a virtual machine (for DigitalOcean, OVH, Hetzner virtual machine resize use `VmEditHardware` option only) - Edit compute resources and system disk of a virtual machine - Attach data volume to the virtual machine - Detach volume from the virtual machine - Rename a virtual machine ## Path parameters - `vmId` integer, required ## Request body - union - VmStart - `action` 'start', required: Action with a virtual machine - VmShutdown - `action` 'shutdown', required: Action with a virtual machine - VmReboot - `action` 'reboot', required: Action with a virtual machine - VmTransfer - `action` 'transfer', required: Action with a virtual machine - `dataCenterId` string, required: ID of the provider's data center - `isKeepOriginalInstance` boolean: Indicate if it is necessary to keep the original instance - VmClone - `action` 'clone', required: Action with a virtual machine - `name` string, required: Name of the virtual machine - VmResizeCompute - `action` 'resizecompute', required: Action with a virtual machine. **Note:** To retrieve available configurations for DigitalOcean system volumes, use the `edithardware` action - `vCpu` integer, required: Number of virtual Central Processing Units (vCPUs) - `vCpuType` 'shared' | 'standard' | 'hpc', required: Type of virtual Central Processing Units (vCPUs) - `ramGb` integer, required: Capacity of the RAM in gigabytes - `accelerators` number: Quantity of GPU accelerators. Optional for non-GPU virtual machines. Required for GPU virtual machines. - VmEditHardware - `action` 'edithardware', required: Action with a virtual machine - `vCpu` integer, required: Number of virtual Central Processing Units (vCPUs) - `vCpuType` 'shared' | 'standard' | 'hpc': Type of virtual Central Processing Units (vCPUs) - `ramGb` integer, required: Capacity of the RAM in gigabytes - `volumeGb` integer, required: Capacity of the volume in gigabytes - VolumeAttach - `action` 'attach', required: Action with a virtual machine - `volumeId` integer, required: Volume ID to attach to the virtual machine - VolumeDetach - `action` 'detach', required: Action with a virtual machine - `volumeId` integer, required: Volume ID to detach from the virtual machine - VmRename - `action` 'rename', required: Action with a virtual machine - `name` string, required: A new name of the virtual machine ## Response `200` Successful operation - Vm - `id` integer: ID of the virtual machine - `createdAt` string: Date and time when the virtual machine was created - `createdByName` string: Name of the user who created the virtual machine - `createdById` integer: ID of the user who created the virtual machine - `modifiedAt` string: Date and time when the virtual machine was last edited - `modifiedByName` string: Name of the user who last edited the virtual machine - `modifiedById` integer: ID of the user who last edited the virtual machine - `name` string: Name of the virtual machine - `projectId` integer: Project ID - `status` 'POWERED_ON' | 'POWERED_OFF' | 'BUSY' | 'DRAFT' | 'FAILED_CREATION': Status of the virtual machine - `provider` object - `id` integer: ID of the cloud provider - `name` string: Name of the cloud provider - `location` object - `id` integer: ID of the data center location - `name` string: Name of the data center location (city or state) - `country` string: Country of the data center location - `continent` string: Name of the geographical continent - `region` string: Name of the geographical region - `latitude` number, double: Approximate latitude of the geographical location - `longitude` number, double: Approximate longitude of the geographical location - `dataCenter` object - `id` string: Data center ID - `name` string: Data center name - `providerId` integer: ID of the cloud provider - `providerName` string: Name of the cloud provider - `locationId` integer: ID of the data center location - `locationName` string: Name of the data center location - `os` object - `id` integer: ID of the operating system - `family` string: Family of the operating system - `architecture` string: Architecture of the operating system - `type` string: Type of the operating system - `version` string: Version of the operating system - `vCpu` integer: Number of virtual Central Processing Units (vCPUs) - `vCpuType` 'shared' | 'standard' | 'hpc': Type of virtual Central Processing Units (vCPUs) - `cloudNetworkType` 'isolated' | 'multi-cloud' | 'default': Cloud network type - `ramGb` integer: Capacity of the RAM in gigabytes - `disks` object[]: List of volumes - `id` integer: Volume ID - `sizeGb` integer: Volume size in gigabytes - `typeId` integer: ID of the volume type - `type` 'hdd' | 'ssd' | 'ssd-plus': Volume type - `isBootable` boolean: Indicates whether the volume is bootable or not - `deviceIdentifier` string, nullable: Device identifier of the volume as seen by the operating system - `localDisks` object[], nullable: Local SSD storage directly attached to the host. Data is ephemeral and will be lost when the VM is stopped or deleted. - `sizeTb` number: Volume size in TB - `typeId` integer: ID of the volume type - `type` string: Volume type - `accelerator` object, nullable: GPU accelerator - `acceleratorTypeId` string: GPU accelerator type ID - `acceleratorType` string: GPU accelerator type - `accelerators` number: Quantity of GPU accelerators - `totalGpuMemoryGb` integer: Total GPU memory (GPU) - `networks` object[] - `id` integer: Network ID - `ip` string: IPv4 or IPv6 address - `ipVersion` number: IP version - `networkTypeId` integer: ID of the network type - `networkType` string: Network type - `securityGroup` object - `id` integer: ID of the security group - `name` string: Name of the security group - `subnetwork` object - `id` string: ID of the subnetwork - `name` string: Name of the subnetwork - `sshKeyId` integer, nullable: SSH key ID - `userName` string, nullable: User name - `userPassword` string, nullable: User password - `cost` object - `unit` string: Cost period - `currency` string: Currency of cost - `price` number: Cost of the virtual machine for the period - `tags` Tag[], nullable - `tagId` string, uuid, required: tag id - `key` string, required: tag key - `value` string, nullable: tag key value - `systemKeyInstalled` boolean: Indicates whether the emma system SSH key is installed on the virtual machine - `workflowExecutionInfo` VmWorkflowExecution, nullable: Workflow execution that provisioned the virtual machine - `executionId` string, uuid: Id of the workflow execution - `workflowTemplateId` integer, nullable: Id of the workflow template that was executed; returned even after the template has been deleted - `workflowTemplateName` string: Name of the workflow template - `workflowExists` boolean: Whether the workflow template still exists; false when it was deleted, in which case clients must not render a link to the template - `status` 'PENDING' | 'RUNNING' | 'SUCCESS' | 'FAILED': Status of the workflow execution - `versionId` integer: ID of the workflow version used to create the instance - `versionName` string: Name of the workflow version used to create the instance - `versionExists` boolean: Whether the workflow version still exists; false when it was deleted, in which case clients must not render a link to the template ## Other responses - `400`: Bad request - `401`: Unauthorized - `403`: Forbidden - Access is denied - `404`: Not found - `422`: Unprocessable entity - `500`: Internal server error --- [API](https://skmtc.dev/emma/apis/public-emma-api.md) - [All operations](https://skmtc.dev/emma/apis/public-emma-api/llms.txt) - [OpenAPI document](https://skmtc.dev/emma/apis/public-emma-api/revisions/9e55f0920078?raw)