---
title: "Compute API"
description: "Create and manage VMs, SSH keys, security groups, backups, and startup scripts over the Edge REST API."
url: https://edge.network/docs/api/compute/
---

# Compute API

# Compute API

Manage virtual machines and everything around them — SSH keys, security groups, snapshots,
backups, private networks, and startup scripts — under
`/api/compute`.
All endpoints require [authentication](https://edge.network/docs/api/authentication).

## Create a VM

```
curl -X POST https://edge.network/api/compute/vms \
  -H "Authorization: Bearer ek_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "web-01",
    "region": "london",
    "osTemplate": "ubuntu-24.04",
    "vcpu": 2,
    "ram": 4,
    "disk": 80,
    "sshKeyIds": ["key_abc123"],
    "setupScript": "#!/bin/bash\napt update"
  }'
```

| Field | Required | Description |
| name | Yes | 1–64 characters, letters, digits, and hyphens |
| region | Yes | Region id from `GET /api/compute/regions` |
| osTemplate | Yes | Template id from `GET /api/compute/os-templates` |
| vcpu / ram / disk | Yes | vCPUs (1–128), RAM in GB (1–512), disk in GB (10–10000) |
| sshKeyIds | No | SSH key ids to attach at first boot |
| securityGroupIds | No | Security group ids to attach |
| password | No | Root password (min 8 chars). Omit to have one generated and returned once. |
| setupScript | No | Bash script to run on first boot. See [Startup Scripts](https://edge.network/docs/compute/scripts) for the library. |

Returns `201`:

```
{
  "vm": {
    "id": "vm_xyz789",
    "name": "web-01",
    "status": "provisioning",
    "region": "london",
    "vcpu": 2,
    "ram": 4,
    "disk": 80,
    "os": { "name": "Ubuntu 24.04" },
    "network": { "publicIp": "pending" },
    "createdAt": "2026-07-31T15:04:05Z"
  },
  "generatedPassword": "..."
}
```

## VMs

| Endpoint | Description |
| GET /api/compute/vms | List VMs — returns `{ vms }` |
| GET /api/compute/vms/:id | Get a VM — returns `{ vm }` |
| PATCH /api/compute/vms/:id | Rename — body `{ "name": "..." }` |
| DELETE /api/compute/vms/:id | Destroy the VM |
| POST /api/compute/vms/:id/start | stop | restart | reset | Power actions — each returns the updated `{ vm }` |
| POST /api/compute/vms/:id/suspend | resume | Suspend / resume |
| POST /api/compute/vms/:id/resize | Change specs — body `{ vcpu?, ram?, disk? }` |
| POST /api/compute/vms/:id/reinstall | Reinstall the OS — body `{ osId }` |
| POST /api/compute/vms/:id/password | Change the root password |
| POST /api/compute/vms/:id/hostname | Change the hostname |

## Stats, Metrics & Console

| Endpoint | Description |
| GET /api/compute/vms/:id/stats | Live CPU / RAM / disk / network usage |
| GET /api/compute/vms/:id/metrics?period=24h | Metric history — `period` is `1h`, `6h`, `24h`, or `7d` |
| POST /api/compute/vms/:id/console | Create a VNC console session (returns session token + password) |
| GET /api/compute/vms/:id/events | Recent lifecycle events for one VM |
| GET /api/compute/vms/:id/bandwidth?month=2026-07 | Monthly bandwidth usage |

## SSH Keys & Security Groups

| Endpoint | Description |
| GET | POST /api/compute/ssh-keys | List keys / add a key — body `{ name, publicKey }` |
| DELETE /api/compute/ssh-keys/:id | Remove a key |
| GET | POST | DELETE /api/compute/vms/:id/ssh-keys/:keyId | List / attach / detach keys on a VM |
| GET | POST /api/compute/security-groups | List / create groups — body `{ name, description?, rules? }` |
| GET | PATCH | DELETE /api/compute/security-groups/:id | Get / update / delete a group |
| GET | POST /api/compute/security-groups/:id/rules | List / add rules — `{ direction, protocol, portRange?, source, description? }` |
| PATCH | DELETE /api/compute/security-groups/:sgId/rules/:ruleId | Update / remove a rule |
| GET | POST | DELETE /api/compute/vms/:id/security-groups/:sgId | List / attach / detach groups on a VM |

## Snapshots & Backups

| Endpoint | Description |
| GET | POST /api/compute/vms/:id/snapshots | List / create snapshots — body `{ name }` |
| POST /api/compute/vms/:id/snapshots/:snapshotId/restore | Restore a snapshot |
| DELETE /api/compute/vms/:id/snapshots/:snapshotId | Delete a snapshot |
| GET | POST /api/compute/vms/:id/backups | List / create full backups |
| POST /api/compute/vms/:id/backups/:backupId/restore | Restore a backup |
| DELETE /api/compute/vms/:id/backups/:backupId | Delete a backup |
| GET | POST | DELETE /api/compute/vms/:id/backup-schedule | Get / set / clear the schedule — `{ frequency, time, retention }` |

## IPs & Private Networks

| Endpoint | Description |
| GET | POST /api/compute/vms/:id/ips | List / add extra public IPs |
| DELETE /api/compute/vms/:id/ips/:ipId | Remove an extra IP |
| GET | POST /api/compute/networks | List / create private networks — body `{ name, region }` |
| DELETE /api/compute/networks/:id | Delete a private network |
| GET | POST /api/compute/vms/:id/networks | List / attach networks — body `{ networkId }` |
| DELETE /api/compute/vms/:id/networks/:networkId | Detach a network |

## Startup Scripts

| Endpoint | Description |
| GET /api/compute/scripts | Edge library scripts plus your custom scripts |
| GET /api/compute/scripts/library | Edge library scripts only |
| GET /api/compute/scripts/:id | Get one script with its content and parameters |
| POST /api/compute/scripts | Create a custom script — `{ name, scriptContent, description?, category?, parameters? }` |
| PUT | DELETE /api/compute/scripts/:id | Update / delete a custom script (library scripts are read-only) |
| GET /api/compute/vms/:id/scripts | Script execution history for a VM |

To run a script at VM creation, substitute its parameters into the content and pass the result
as `setupScript`. The
[CLI](https://edge.network/docs/cli/compute) and
[Agent API](https://edge.network/docs/agent/deploy-app) do this for you.

## Discovery & Account

| Endpoint | Description |
| GET /api/compute/regions | Available deployment regions |
| GET /api/compute/os-templates | Available operating systems |
| GET /api/compute/pricing | Pay-as-you-go rates and prepaid balance |
| GET /api/compute/usage | Current resource usage against account limits |
| GET /api/compute/events | Recent compute events across the account |

[Back to Docs](https://edge.network/docs) [Need help?](https://edge.network/support)