Virtual Machine Endpoints

Endpoints are under /v1/resource/virtual-machines and require authentication.

Base URL: https://api.gpcn.com/v1

See the API Reference → for examples in TypeScript, Python, Go, and C#.

List Virtual Machines

GET /resource/virtual-machines

Returns a paginated list of virtual machines.

Query Parameters

Parameter	Type	Default	Description
`page`	integer	`1`	Page number
`limit`	integer	`10`	Items per page (max 100)
`sort`	string	`createdAt:desc`	Sort field and direction. Fields: `name`, `createdAt`, `updatedAt`, `configuration`, `region`, `datacenter`
`search`	string	—	Search by name, private IP, or public IP
`filter[teamId]`	integer	—	Filter by resource group
`filter[regionId]`	integer	—	Filter by region
`filter[datacenterId]`	UUID	—	Filter by data center
`filter[configurationId]`	integer	—	Filter by configuration
`filter[imageName]`	string	—	Filter by image name
`filter[status]`	string	—	Filter by status

Response (200 OK)

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "web-server-1",
      "status": "Running",
      "createdAt": "2026-02-20T10:00:00Z",
      "updatedAt": "2026-02-20T10:05:00Z",
      "configuration": { "cpu": 4, "ram": 8, "disk": 80 },
      "datacenter": {
        "id": "dc-uuid",
        "name": "US East 1",
        "region": "North America",
        "country": "United States"
      },
      "imageName": "Ubuntu 24.04 LTS",
      "primaryPrivateIp": "10.0.1.5",
      "primaryPublicIp": "203.0.113.10"
    }
  ],
  "meta": {
    "total": 42,
    "page": 1,
    "pageSize": 10,
    "totalPages": 5,
    "hasNextPage": true,
    "hasPreviousPage": false
  }
}

curl https://api.gpcn.com/v1/resource/virtual-machines \
  -H "X-API-Key: gpcn_your_api_key_here"

Get Virtual Machine

GET /resource/virtual-machines/{id}

Returns detailed information about a single VM, including real-time status from the cloud provider.

Response (200 OK)

{
  "success": true,
  "data": {
    "status": "Running",
    "virtualMachine": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "web-server-1",
      "teamId": 5,
      "cpu": 4,
      "ram": 8,
      "disk": 80,
      "configurationId": 45,
      "configuration": "GP-Small-1",
      "configurationCategoryCode": "general",
      "image": "Ubuntu 24.04 LTS",
      "datacenter": { "id": "dc-uuid", "name": "US East 1" },
      "createdAt": "2026-02-20T10:00:00Z",
      "updatedAt": "2026-02-20T10:05:00Z"
    },
    "usage": { },
    "consoleEnabled": true,
    "networkHotplug": true
  }
}

Create Virtual Machine

POST /resource/virtual-machines

Creates one or more VMs. Returns immediately with job tracking info.

Request Body

{
  "name": "web-server",
  "datacenterId": "dc-uuid",
  "imageId": 12,
  "configurationId": 45,
  "numberOfInstances": 1,
  "allocatePublicIp": true,
  "teamId": 5,
  "networkInterfaces": [
    { "networkId": "net-uuid", "primary": true }
  ]
}

Field	Type	Required	Description
`name`	string	Yes	VM name
`datacenterId`	UUID	Yes	Target data center
`imageId`	integer	Yes	OS image ID
`configurationId`	integer	Yes	VM size configuration ID
`numberOfInstances`	integer	No	1–10 (default: 1)
`allocatePublicIp`	boolean	No	Default: `false`
`teamId`	integer	No	Assign to a resource group
`networkInterfaces`	array	No	1–5 network attachments
`networkInterfaces[].networkId`	UUID	Yes	Network ID
`networkInterfaces[].primary`	boolean	Yes	Exactly one must be `true`

curl -X POST https://api.gpcn.com/v1/resource/virtual-machines \
  -H "X-API-Key: gpcn_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "web-server-01",
    "datacenterId": "dc-uuid",
    "imageId": 12,
    "configurationId": 45,
    "sshKeyIds": ["key-uuid"],
    "teamId": 5
  }'

Response (202 Accepted)

{
  "success": true,
  "data": [
    {
      "id": "job-uuid",
      "status": "pending",
      "resourceType": "vm",
      "createdAt": "2026-02-21T10:00:00Z"
    }
  ]
}

Edit Virtual Machine

PUT /resource/virtual-machines/{id}

Update a VM's name or resource group assignment.

Request Body

{
  "name": "new-name",
  "teamId": 5
}

Both fields are optional. Set teamId to null to remove from a resource group.

Response (200 OK)

Delete Virtual Machine

DELETE /resource/virtual-machines/{id}

Permanently deletes the VM, releases public IPs, and cleans up network interfaces.

Response (202 Accepted)

Returns a job tracking object. Poll for completion.

Start Virtual Machine

POST /resource/virtual-machines/{id}/start

Boot a stopped VM.

Response (200 OK)

Stop Virtual Machine

POST /resource/virtual-machines/{id}/stop

Gracefully shut down a running VM. Disk and configuration are preserved.

Response (200 OK)

Reset Virtual Machine

POST /resource/virtual-machines/{id}/reset

Hard reboot — power-cycle without graceful shutdown.

Response (200 OK)

Upgrade Virtual Machine

PUT /resource/virtual-machines/{id}/size

Change the VM's configuration. Only upgrades (equal or greater CPU/RAM/disk) are allowed.

Request Body

{ "configurationId": 67 }

Response (202 Accepted)

Returns a job tracking object. The VM may stop and restart during the upgrade.

Get SSH Private Key

GET /resource/virtual-machines/{id}/ssh-key

Download the SSH private key generated during VM creation.

Response (200 OK)

{
  "success": true,
  "data": {
    "privateKey": "-----BEGIN RSA PRIVATE KEY-----\n..."
  }
}

Get VM Password

GET /resource/virtual-machines/{id}/password

Retrieve the VM's SSH/RDP password (if applicable).

Response (200 OK)

{
  "success": true,
  "data": {
    "sshPassword": "generated-password"
  }
}

Get Console URL

GET /resource/virtual-machines/{id}/console

Get a temporary noVNC console URL. Open in a browser.

Response (200 OK)

{
  "success": true,
  "data": {
    "consoleUrl": "https://console.provider.com/vnc/?token=..."
  }
}

List Network Interfaces

GET /resource/virtual-machines/{id}/network-interfaces

Response (200 OK)

Array of network interface objects with private IP, public IP, primary flag, and network type.

Add Network Interface

POST /resource/virtual-machines/{id}/network-interfaces

Attach a new NIC. VM must be stopped if networkHotplug is false.

Request Body

{ "networkId": "net-uuid" }

Response (202 Accepted)

Update Network Interface

PUT /resource/virtual-machines/{id}/network-interfaces/{nicId}

Change the primary interface.

Request Body

{ "setPrimary": true }

Response (200 OK)

Remove Network Interface

DELETE /resource/virtual-machines/{id}/network-interfaces/{nicId}

Detach a NIC. VM must be stopped if networkHotplug is false.

Response (202 Accepted)

Allocate Public IP

POST /resource/virtual-machines/{id}/network-interfaces/{nicId}/public-ip

Assign a public IP to a NIC on a standard (L3) network.

Response (202 Accepted)

Release Public IP

DELETE /resource/virtual-machines/{id}/network-interfaces/{nicId}/public-ip

Remove the public IP. The IP returns to the pool.

Response (202 Accepted)

Get Available Networks

GET /resource/virtual-machines/{id}/available-networks

List networks in the same data center that can be attached to this VM.

Response (200 OK)

Array of available network objects.

Bulk Start

POST /resource/virtual-machines/bulk/start

Request Body

{ "ids": ["vm-uuid-1", "vm-uuid-2"] }

1–50 VM IDs. Returns per-ID results with partial failure support.

Bulk Stop

POST /resource/virtual-machines/bulk/stop

Same format as bulk start.

Bulk Reset

POST /resource/virtual-machines/bulk/reset

Same format as bulk start.

Bulk Delete

POST /resource/virtual-machines/bulk/delete

Request Body

{ "ids": ["vm-uuid-1", "vm-uuid-2"] }

Response (202 Accepted)

Array of job tracking objects — one per VM. Poll each job independently.

Workflow: Create a VM and Wait for Completion

VM creation is asynchronous. Here's the complete pattern — create the VM, then poll the job until it completes:

# 1. Create the VM
RESPONSE=$(curl -s -X POST https://api.gpcn.com/v1/resource/virtual-machines \
  -H "X-API-Key: gpcn_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "web-server-01", "datacenterId": "dc-uuid", "imageId": 12, "configurationId": 45}')

JOB_ID=$(echo $RESPONSE | jq -r '.data.jobId')

# 2. Poll until complete (check every 5 seconds)
while true; do
  STATUS=$(curl -s -X POST https://api.gpcn.com/v1/resource/jobs \
    -H "X-API-Key: gpcn_your_api_key_here" \
    -H "Content-Type: application/json" \
    -d "{\"jobIds\": [\"$JOB_ID\"]}" | jq -r '.data[0].status')

  echo "Status: $STATUS"
  [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ] && break
  sleep 5
done

For more on async job patterns, see Async Operations.

Next Steps

Create a VM in the Portal → — step-by-step portal walkthrough
Manage VMs → — start, stop, upgrade from the dashboard
GPU Endpoints → — GPU-accelerated VMs
Async Operations — job polling patterns
Network Endpoints → — manage VM network interfaces

Resource Group Endpoints

GPU Endpoints