REST API & CLI Tools

Every operation you perform in the VergeOS UI maps directly to a REST API call. This API-first design means anything you can click in the dashboard — creating VMs, configuring networks, managing tenants — can be automated through HTTP endpoints. This section covers the three primary interfaces for programmatic access: the REST API itself, the yb-api helper script for on-box automation, and the vrg CLI for remote management.

REST API Overview

The VergeOS API follows standard REST conventions with JSON payloads, supporting the full lifecycle of every resource in the platform.

HTTP Methods

Method	Purpose	Example
GET	Retrieve resources	GET /api/v4/vms?fields=most
POST	Create resources or trigger actions	POST /api/v4/vms
PUT	Update existing resources	PUT /api/v4/vms/36
DELETE	Remove resources	DELETE /api/v4/vms/36

Query Parameters

Every GET request supports powerful filtering and field selection:

• fields — Specify which fields to return (e.g., fields=name,$key,ram or fields=most for all common fields)
• filter — OData-style filter expressions (e.g., filter=is_snapshot eq false)
• sort — Sort results by field (e.g., sort=name)
• limit / offset — Pagination controls for large result sets

Data Formats

All API responses are returned in JSON format. Request bodies for POST and PUT operations must also be JSON with the Content-Type: application/json header.

Rate Limits

The API supports a maximum of 1,000 requests per hour per API key. For high-volume automation, batch operations where possible and implement retry logic with exponential backoff.

Authentication

VergeOS supports three authentication methods, each suited to different use cases:

1. Basic HTTP Authentication

The simplest method — pass credentials directly with each request. All API traffic requires HTTPS.

curl -X GET "https://vergeos.example.com/api/v4/vms?fields=most" \
  --basic --user "admin:password" \
  -H "Accept: application/json"

2. Token-Based Authentication (Session Tokens)

Request a session token by POSTing credentials to /sys/tokens. Use the returned token in subsequent requests via the x-yottabyte-token header:

# Step 1: Obtain a token
curl --basic \
  --data-ascii '{"login": "admin", "password": "secret"}' \
  --request "POST" \
  --header "Content-Type: application/json" \
  "https://vergeos.example.com/api/sys/tokens"

# Response includes the token key:
# {"location":"/sys/tokens/3a334...","$key":"3a334..."}

# Step 2: Use the token in subsequent requests
curl -X GET "https://vergeos.example.com/api/v4/vms?fields=most" \
  -H "x-yottabyte-token: 3a334..." \
  -H "Accept: application/json"

# Step 3: Logout when done
curl -X DELETE "https://vergeos.example.com/api/sys/tokens/3a334..."

3. API Keys (Long-Lived Bearer Tokens)

For production automation, create persistent API keys through System → Users → [User] → API Keys. These keys function as Bearer tokens and remain valid until expiration or deletion:

curl -X GET "https://vergeos.example.com/api/v4/vms?fields=most" \
  -H "Authorization: Bearer your-api-key-string" \
  -H "Content-Type: application/json"

API keys support IP allow/deny lists for security and configurable expiration dates. Store them in environment variables rather than hardcoding:

export VERGEOS_API_KEY="your-api-key-string"
curl -X GET "https://vergeos.example.com/api/v4/system" \
  -H "Authorization: Bearer ${VERGEOS_API_KEY}"

Caution

API keys are shown only once at creation time. If lost, you must delete the key and create a new one.

API Explorer (Swagger)

VergeOS includes a built-in Swagger documentation page that is dynamically generated from the running system, showing every available table and operation.

To access it:

1. Log in to the VergeOS UI
2. Navigate to System → API Documentation
3. Browse available endpoints, view schemas, and test API calls directly

The Swagger interface lets you execute API calls in-browser and see the resulting curl command, response body, and headers — making it an excellent tool for prototyping automation scripts.

Key API Endpoints

The API organizes resources into tables. Here are the most commonly used endpoints:

Endpoint	Purpose
/api/v4/vms	Virtual machine CRUD operations
/api/v4/vm_actions	VM power operations, clone, snapshot
/api/v4/machine_drives	Attach/manage VM storage drives
/api/v4/machine_nics	Configure VM network interfaces
/api/v4/machine_devices	GPU/PCI device passthrough
/api/v4/machine_status/{id}	Runtime power state and status
/api/v4/vnets	Virtual network management
/api/v4/vnet_rules	Firewall and NAT rules
/api/v4/tenants	Tenant (VDC) management
/api/v4/nodes	Physical node information
/api/v4/clusters	Cluster configuration
/api/sys/tokens	Session token management

Schema Introspection

Append /$table to any endpoint to retrieve its full database schema, including all available fields and types:

# Get the VM table schema
curl -X GET "https://vergeos.example.com/api/v4/vms/\$table" \
  -H "Authorization: Bearer ${VERGEOS_API_KEY}"

VM Lifecycle API Walkthrough

The most common automation workflow is provisioning a complete VM through the API. This four-step process mirrors what the UI does behind the scenes:

Step 1: Create the VM

curl -X POST "https://vergeos.example.com/api/v4/vms" \
  -H "Authorization: Bearer ${VERGEOS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "web-server-01",
    "description": "Production web server",
    "machine_type": "pc-q35-9.0",
    "cpu_cores": 4,
    "cpu_type": "Cascadelake-Server",
    "ram": 8192,
    "os_family": "linux",
    "boot_order": "cd",
    "uefi": true,
    "allow_hotplug": true
  }'

# Response: {"location":"/v4/vms/42","$key":"42"}

Step 2: Add a Storage Drive

curl -X POST "https://vergeos.example.com/api/v4/machine_drives" \
  -H "Authorization: Bearer ${VERGEOS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "machine": 42,
    "name": "boot-disk",
    "size": 107374182400,
    "interface": "virtio",
    "media": "disk",
    "tier": 1
  }'

Step 3: Add a Network Interface

curl -X POST "https://vergeos.example.com/api/v4/machine_nics" \
  -H "Authorization: Bearer ${VERGEOS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "machine": 42,
    "network": 6,
    "model": "virtio"
  }'

Step 4: Power On

curl -X POST "https://vergeos.example.com/api/v4/vm_actions" \
  -H "Authorization: Bearer ${VERGEOS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "vm": 42,
    "action": "poweron"
  }'

Additional Actions

Once the VM exists, you can trigger advanced operations through the same vm_actions endpoint:

# Clone a VM
curl -X POST ".../api/v4/vm_actions" \
  -d '{"vm": 42, "action": "clone", "params": {"name": "web-server-clone", "quiesce": "true"}}'

# Take a snapshot
curl -X POST ".../api/v4/vm_actions" \
  -d '{"vm": 42, "action": "snapshot", "params": {"name": "pre-upgrade"}}'

# Power off gracefully
curl -X POST ".../api/v4/vm_actions" \
  -d '{"vm": 42, "action": "poweroff"}'

yb-api Helper Script

The yb-api script is a built-in command-line wrapper available on every VergeOS node via SSH. It simplifies making API calls without having to construct full curl commands.

Basic Syntax

yb-api --get|--post|--put|--delete [options] /v4/<endpoint>

Common Options

Flag	Purpose
--get	Retrieve resources
--post='JSON'	Create a resource with JSON payload
--put='JSON'	Update a resource with JSON payload
--delete	Delete a resource
--server=IP	Target a specific VergeOS system
--user=NAME	Authenticate as a specific user
--fields='...'	Select fields to return
--filter='...'	OData filter expression

Usage Examples

# List all VMs (excluding snapshots) with status
yb-api --get --user=admin --server=10.0.0.100 \
  --fields='name,$key,ram,machine#status#status as machine_status' \
  --filter='is_snapshot eq false' /v4/vms

# Get detailed VM info including drives and NICs
yb-api --get --fields='most,machine[most,drives[most],nics[most]]' /v4/vms/1

# Create a new VM
yb-api --post='{"name":"api-vm","enabled":true,"os_family":"linux",
  "cpu_cores":4,"ram":"8192"}' --user=admin --server=10.0.0.100 /v4/vms

# Rename a VM
yb-api --put='{"name":"new-name"}' --user=admin --server=10.0.0.100 /v4/vms/1

# Power on a VM
yb-api --post='{"vm":1, "action": "poweron"}' /v4/vm_actions

# Get table schema for VMs
yb-api --get '/v4/vms/$table'

Tip

The yb-api script is ideal for quick ad-hoc queries and scripting directly on VergeOS nodes. For remote automation from workstations, use the vrg CLI or the Python/PowerShell SDKs.

vrg CLI

The vrg command-line tool provides a full-featured remote management interface for VergeOS, built in Python with over 200 commands covering VMs, networks, storage, tenants, and system administration.

Installation

# macOS (Homebrew)
brew install verge-io/tap/vrg

# Linux / Windows (pip or pipx)
pip install vrg

Key Capabilities

VM Management

Create, list, start, stop, snapshot, clone, and delete virtual machines with simple commands.

Network Operations

Manage virtual networks, firewall rules, DHCP settings, and VPN configurations.

Storage Control

Administer NAS volumes, CIFS/NFS shares, and monitor vSAN tiers.

Tenant Management

Provision tenants, allocate resources, and manage multi-tenant environments.

The vrg CLI wraps the same REST API documented above, providing tab completion, formatted output, and a more ergonomic interface for day-to-day operations from your workstation.

API Error Handling

When API calls fail, VergeOS returns standard HTTP status codes with descriptive JSON error bodies:

Status Code	Meaning	Common Cause
401	Unauthorized	Invalid credentials or expired token
403	Forbidden	Insufficient permissions for the operation
404	Not Found	Resource does not exist or invalid endpoint
409	Conflict	Resource state conflict (e.g., VM already running)
422	Validation Error	Invalid parameters or missing required fields
429	Rate Limited	Exceeded 1,000 requests/hour limit
500	Server Error	Internal error — check system logs

VMware Bridge

VMware’s vSphere REST API (introduced in 6.5) operates alongside the older SOAP-based SDK, creating two parallel API surfaces. The VergeOS API is the only management interface — the UI itself is an API client. This means every UI feature is available via API on day one, with no separate SDK or SOAP layer to manage. The yb-api helper is conceptually similar to VMware’s govc CLI, while the vrg CLI is analogous to PowerCLI but REST-native.

Nutanix Bridge

Nutanix provides Prism Central v4 APIs alongside legacy v2/v3 endpoints, with different API versions for different feature sets. VergeOS maintains a single versioned API (/api/v4/) for all operations. The built-in Swagger explorer is similar to Nutanix’s API Explorer in Prism, but VergeOS’s yb-api helper script provides on-box convenience that Nutanix doesn’t offer natively. The vrg CLI serves a similar role to Nutanix’s nuclei CLI tool.

Best Practices for API Automation

1. Use API keys for production automation instead of session tokens — they don’t expire on inactivity
2. Apply IP restrictions on API keys to limit where they can be used
3. Select specific fields (fields=name,$key,ram) instead of fields=most to reduce payload size
4. Implement pagination with limit and offset for large result sets
5. Handle async operations — actions like clone and snapshot return immediately; poll machine_status for completion
6. Store credentials in environment variables — never hardcode tokens in scripts
7. Use schema introspection (/$table) to discover available fields before writing automation

What’s Next

Now that you understand the raw API, the following pages cover higher-level tools that wrap this API into language-native interfaces:

• Python SDK (pyvergeos) — Pythonic, type-annotated wrapper with resource managers and OData filter builder
• PowerShell Module (PSVergeOS) — 200+ cmdlets with pipeline support for Windows-native automation