Create a new virtual machine

​

Create one or more virtual machines with the specified configuration.

Single VM: Returns a single job object for tracking.

Multiple VMs: Returns an array of job objects - one for each VM created. Each VM is provisioned in parallel after data center initialization.

Batch Creation: Use numberOfInstances to create multiple VMs (e.g., "web-server-1", "web-server-2", etc.). Each VM gets its own resource job for independent progress tracking.

Body

required
application/json
  • datacenterId
    Type: stringFormat: uuid
    required

    ID of the data center where VMs will be created. The backend automatically selects the appropriate cloud provider based on data center.

  • imageId
    Type: stringFormat: uuid
    required

    UUID of the OS image to use

  • name
    Type: string
    min length:  
    1
    max length:  
    60
    required

    Friendly display name for the VM(s). Letters, numbers, spaces, periods, and hyphens only; cannot start or end with a hyphen. If numberOfInstances > 1, VMs are named "name-1", "name-2", etc.

  • skuId
    Type: stringFormat: uuid
    required

    UUID of the VM SKU (from GET /resource/data-centers/{id}/virtual-machine-sizes).

  • acquirePublicIp
    Type: boolean

    Ask the platform for a new public address on the primary interface. On a VPC-shaped body it acquires one elastic address into the VPC's holdings on that VPC's anchor and attaches it to the interface — one address, which is why it cannot be combined with more than one instance. On a legacy body it allocates one address per instance onto each machine's own NIC, and is only supported on standard networks, not custom L2 ones. Mutually exclusive with publicIpId.

  • authMethod
    Type: "ssh-key" or "password" or "custom"enum

    Authentication method for the VM. Required when the image's config.customizations includes sshKey or password; omit for images with no auth customizations (e.g. appliances with fixed credentials).

    • ssh-key: SSH key only — sshKeyId required, password auth disabled entirely.
    • password: Password auth — password required, never stored server-side.
  • hostname
    Type: string
    min length:  
    1
    max length:  
    60

    Optional guest OS hostname. Must start with a letter; letters, digits, and hyphens only; no spaces; cannot end with a hyphen. Derived from the name when omitted. For multiple instances a "-N" suffix is appended.

  • networkId
    Type: stringFormat: uuid

    The one legacy network the machine is born on. Mutually exclusive with subnetId; omit both and the machine lands on the tenant's default network in the data center, which is created in the Default resource group if none exists yet. Omitting both is a request to use (or create) that network, so the caller must be able to see the default network and hold network:update in its resource group — or, with no default network yet, network:create in the Default group. A caller whose grants are scoped to other groups gets the 403 or 404 below and must name a network it can use.

    Must be in the same data center as the VM, and if acquirePublicIp is true it must be a standard (L3) network. Additional interfaces are added after creation through the network-interface attach endpoint.

  • numberOfInstances
    Type: number
    min:  
    1
    max:  
    10

    Number of VMs to create (default 1, max 10)

  • password
    Type: string
    min length:  
    12
    max length:  
    20

    VM admin password. Required when authMethod is password. Must be 12–20 characters and contain at least one uppercase letter, one lowercase letter, one digit, and one special character. Allowed special characters: ! @ # % - _ . The password is passed to the provisioning system and never stored server-side.

  • publicIpId
    Type: stringFormat: uuid

    A HELD VPC elastic address to attach to the primary interface. Requires a VPC subnet interface, and the address must belong to that subnet's VPC — an address of any other VPC, like an unknown id, answers 404 "Public IP not found". Mutually exclusive with acquirePublicIp.

  • resourceGroupId
    Type: stringFormat: uuid

    The resource group to create into. Omitted: the resource is placed in the tenant's Default resource group.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for post/resource/virtual-machines
curl https://api.gpcn.com/v1/resource/virtual-machines \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_SECRET_TOKEN' \
  --data '{
  "datacenterId": "",
  "imageId": "",
  "skuId": "",
  "name": "Web Server v1.2",
  "hostname": "web-server-1",
  "resourceGroupId": "",
  "numberOfInstances": 1,
  "acquirePublicIp": false,
  "publicIpId": "",
  "networkId": "",
  "subnetId": "",
  "authMethod": "ssh-key",
  "sshKeyId": "",
  "password": "",
  "username": "myuser"
}'

{
  "success": true,
  "message": "string",
  "data": {
    "jobs": [
      {
        "jobId": "123e4567-e89b-12d3-a456-426614174000",
        "resourceType": "virtual_machine",
        "resourceDisplayName": "string",
        "operation": "create",
        "stage": "initializing",
        "progressPercentage": 0,
        "message": "string",
        "errorMessage": "string",
        "estimatedCompletion": "2026-10-21T16:19:07.193Z",
        "timeRemaining": "string",
        "canRetry": true,
        "isCompleted": true,
        "isTerminal": true,
        "hasFailed": true,
        "resourceId": "123e4567-e89b-12d3-a456-426614174000",
        "resourceName": "string",
        "createdAt": "2026-10-21T16:19:07.193Z",
        "updatedAt": "2026-10-21T16:19:07.193Z"
      }
    ]
  },
  "meta": null
}

VM creation initiated successfully (async operation)

Previous
Get paginated list of virtual machines
Next
Get Virtual Machine Details