KVM / VPS Servers

The /api/v1/kvm-servers endpoints let you provision and manage virtual private servers (KVM). Everything here requires an API key with the kvm scope (see Authentication).

Unlike game servers, KVM servers are identified by a numeric id (not a UUID).

For the complete list of endpoints with request/response schemas, use the interactive API Reference.

Discover Plans and Templates

Before ordering, list the available plans (CPU/RAM/disk tiers) and OS templates:

curl -X GET "https://respawnhost.com/api/v1/kvm-servers/plans" \
  -H "X-Api-Key: rsp_YOUR_API_KEY"

curl -X GET "https://respawnhost.com/api/v1/kvm-servers/templates" \
  -H "X-Api-Key: rsp_YOUR_API_KEY"

Order a Server

Provision a new server from a plan and template. Provisioning runs asynchronously — poll GET /{id} and watch the status / provisioningStep fields until it is ready.

curl -X POST "https://respawnhost.com/api/v1/kvm-servers/order" \
  -H "X-Api-Key: rsp_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "planId": 3,
    "templateId": 12,
    "name": "web-01",
    "region": "eu-central",
    "sshKeyIds": [1],
    "password": "optional-root-password"
  }'

Provide either sshKeyIds (see SSH Keys) / sshKeys (raw public keys) or a password for initial access.

List and Inspect Servers

# List your servers (supports ?page, ?limit, ?status, ?search)
curl -X GET "https://respawnhost.com/api/v1/kvm-servers?page=1&limit=10" \
  -H "X-Api-Key: rsp_YOUR_API_KEY"

# Get one server
curl -X GET "https://respawnhost.com/api/v1/kvm-servers/42" \
  -H "X-Api-Key: rsp_YOUR_API_KEY"

Power Control

curl -X POST "https://respawnhost.com/api/v1/kvm-servers/42/power" \
  -H "X-Api-Key: rsp_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "reboot"}'

Valid actions: start, stop, shutdown, reboot. (stop is a hard power-off; shutdown is a graceful ACPI shutdown.)

Live Resource Usage & Metrics

# Current CPU / memory / disk / network snapshot
curl -X GET "https://respawnhost.com/api/v1/kvm-servers/42/resources" \
  -H "X-Api-Key: rsp_YOUR_API_KEY"

# Historical metrics
curl -X GET "https://respawnhost.com/api/v1/kvm-servers/42/metrics" \
  -H "X-Api-Key: rsp_YOUR_API_KEY"

Rescale (Change Plan)

Move a server to a different plan. Set resizeDisk to also grow the disk (disk growth is irreversible).

curl -X POST "https://respawnhost.com/api/v1/kvm-servers/42/rescale" \
  -H "X-Api-Key: rsp_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"planId": 5, "resizeDisk": true}'

OS Operations

# Reinstall from a template (wipes the server)
curl -X POST "https://respawnhost.com/api/v1/kvm-servers/42/reinstall" \
  -H "X-Api-Key: rsp_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"templateId": 12}'

# Reset the root password (omit "password" to auto-generate one)
curl -X POST "https://respawnhost.com/api/v1/kvm-servers/42/reset-password" \
  -H "X-Api-Key: rsp_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"password": "new-strong-password"}'

# Boot into a rescue system (returns temporary credentials)
curl -X POST "https://respawnhost.com/api/v1/kvm-servers/42/rescue-and-reboot" \
  -H "X-Api-Key: rsp_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"os": "linux"}'

Snapshots

# List snapshots
curl -X GET "https://respawnhost.com/api/v1/kvm-servers/42/snapshots" \
  -H "X-Api-Key: rsp_YOUR_API_KEY"

# Create a snapshot
curl -X POST "https://respawnhost.com/api/v1/kvm-servers/42/snapshots" \
  -H "X-Api-Key: rsp_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "pre-upgrade"}'

# Restore a snapshot
curl -X POST "https://respawnhost.com/api/v1/kvm-servers/42/snapshots/{snapshotId}/restore" \
  -H "X-Api-Key: rsp_YOUR_API_KEY"

Backups work the same way under /{id}/backups (with settings at /{id}/backups/settings).

Firewall

Manage per-server firewall rules and the default policy.

# List rules
curl -X GET "https://respawnhost.com/api/v1/kvm-servers/42/firewall" \
  -H "X-Api-Key: rsp_YOUR_API_KEY"

# Allow inbound SSH from a single source
curl -X POST "https://respawnhost.com/api/v1/kvm-servers/42/firewall" \
  -H "X-Api-Key: rsp_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "direction": "in",
    "action": "accept",
    "protocol": "tcp",
    "port": "22",
    "source": "203.0.113.4",
    "comment": "office SSH"
  }'

# Set the default policy
curl -X PUT "https://respawnhost.com/api/v1/kvm-servers/42/firewall/policy" \
  -H "X-Api-Key: rsp_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"policyIn": "DROP", "policyOut": "ACCEPT"}'

Networking (IPs & Reverse DNS)

# List assigned IP addresses
curl -X GET "https://respawnhost.com/api/v1/kvm-servers/42/ips" \
  -H "X-Api-Key: rsp_YOUR_API_KEY"

# Set reverse DNS (PTR) for an IP
curl -X PUT "https://respawnhost.com/api/v1/kvm-servers/42/ips/203.0.113.10/rdns" \
  -H "X-Api-Key: rsp_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reverseDns": "vps.example.com"}'

VNC Console

Open a short-lived VNC session. POST /{id}/console returns a ticket (valid ~30 s) and a websocketUrl; connect your VNC-over-WebSocket client to the proxy at /api/v1/kvm-servers/{id}/console/ws.

curl -X POST "https://respawnhost.com/api/v1/kvm-servers/42/console" \
  -H "X-Api-Key: rsp_YOUR_API_KEY"

ISO Images

Upload, mount, and unmount custom ISO images:

# List ISOs
curl -X GET "https://respawnhost.com/api/v1/kvm-servers/iso" \
  -H "X-Api-Key: rsp_YOUR_API_KEY"

# Mount an ISO
curl -X POST "https://respawnhost.com/api/v1/kvm-servers/42/iso/mount" \
  -H "X-Api-Key: rsp_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"isoVolume": "local:iso/debian-12.iso"}'

ISO uploads use multipart/form-data (POST /iso/upload, max 10 GB).

Cancellation & Lifecycle

# Schedule cancellation at the end of the billing period
curl -X POST "https://respawnhost.com/api/v1/kvm-servers/42/cancel" \
  -H "X-Api-Key: rsp_YOUR_API_KEY"

# Revoke a pending cancellation
curl -X DELETE "https://respawnhost.com/api/v1/kvm-servers/42/cancel" \
  -H "X-Api-Key: rsp_YOUR_API_KEY"

# Delete immediately
curl -X DELETE "https://respawnhost.com/api/v1/kvm-servers/42" \
  -H "X-Api-Key: rsp_YOUR_API_KEY"

SSH Keys

Manage the SSH keys you can attach when ordering or reinstalling a server. These live under /api/v1/ssh-keys and also require the kvm scope.

# List keys
curl -X GET "https://respawnhost.com/api/v1/ssh-keys" \
  -H "X-Api-Key: rsp_YOUR_API_KEY"

# Add a key
curl -X POST "https://respawnhost.com/api/v1/ssh-keys" \
  -H "X-Api-Key: rsp_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "laptop", "publicKey": "ssh-ed25519 AAAA... user@host"}'

# Delete a key
curl -X DELETE "https://respawnhost.com/api/v1/ssh-keys/1" \
  -H "X-Api-Key: rsp_YOUR_API_KEY"