---
title: "Compute API"
description: "Create and manage VMs, SSH keys, security groups, snapshots, backups, private networks and startup scripts over the Edge REST API."
url: "https://edge.network/docs/api/compute"
section: "REST 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](/docs/api/authentication).

## Create a VM

```bash
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](/docs/compute/scripts) for the library. |

Returns `201`:

```json
{
  "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 and 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 and 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. Body: `{ 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 and 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. Body: `{ frequency, time, retention }` |

## IPs and 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. Body: `{ 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](/docs/cli/compute) and [Agent API](/docs/agent/deploy-app) do this for you.

## Discovery and 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 |