Skip to main content
Base URL: https://api.lyceum.technologyAll endpoints require authentication via Bearer token in the header:
Authorization: Bearer <token>

​
Endpoints Overview

MethodEndpointDescription
POST/api/v2/external/vms/createCreate a new VM instance
GET/api/v2/external/vms/listList all VM instances
GET/api/v2/external/vms/availabilityCheck hardware availability
GET/api/v2/external/vms/{vm_id}/statusGet VM status
DELETE/api/v2/external/vms/{vm_id}Terminate a VM

​
Create VM

Create and start a new VM instance. Endpoint: POST /api/v2/external/vms/create 
curl -X POST https://api.lyceum.technology/api/v2/external/vms/create \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "hardware_profile": "a100",
    "user_public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAB...",
    "name": "my-training-vm",
    "instance_specs": {
      "cpu": 8,
      "memory": 64,
      "disk": 100,
      "gpu_count": 1
    }
  }'

​
Request Body

​
hardware_profile
string
required
Hardware profile: cpu, a100, or h100
​
user_public_key
string
required
SSH public key for authentication
​
name
string
Friendly name for the VM instance
​
instance_specs
object
Custom resource specifications (optional - uses profile defaults if not provided)

​
Response

{
  "vm_id": "vm-abc123def456",
  "status": "pending",
  "name": "my-training-vm",
  "created_at": "2024-01-15T10:30:00Z",
  "ip_address": null
}
The ip_address will be null while the VM is provisioning. Poll the status endpoint to get the IP once the VM is ready.

​
List VMs

List all VM instances for the authenticated user. Endpoint: GET /api/v2/external/vms/list 
curl -X GET https://api.lyceum.technology/api/v2/external/vms/list \
  -H "Authorization: Bearer <TOKEN>"

​
Response

{
  "vms": [
    {
      "vm_id": "vm-abc123def456",
      "name": "training-vm",
      "status": "running",
      "ip_address": "10.0.1.5:22",
      "hardware_profile": "a100",
      "billed": 2.45,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 1
}

​
Check Availability

Check available hardware profiles and capacity. Endpoint: GET /api/v2/external/vms/availability 
curl -X GET https://api.lyceum.technology/api/v2/external/vms/availability \
  -H "Authorization: Bearer <TOKEN>"

​
Response

{
  "pool_name": "default",
  "available_hardware_profiles": [
    {
      "profile": "cpu",
      "gpu_type": null,
      "vcpu": 4,
      "memory_gb": 16,
      "available": 12
    },
    {
      "profile": "a100",
      "gpu_type": "NVIDIA A100",
      "vcpu": 8,
      "memory_gb": 64,
      "available": 3
    },
    {
      "profile": "h100",
      "gpu_type": "NVIDIA H100",
      "vcpu": 8,
      "memory_gb": 80,
      "available": 1
    }
  ]
}

​
Get VM Status

Get detailed status of a specific VM. Endpoint: GET /api/v2/external/vms/{vm_id}/status 
curl -X GET https://api.lyceum.technology/api/v2/external/vms/vm-abc123def456/status \
  -H "Authorization: Bearer <TOKEN>"

​
Response

{
  "vm_id": "vm-abc123def456",
  "status": "running",
  "name": "training-vm",
  "ip_address": "10.0.1.5:22",
  "hardware_profile": "a100",
  "billed": 2.45,
  "uptime_seconds": 8130,
  "instance_specs": {
    "cpu": 8,
    "memory": 64,
    "disk": 100,
    "gpu_count": 1
  },
  "created_at": "2024-01-15T10:30:00Z"
}

​
Terminate VM

Terminate and delete a VM instance. Endpoint: DELETE /api/v2/external/vms/{vm_id} 
curl -X DELETE https://api.lyceum.technology/api/v2/external/vms/vm-abc123def456 \
  -H "Authorization: Bearer <TOKEN>"

​
Response

{
  "message": "VM instance terminated successfully"
}

​
Error Responses

All endpoints return standard error responses:
Status CodeDescription
400Bad request - invalid parameters
401Unauthorized - invalid or missing token
402Payment required - insufficient credits
404Not found - VM does not exist
422Validation error - invalid request body
500Server error

​
Error Response Format

{
  "detail": "Insufficient credits to start VM instance"
}

​
Polling for VM Readiness

VMs take time to provision. Here’s how to poll for readiness: 
import time

def wait_for_vm(vm_id, token, timeout=600, interval=30):
    """Poll until VM is ready or timeout."""
    start = time.time()

    while time.time() - start < timeout:
        response = requests.get(
            f"https://api.lyceum.technology/api/v2/external/vms/{vm_id}/status",
            headers={"Authorization": f"Bearer {token}"}
        )
        status = response.json()

        if status["status"] in ["ready", "running"]:
            return status
        elif status["status"] in ["failed", "error"]:
            raise Exception(f"VM failed: {status}")

        print(f"Status: {status['status']} - waiting...")
        time.sleep(interval)

    raise TimeoutError("VM did not become ready in time")

# Usage
vm = create_vm(...)
ready_vm = wait_for_vm(vm["vm_id"], token)
print(f"SSH: ssh -i ~/.ssh/id_rsa ubuntu@{ready_vm['ip_address']}")

​
Rate Limits

EndpointRate Limit
Create VM10 requests/minute
List/Status60 requests/minute
Terminate30 requests/minute
Need help? Contact [email protected] or check our API Introduction for authentication details.