Skip to main content

​
API Introduction

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

​
Base URL

The API base URL depends on your Vers server deployment. All endpoints are prefixed with /api.

​
Authentication

All API endpoints (except /api/health and /api/network) require authentication using a Bearer token in the Authorization header: 
Authorization: Bearer YOUR_API_TOKEN
You can obtain an API token from the Vers dashboard at vers.sh/billing.

​
Core Concepts

​
Clusters

Clusters are isolated environments that contain one or more VMs. Each cluster has:
  • A unique cluster ID
  • Configuration for VM resources (CPU, memory, filesystem size)
  • A root VM that serves as the base for branching

​
VMs

Virtual machines within clusters that can be:
  • Branched - Create new VMs based on the current state
  • Committed - Save the current state as a new snapshot
  • Paused/Resumed - Control VM execution state
  • Connected to - SSH access for interactive use

​
Rootfs Images

Base filesystem images that define the operating system and initial software for VMs. You can:
  • Upload custom rootfs images as tar archives
  • List available images
  • Delete unused images

​
API Categories

​
Cluster Management

  • Create and configure clusters
  • List and inspect cluster details
  • Delete clusters and all associated VMs
  • Retrieve SSH keys for cluster access

​
VM Operations

  • List and inspect individual VMs
  • Branch VMs to create new development paths
  • Commit VM state for persistence
  • Control VM state (pause/resume)
  • Delete VMs with optional recursive deletion of children

​
Rootfs Management

  • Upload custom filesystem images
  • List available rootfs options
  • Delete unused rootfs images

​
System Information

  • Health checks for API availability
  • Network capacity and usage information

​
Response Format

All API responses follow a consistent format with operation metadata: 
{
  "operation_id": "unique-operation-identifier",
  "time_start": 1640995200,
  "duration_ns": 1500000,
  "data": {
    // Response payload
  }
}
Error responses include an error field instead of data: 
{
  "operation_id": "unique-operation-identifier", 
  "time_start": 1640995200,
  "duration_ns": 1500000,
  "error": "Error description"
}

​
Getting Started

  1. Health Check: Verify API availability with GET /api/health
  2. Authentication: Ensure you have a valid Bearer token
  3. Create Cluster: Use POST /api/cluster to create your first cluster
  4. Manage VMs: Branch, commit, and control VMs within your cluster

​
CLI Integration

The Vers CLI uses this same API under the hood. CLI commands like vers up, vers branch, and vers commit correspond directly to API endpoints, making it easy to transition between CLI and API usage as needed. For interactive exploration, use the API playground in the next section to test endpoints and see live examples.