REST API Reference

The Cockpit REST API allows administrators and external systems to automate host registration, manage virtual machine lifecycles, and retrieve system telemetry over HTTP.

---

Authentication & Session Management

The REST API implements JSON Web Token (JWT) authentication to validate requests.

All API requests must include the JWT token in the HTTP authorization header:

Authorization: Bearer <YOUR_JWT_TOKEN>
Content-Type: application/json

1. Authenticate (Retrieve Session Token)

• Endpoint: POST /api/v1/auth/login
• Request Payload:

  {
    "username": "admin",
    "password": "yourpassword"
  }

• Response Payload:

  {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "a1b2c3d4-...",
    "expires_in": 3600
  }

2. Refresh Expired Session Token

• Endpoint: POST /api/v1/auth/refresh
• Request Payload:

  {
    "refresh_token": "a1b2c3d4-..."
  }

---

Host Node Administration

List Registered Hosts

• Endpoint: GET /api/v1/hosts
• Response Payload:

  {
    "hosts": [
      {
        "id": "019e0014-abcd-7057-b326-000000000001",
        "hostname": "vapor-node-01.corp.awan.io",
        "status": "connected",
        "sync_cursor": 1716999901
      }
    ]
  }

---

Virtual Machine Operations

List All Virtual Machines

• Endpoint: GET /api/v1/vms

Trigger VM Power Action

• Endpoint: POST /api/v1/vms/:id/action
• Request Payload Examples:
  • Start VM: {"action": "start"}
  • Graceful Shutdown: {"action": "shutdown"}
  • Hard Power Off: {"action": "stop", "force": true}

Execute Virtual Machine Migration

• Endpoint: POST /api/v1/vms/:id/migrate
• Request Payload:

  {
    "destination_host_id": "019e0014-ffff-7057-b326-000000000002",
    "live": true,
    "persistent": true,
    "undefine_source": true,
    "copy_storage": "none"
  }

• Response Payload:

  {
    "migration_id": "abc123def456",
    "status": "initiated"
  }