---
title: "Create virtual machine"
method: POST
path: "/v1/vms"
tags: ["Virtual machines"]
---

# Create virtual machine

`POST /v1/vms`

## Request

- Base URL: `https://api.emma.ms/external`
- URL: `https://api.emma.ms/external/v1/vms`
- Auth: HTTP bearer

This method creates a virtual machine according to the specified parameters.

To create a virtual machine, follow these steps:

1. Select a data center using the `/v1/data-centers` endpoint. The data center determines the provider and location of the virtual machine.

2. Select an available hardware configuration for the virtual machine using the `/v1/vms-configs` endpoint.

3. Select an SSH key for the Linux virtual machine using the `/v1/ssh-keys` endpoint.

4. Select an operating system using the `/v1/operating-systems` endpoint.

5. Choose one of the cloud network types: _multi-cloud_, _isolated,_ or _default_. Choose the _multi-cloud_ network type if you need to connect compute instances from different providers.

Providers support the following types of networks:
- AWS - multi-cloud, isolated, default
- Azure - multi-cloud, isolated, default
- DigitalOcean - default
- Gcore - default
- GCP - multi-cloud, isolated, default
- IONOS - default
- OVHCloud - default
- VMware - default
- Nebius - default
- Hetzner - default

You may choose not to specify a security group. In this case, the virtual machine will be added to the default security group.

## Request body

- VmCreate
  - `name` string, required: Virtual machine name
  - `dataCenterId` string, required: ID of the provider's data center
  - `osId` integer, required: ID of the operating system
  - `cloudNetworkType` 'isolated' | 'multi-cloud' | 'default', required: Type of the cloud network
  - `vCpuType` 'shared' | 'standard' | 'hpc', required: Type of virtual Central Processing Units (vCPUs)
  - `vCpu` integer, required: Number of virtual Central Processing Units (vCPUs)
  - `ramGb` integer, required: Capacity of the RAM in gigabytes
  - `volumeType` 'ssd' | 'ssd-plus', required: Volume type
  - `volumeGb` integer, required: Capacity of the volume in gigabytes
  - `acceleratorTypeId` string: GPU accelerator type ID
  - `accelerators` number: Quantity of GPU accelerators
  - `sshKeyId` integer, nullable: SSH-key ID
  - `userPassword` string, nullable: User password for the Windows virtual machine. Not required for the AWS and GCP virtual machines.
  - `securityGroupId` integer: ID of the security group
  - `subnetworkId` string: ID of the subnetwork
  - `privateIp` string: IP address within the subnetwork range
  - `ipAddressing` 'ipv4' | 'dual_stack': IP addressing, ipv4 or dual stack (ipv4 + ipv6)
  - `initScript` string, nullable: Optional bash script to execute after the virtual machine is created. Supported for Linux operating systems only — providing initScript for a Windows osId returns 422.
  - `installSystemKey` boolean, nullable: Install the emma system SSH key on the virtual machine. Not supported for Windows operating system or VMware provider.

## Response `200`

Virtual machine created

- 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
- `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)