Skip to main content

​
API Introduction

The Vers API provides programmatic access to VM management functionality. While most users interact with Vers through the CLI, the API enables direct integration into scripts, applications, and custom tooling.

​
Base URL

https://api.vers.sh/api/v1

​
Authentication

All API endpoints require authentication using a Bearer token, except for the health check: 
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://api.vers.sh/api/v1/vms
Obtain your API token from the Vers billing page at vers.sh/billing.

​
Health Check (Public)

The health endpoint is available without authentication at the root path: 
curl https://api.vers.sh/health
Returns connection statistics: 
{
  "ssh": {
    "connections_total": 4,
    "connections_active": 0,
    "errors": { ... }
  },
  "http": {
    "connections_total": 9941,
    "connections_active": 3
  },
  "websocket": {
    "connections_total": 0,
    "connections_active": 0
  }
}

​
Core Concepts

​
VMs

Virtual machines are the primary resource in Vers. Each VM:
  • Has a unique VM ID (UUID format)
  • Has a state: running, paused, or not_started
  • Can be branched, committed, paused, resumed, and deleted
  • Provides SSH access for interactive use

​
Commits

Commits are snapshots of a VM’s complete state (filesystem + memory). You can:
  • Create commits from running VMs
  • Restore VMs from existing commits
  • Branch from commits to create new VMs

​
Rootfs Images

Base filesystem images that define the operating system and initial software.

​
API Endpoints

​
VM Operations

MethodEndpointDescription
GET/vmsList all VMs
POST/vm/new_rootCreate a new root VM
GET/vm/{vm_id}/statusGet VM status and details
DELETE/vm/{vm_id}Delete a VM
PATCH/vm/{vm_id}/stateUpdate VM state (pause/resume)
POST/vm/{vm_id}/branchBranch from a VM
POST/vm/{vm_id}/commitCommit VM state
POST/vm/from_commitCreate VM from a commit
GET/vm/{vm_id}/ssh_keyGet SSH credentials

​
Branch Operations

The branch endpoint auto-detects whether you’re branching from a VM or commit: 
# Branch from a running VM
POST /api/v1/vm/{vm_id}/branch

# Branch directly from a commit
POST /api/v1/vm/branch/by_commit/{commit_id}

# Branch from VM with explicit path
POST /api/v1/vm/branch/by_vm/{vm_id}
When branching from a running VM, the API automatically:
  1. Briefly pauses the parent VM for a consistent snapshot
  2. Creates a commit of the VM’s current state
  3. Spawns a new VM from that commit
  4. Resumes the parent VM
  5. Both VMs end up running simultaneously

​
Rootfs Management

MethodEndpointDescription
GET/api/rootfsList available rootfs images
PUT/api/rootfs/{name}Upload a rootfs image
DELETE/api/rootfs/{name}Delete a rootfs image

​
SSH Access

The API provides SSH credentials for connecting to VMs programmatically.

​
Getting SSH Credentials

curl -H "Authorization: Bearer $API_TOKEN" \
  https://api.vers.sh/api/v1/vm/{vm_id}/ssh_key
Response: 
{
  "ssh_private_key": "-----BEGIN OPENSSH PRIVATE KEY-----\n...",
  "ssh_port": 443
}

​
SSH-over-TLS Connection

Vers uses SSH tunneled over TLS on port 443:
  • Host: {vm_id}.vm.vers.sh
  • Port: 443 (TLS)
  • Username: root
  • Auth: Private key from the API
This enables SSH access through firewalls that only allow HTTPS traffic.

​
Programmatic SSH Example

import Vers, { withSSH } from 'vers';

const client = new Vers({ apiKey: 'your-api-key' });
const vm = withSSH(client.vm);

// Execute command
const result = await vm.execute(vmId, 'ls -la');
console.log(result.stdout);

// Upload files
await vm.upload(vmId, './local-file', '/remote/path');
See the VM Access Guide for comprehensive SDK documentation.

​
Response Format

Successful responses return the data directly: 
// GET /api/v1/vms
[
  {
    "vm_id": "658805b3-8a5f-463a-9989-62cf9a9765e6",
    "owner_id": "9370b900-e31a-4f0c-b92d-0829df4c8e15",
    "created_at": "2026-01-07T22:08:58.475021Z",
    "state": "running"
  }
]

// POST /api/v1/vm/{vm_id}/branch
{
  "vm_id": "new-vm-uuid"
}

// POST /api/v1/vm/{vm_id}/commit
{
  "commit_id": "commit-uuid",
  "host_architecture": "x86_64"
}
Error responses: 
{
  "error": "Error description",
  "success": false
}

​
Request Bodies

​
Create Root VM

POST /api/v1/vm/new_root

{
  "vm_config": {
    "mem_size_mib": 512,
    "vcpu_count": 1,
    "fs_size_mib": 512,
    "image_name": "default",
    "kernel_name": "default.bin"
  }
}

​
Update VM State

PATCH /api/v1/vm/{vm_id}/state

{
  "state": "Paused"
}
Valid states: "Paused", "Running"

​
Create from Commit

POST /api/v1/vm/from_commit

{
  "commit_id": "commit-uuid"
}

​
CLI to API Mapping

The Vers CLI uses this API. CLI commands map to API endpoints:
CLI CommandAPI Endpoint
vers runPOST /vm/new_root
vers statusGET /vms
vers branchPOST /vm/{id}/branch
vers commitPOST /vm/{id}/commit
vers run-commitPOST /vm/from_commit
vers delete / vers killDELETE /vm/{id}
vers pausePATCH /vm/{id}/state (state: Paused)
vers resumePATCH /vm/{id}/state (state: Running)

​
Rate Limits

The API enforces rate limits to ensure fair usage. If you exceed limits, you’ll receive a 429 Too Many Requests response.

​
See Also

  • VM Access Guide - SSH connections and SDK usage
  • CLI Reference - Command-line interface documentation
  • API Playground (below) - Interactive endpoint testing