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 datacenter 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 datacenter where VMs will be created. The backend automatically selects the appropriate cloud provider based on datacenter.

  • imageId
    Type: stringFormat: uuid
    required

    UUID of the OS image to use

  • name
    Type: string
    required

    Base name for the VM(s). If numberOfInstances > 1, VMs will be 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). Phase 3 Stage 6 cutover replaced the legacy configurationId (integer FK) with this UUID-typed identifier. Hard cut — clients sending configurationId will receive a 400.

  • allocatePublicIp
    Type: boolean

    Whether to allocate a public IP address on the primary network. Only supported on standard networks, not custom L2 networks.

  • authMethod
    Type: stringenum

    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.
    values
    • ssh-key
    • password
    • custom
  • networkInterfaces
    Type: array object[] 1…5

    Optional array of network interface configurations (max 5 network interfaces). Exactly one interface must be marked as primary. If not provided, the default network for the datacenter will be created/used automatically. All networks must be in the same datacenter as the VM. If allocatePublicIp is true, the primary network must be a standard (L3) network.

    Example:

    [
  { "networkId": "550e8400-e29b-41d4-a716-446655440000", "primary": true },
  { "networkId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "primary": false }
]
  • 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     Pattern: ^[A-Za-z0-9!@#%\-_.]+$

    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.

  • resourceGroupId
    Type: stringFormat: uuid

    Optional resource group ID to assign VMs to

  • sshKeyId
    Type: stringFormat: uuid

    SSH key library UUID to use for authentication. Required when authMethod is ssh-key. Use GET /resource/ssh-keys to list available keys.

  • username
    Type: string
    min length:  
    3
    max length:  
    20

    Linux only. Username for the VM's admin user. Only supported when config.customizations.username is true. Overrides the image default (e.g. ubuntu, centos, debian). If omitted, the image's default username is used. Reserved system usernames (e.g. root, guest) are rejected with a 400. See GET /resource/data-centers/{id}/virtual-machine-images → meta.constraints.usernames for the full list.

Responses
  • 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": "",
  "resourceGroupId": "",
  "numberOfInstances": 1,
  "allocatePublicIp": false,
  "networkInterfaces": [
    {
      "networkId": "",
      "primary": true
    }
  ],
  "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-05-19T14:02:02.487Z",
        "timeRemaining": "string",
        "canRetry": true,
        "isCompleted": true,
        "hasFailed": true,
        "resourceId": "123e4567-e89b-12d3-a456-426614174000",
        "resourceName": "string",
        "createdAt": "2026-05-19T14:02:02.487Z",
        "updatedAt": "2026-05-19T14:02:02.487Z"
      }
    ]
  },
  "meta": null
}

VM creation initiated successfully (async operation)