REST API Reference

The Cockpit API allows other software applications and custom scripts to control virtual machines, query performance logs, and manage servers automatically.

---

1. What is an API & JWT Token? 🔌

💡 Analogy: The Bank Drive-Through Window

• The REST API: Imagine a bank's drive-through window. Instead of walking inside the lobby (using the web dashboard), you drive up, pass a specific slip through the slot (HTTP request), and the teller passes back your money or receipt (JSON response).
• The JWT (Security Badge): When you first drive up and prove who you are (login), the teller hands you a digital security badge (a JWT token). This badge has a timer on it (expiration). Every time you request a transfer or update, you must show this badge (Authorization: Bearer <JWT_TOKEN>) so the teller knows you are authorized.

---

2. Authentication

All API requests must include your security badge in the request headers:

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

Log In to Get a Security Badge (Token)

• Request: Send your admin credentials.

POST /api/v1/auth/login

• Payload (JSON data you send):

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

• Response (JSON data you receive):

  {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", // <-- This is your security badge
    "refresh_token": "a1b2c3d4-...",
    "expires_in": 3600 // Expired in seconds (1 hour)
  }

Refresh an Expired Security Badge

• Request: If your token expires, trade in your refresh token for a fresh security badge.

POST /api/v1/auth/refresh

• Payload:

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

---

3. Managing Physical Servers

List All Connected Servers

• Request: Query the list of physical servers.

GET /api/v1/hosts

• Response:

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

---

4. Managing Virtual Machines

List All Virtual Machines in the Cluster

• Request:

GET /api/v1/vms

Power Operations on a VM

• Request: Start, stop, or restart a specific VM by its ID.

POST /api/v1/vms/:id/action

• Payload:
  • To start a VM: {"action": "start"}
  • To force stop a VM (unplug power): {"action": "stop", "force": true}

Move a VM to another Server (Live Migration)

• Request: Move a running VM to another physical server.

POST /api/v1/vms/:id/migrate

• Payload:

  {
    "destination_host_id": "019e0014-ffff-7057-b326-000000000002", // Target physical server ID
    "live": true,          // Perform live migration without shutting down
    "persistent": true,    // Save VM configurations permanently on the target
    "undefine_source": true, // Clean up the VM configuration from the old server
    "copy_storage": "none" // Set to "none" if both servers share network storage
  }

• Response:

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