API Reference

The ZoneweaverAPI provides comprehensive RESTful endpoints for managing Bhyve virtual machines, networking, storage, and system monitoring on OmniOS/illumos systems.

Table of contents

  1. Authentication
  2. Base URL
  3. OpenAPI Specification
    1. Interactive Documentation
    2. API Categories
      1. Zone Management
      2. Network Management
      3. Storage Management
      4. Console Access
      5. System Monitoring
      6. Package Management
      7. API Management
  4. Rate Limiting
  5. Error Handling
  6. Pagination
  7. WebSocket Endpoints

Authentication

All API endpoints require authentication using API keys in the Bearer token format:

Authorization: Bearer wh_your_api_key_here

See the Authentication Guide for detailed setup instructions.

Base URL

The API is served from your ZoneweaverAPI server:

  • HTTPS (Recommended): https://your-server:5001
  • HTTP: http://your-server:5000

OpenAPI Specification

The ZoneweaverAPI is fully documented using OpenAPI 3.0 specification.

Interactive Documentation

  • Live API Reference - Complete interactive API documentation with examples and testing capabilities
  • OpenAPI JSON - Raw OpenAPI specification for tools and integrations

API Categories

The ZoneweaverAPI is organized into the following categories:

Zone Management

  • Zone lifecycle management (create, start, stop, delete)
  • Zone configuration and properties
  • Boot environment management

Network Management

  • VLAN configuration and management
  • VNIC (Virtual Network Interface) management
  • Etherstub management
  • Network bridge configuration

Storage Management

  • ZFS dataset management
  • ZFS pool management and monitoring
  • Swap area management

Console Access

  • VNC console sessions
  • Terminal/SSH sessions (zlogin)
  • WebSocket connections for real-time access

System Monitoring

  • Host system metrics and statistics
  • Network usage and performance monitoring
  • Storage I/O and capacity monitoring
  • CPU and memory statistics

Package Management

  • Zone provisioning and package installation
  • System update management
  • Repository management

API Management

  • API key generation and management
  • Bootstrap configuration
  • Entity management

Rate Limiting

The API currently does not implement rate limiting, but this may be added in future versions for production deployments.

Error Handling

The API uses standard HTTP status codes and returns JSON error responses:

{
  "msg": "Error description"
}

Common status codes:

  • 200 - Success
  • 201 - Created
  • 400 - Bad Request
  • 401 - Unauthorized (Invalid API key)
  • 403 - Forbidden
  • 404 - Not Found
  • 500 - Internal Server Error

Pagination

Paginated endpoints support the following query parameters:

  • limit - Number of items per page (default: 50)
  • offset - Number of items to skip

WebSocket Endpoints

Real-time features use WebSocket connections:

  • /term/{sessionId} - Terminal sessions
  • /zlogin/{sessionId} - Zone login sessions
  • /zones/{zoneName}/vnc/websockify - VNC console access