VPS API

Create, manage, and scale virtual private servers. Full lifecycle control with start/stop, resize, snapshots, console access, real-time events, and metrics.

← All APIs · Launchpad Co-Stream · Auth Pay Media Vault

Base URL

https://api.railscloud.co/v1

Authentication

Include your API key or JWT token in the Authorization header. All VPS endpoints require authentication and appropriate project membership.

# API key (programmatic access)
Authorization: Bearer dk_live_your_api_key

# JWT token (dashboard sessions)
Authorization: Bearer <jwt_token>

How It Works

VPS instances run on KubeVirt inside our K3s clusters. You create a server, choose a size and OS image, and we provision a fully isolated virtual machine with its own IP, storage, and network.

1 Create a project to group your servers (or use an existing one)
2 Call POST /projects/{slug}/vps with a name, size, and OS image
3 The VPS provisions in seconds — monitor via GET /vps/{id}/events/stream (SSE)
4 SSH in or use the web console — full root access to your server

Quick Start

# Create a VPS
curl -X POST https://api.railscloud.co/v1/projects/my-project/vps \
  -H "Authorization: Bearer dk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "web-01",
    "size": "sm",
    "image": "ubuntu-24.04"
  }'

# Response
# {"data": {"id": "...", "name": "web-01", "status": "provisioning", "ip": "10.0.2.50", ...}}

# Check status
curl https://api.railscloud.co/v1/vps/VPS_ID \
  -H "Authorization: Bearer dk_live_your_key"

Endpoints

Lifecycle

POST /projects/{slug}/vps Create a new VPS
GET /projects/{slug}/vps List all VPS in a project
GET /vps/{id} Get VPS details
DELETE /vps/{id} Permanently delete a VPS

Power Actions

POST /vps/{id}/start Start a stopped VPS
POST /vps/{id}/stop Stop a running VPS
POST /vps/{id}/restart Reboot a running VPS
POST /vps/{id}/resize Change CPU/RAM (VPS must be stopped)

Console & Events

GET /vps/{id}/console Get web console session (VPS must be running)
GET /vps/{id}/events List all events for a VPS
GET /vps/{id}/events/stream Real-time event stream (SSE)

Metrics

GET /vps/{id}/metrics CPU, memory, disk, and network metrics

Snapshots

POST /vps/{id}/snapshots Create a snapshot
GET /vps/{id}/snapshots List all snapshots
POST /vps/{id}/snapshots/{snapshot_id}/restore Restore from snapshot (VPS must be stopped)
DELETE /vps/{id}/snapshots/{snapshot_id} Delete a snapshot

Example: Resize a VPS

# Step 1: Stop the VPS
curl -X POST https://api.railscloud.co/v1/vps/VPS_ID/stop \
  -H "Authorization: Bearer dk_live_your_key"

# Step 2: Resize to a larger plan
curl -X POST https://api.railscloud.co/v1/vps/VPS_ID/resize \
  -H "Authorization: Bearer dk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"size": "md"}'

# Step 3: Start the VPS
curl -X POST https://api.railscloud.co/v1/vps/VPS_ID/start \
  -H "Authorization: Bearer dk_live_your_key"

Example: Snapshot & Restore

# Create a snapshot before deploying
curl -X POST https://api.railscloud.co/v1/vps/VPS_ID/snapshots \
  -H "Authorization: Bearer dk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "pre-deploy-backup"}'

# Response: {"data": {"id": "snap_abc123", "name": "pre-deploy-backup", "status": "creating"}}

# If something goes wrong, restore from snapshot
curl -X POST https://api.railscloud.co/v1/vps/VPS_ID/snapshots/snap_abc123/restore \
  -H "Authorization: Bearer dk_live_your_key"

The VPS must be stopped before restoring from a snapshot. All current data will be replaced with the snapshot contents.

Available Sizes

xs 1 vCPU, 1 GB RAM, 25 GB disk
$6.99/mo
sm 1 vCPU, 2 GB RAM, 50 GB disk
$13.99/mo
md 2 vCPU, 4 GB RAM, 80 GB disk
$27.99/mo
lg 4 vCPU, 8 GB RAM, 160 GB disk
$55.99/mo
xl 8 vCPU, 16 GB RAM, 320 GB disk
$111.99/mo

Rate Limits

Create requests 10 per minute
Power actions (start/stop/restart) 30 per minute
Read operations 120 per minute
Snapshot operations 5 per hour

Error Responses

All errors follow a standard format.

{
  "error": "insufficient_balance",
  "message": "Account balance too low to provision this VPS size"
}
400 Invalid request body or parameters
401 Invalid or missing authentication
403 Insufficient permissions for this project
404 VPS or project not found
409 VPS is in an incompatible state (e.g., resize while running)
422 Validation error (invalid size, duplicate name)
429 Rate limit exceeded
Launch Your First VPS