26 KiB
Executable File
26 KiB
Executable File
Архив исходника docs/reference/lume-0.5.3-api.json
Источник: Virfield, commit a1460d3372bdfbb5cb19d633d41dd5d3fb3164e6. Снимок перед релизной очисткой. Исторические утверждения ниже относятся к моменту исходной записи; актуальное состояние — в personal/projects/virfield.
{
"base_path" : "\/lume",
"description" : "HTTP API for managing macOS and Linux virtual machines",
"endpoints" : [
{
"category" : "VM Management",
"description" : "List all virtual machines",
"method" : "GET",
"path" : "\/lume\/vms",
"path_parameters" : [
],
"query_parameters" : [
{
"description" : "Filter by storage location name",
"name" : "storage",
"required" : false,
"type" : "string"
}
],
"response_body" : {
"content_type" : "application\/json",
"description" : "Array of VM details objects"
},
"status_codes" : [
{
"code" : 200,
"description" : "Success"
},
{
"code" : 400,
"description" : "Bad request"
}
]
},
{
"category" : "VM Management",
"description" : "Get detailed information about a specific virtual machine",
"method" : "GET",
"path" : "\/lume\/vms\/:name",
"path_parameters" : [
{
"description" : "Name of the VM",
"name" : "name",
"required" : true,
"type" : "string"
}
],
"query_parameters" : [
{
"description" : "VM storage location to use",
"name" : "storage",
"required" : false,
"type" : "string"
}
],
"response_body" : {
"content_type" : "application\/json",
"description" : "VM details object with name, os, cpuCount, memorySize, diskSize, display, status, vncUrl, ipAddress, locationName",
"fields" : [
{
"description" : "VM name",
"name" : "name",
"required" : true,
"type" : "string"
},
{
"description" : "Operating system (macOS or linux)",
"name" : "os",
"required" : true,
"type" : "string"
},
{
"description" : "Number of CPU cores",
"name" : "cpuCount",
"required" : true,
"type" : "integer"
},
{
"description" : "Memory size in bytes",
"name" : "memorySize",
"required" : true,
"type" : "integer"
},
{
"description" : "Disk size with allocated and total",
"name" : "diskSize",
"required" : true,
"type" : "object"
},
{
"description" : "Display resolution (WIDTHxHEIGHT)",
"name" : "display",
"required" : true,
"type" : "string"
},
{
"description" : "VM status (running, stopped)",
"name" : "status",
"required" : true,
"type" : "string"
},
{
"description" : "VNC URL if running",
"name" : "vncUrl",
"required" : false,
"type" : "string"
},
{
"description" : "IP address if running",
"name" : "ipAddress",
"required" : false,
"type" : "string"
},
{
"description" : "Storage location name",
"name" : "locationName",
"required" : true,
"type" : "string"
}
]
},
"status_codes" : [
{
"code" : 200,
"description" : "Success"
},
{
"code" : 400,
"description" : "VM not found or invalid request"
}
]
},
{
"category" : "VM Management",
"description" : "Create a new virtual machine",
"method" : "POST",
"path" : "\/lume\/vms",
"path_parameters" : [
],
"query_parameters" : [
],
"request_body" : {
"content_type" : "application\/json",
"description" : "VM creation parameters",
"fields" : [
{
"description" : "Name for the virtual machine",
"name" : "name",
"required" : true,
"type" : "string"
},
{
"description" : "Operating system to install (macOS or linux)",
"name" : "os",
"required" : true,
"type" : "string"
},
{
"description" : "Number of CPU cores",
"name" : "cpu",
"required" : true,
"type" : "integer"
},
{
"description" : "Memory size (e.g., 8GB)",
"name" : "memory",
"required" : true,
"type" : "string"
},
{
"description" : "Disk size (e.g., 50GB)",
"name" : "diskSize",
"required" : true,
"type" : "string"
},
{
"description" : "Display resolution (e.g., 1024x768)",
"name" : "display",
"required" : true,
"type" : "string"
},
{
"description" : "Path to IPSW file or 'latest' for macOS VMs",
"name" : "ipsw",
"required" : false,
"type" : "string"
},
{
"description" : "VM storage location to use",
"name" : "storage",
"required" : false,
"type" : "string"
}
]
},
"response_body" : {
"content_type" : "application\/json",
"description" : "Success message with VM name"
},
"status_codes" : [
{
"code" : 200,
"description" : "VM created successfully"
},
{
"code" : 400,
"description" : "Invalid request body or VM creation failed"
}
]
},
{
"category" : "VM Management",
"description" : "Delete a virtual machine and its associated files",
"method" : "DELETE",
"path" : "\/lume\/vms\/:name",
"path_parameters" : [
{
"description" : "Name of the VM to delete",
"name" : "name",
"required" : true,
"type" : "string"
}
],
"query_parameters" : [
{
"description" : "VM storage location",
"name" : "storage",
"required" : false,
"type" : "string"
}
],
"response_body" : {
"content_type" : "application\/json",
"description" : "Empty response on success"
},
"status_codes" : [
{
"code" : 200,
"description" : "VM deleted successfully"
},
{
"code" : 400,
"description" : "VM not found or deletion failed"
}
]
},
{
"category" : "VM Management",
"description" : "Create a copy of an existing virtual machine",
"method" : "POST",
"path" : "\/lume\/vms\/clone",
"path_parameters" : [
],
"query_parameters" : [
],
"request_body" : {
"content_type" : "application\/json",
"description" : "Clone parameters",
"fields" : [
{
"description" : "Name of the source VM",
"name" : "name",
"required" : true,
"type" : "string"
},
{
"description" : "Name for the cloned VM",
"name" : "newName",
"required" : true,
"type" : "string"
},
{
"description" : "Source VM storage location",
"name" : "sourceLocation",
"required" : false,
"type" : "string"
},
{
"description" : "Destination VM storage location",
"name" : "destLocation",
"required" : false,
"type" : "string"
}
]
},
"response_body" : {
"content_type" : "application\/json",
"description" : "Success message with source and destination names"
},
"status_codes" : [
{
"code" : 200,
"description" : "VM cloned successfully"
},
{
"code" : 400,
"description" : "Clone operation failed"
}
]
},
{
"category" : "VM Management",
"description" : "Update virtual machine configuration settings",
"method" : "PATCH",
"path" : "\/lume\/vms\/:name",
"path_parameters" : [
{
"description" : "Name of the VM to update",
"name" : "name",
"required" : true,
"type" : "string"
}
],
"query_parameters" : [
],
"request_body" : {
"content_type" : "application\/json",
"description" : "Settings to update (all fields optional)",
"fields" : [
{
"description" : "New number of CPU cores",
"name" : "cpu",
"required" : false,
"type" : "integer"
},
{
"description" : "New memory size (e.g., 16GB)",
"name" : "memory",
"required" : false,
"type" : "string"
},
{
"description" : "New total disk size (increase only)",
"name" : "diskSize",
"required" : false,
"type" : "string"
},
{
"description" : "New display resolution",
"name" : "display",
"required" : false,
"type" : "string"
},
{
"description" : "VM storage location",
"name" : "storage",
"required" : false,
"type" : "string"
},
{
"default_value" : "false",
"description" : "Skip the macOS rollback backup",
"name" : "noBackup",
"required" : false,
"type" : "boolean"
},
{
"default_value" : "false",
"description" : "Keep rollback files after success",
"name" : "keepBackup",
"required" : false,
"type" : "boolean"
},
{
"default_value" : "false",
"description" : "Validate the resize plan without modifying the disk",
"name" : "dryRun",
"required" : false,
"type" : "boolean"
}
]
},
"response_body" : {
"content_type" : "application\/json",
"description" : "Success message"
},
"status_codes" : [
{
"code" : 200,
"description" : "Settings updated successfully"
},
{
"code" : 400,
"description" : "Invalid settings or update failed"
}
]
},
{
"category" : "VM Management",
"description" : "Start a virtual machine",
"method" : "POST",
"path" : "\/lume\/vms\/:name\/run",
"path_parameters" : [
{
"description" : "Name of the VM to start",
"name" : "name",
"required" : true,
"type" : "string"
}
],
"query_parameters" : [
],
"request_body" : {
"content_type" : "application\/json",
"description" : "Run options (all fields optional)",
"fields" : [
{
"default_value" : "false",
"description" : "Run without VNC display",
"name" : "noDisplay",
"required" : false,
"type" : "boolean"
},
{
"description" : "Directories to share with the VM",
"name" : "sharedDirectories",
"required" : false,
"type" : "array"
},
{
"default_value" : "false",
"description" : "Boot macOS VM in recovery mode",
"name" : "recoveryMode",
"required" : false,
"type" : "boolean"
},
{
"description" : "VM storage location",
"name" : "storage",
"required" : false,
"type" : "string"
},
{
"default_value" : "false",
"description" : "Enable bidirectional clipboard sync via SSH (experimental)",
"name" : "clipboard",
"required" : false,
"type" : "boolean"
}
]
},
"response_body" : {
"content_type" : "application\/json",
"description" : "Message indicating VM start was initiated"
},
"status_codes" : [
{
"code" : 202,
"description" : "VM start initiated (async operation)"
},
{
"code" : 400,
"description" : "Invalid request or VM not found"
}
]
},
{
"category" : "VM Management",
"description" : "Stop a running virtual machine",
"method" : "POST",
"path" : "\/lume\/vms\/:name\/stop",
"path_parameters" : [
{
"description" : "Name of the VM to stop",
"name" : "name",
"required" : true,
"type" : "string"
}
],
"query_parameters" : [
],
"request_body" : {
"content_type" : "application\/json",
"description" : "Stop options (optional)",
"fields" : [
{
"description" : "VM storage location",
"name" : "storage",
"required" : false,
"type" : "string"
}
]
},
"response_body" : {
"content_type" : "application\/json",
"description" : "Success message"
},
"status_codes" : [
{
"code" : 200,
"description" : "VM stopped successfully"
},
{
"code" : 400,
"description" : "Stop operation failed"
}
]
},
{
"category" : "Image Management",
"description" : "List available images from local cache",
"method" : "GET",
"path" : "\/lume\/images",
"path_parameters" : [
],
"query_parameters" : [
{
"description" : "Organization to list images for (default: trycua)",
"name" : "organization",
"required" : false,
"type" : "string"
}
],
"response_body" : {
"content_type" : "application\/json",
"description" : "Array of image objects with repository and imageId"
},
"status_codes" : [
{
"code" : 200,
"description" : "Success"
},
{
"code" : 400,
"description" : "Failed to list images"
}
]
},
{
"category" : "Image Management",
"description" : "Get the latest macOS restore image (IPSW) URL",
"method" : "GET",
"path" : "\/lume\/ipsw",
"path_parameters" : [
],
"query_parameters" : [
],
"response_body" : {
"content_type" : "application\/json",
"description" : "Object with url field containing the IPSW download URL"
},
"status_codes" : [
{
"code" : 200,
"description" : "Success"
},
{
"code" : 400,
"description" : "Failed to get IPSW URL"
}
]
},
{
"category" : "Image Management",
"description" : "Pull a VM image from a container registry",
"method" : "POST",
"path" : "\/lume\/pull",
"path_parameters" : [
],
"query_parameters" : [
],
"request_body" : {
"content_type" : "application\/json",
"description" : "Pull parameters",
"fields" : [
{
"description" : "Image to pull (format: name:tag)",
"name" : "image",
"required" : true,
"type" : "string"
},
{
"description" : "Name for the resulting VM",
"name" : "name",
"required" : false,
"type" : "string"
},
{
"default_value" : "ghcr.io",
"description" : "Container registry URL",
"name" : "registry",
"required" : false,
"type" : "string"
},
{
"default_value" : "trycua",
"description" : "Organization to pull from",
"name" : "organization",
"required" : false,
"type" : "string"
},
{
"description" : "VM storage location",
"name" : "storage",
"required" : false,
"type" : "string"
}
]
},
"response_body" : {
"content_type" : "application\/json",
"description" : "Success message with image and name"
},
"status_codes" : [
{
"code" : 200,
"description" : "Image pulled successfully"
},
{
"code" : 400,
"description" : "Pull operation failed"
}
]
},
{
"category" : "Image Management",
"description" : "Push a VM image to a container registry",
"method" : "POST",
"path" : "\/lume\/vms\/push",
"path_parameters" : [
],
"query_parameters" : [
],
"request_body" : {
"content_type" : "application\/json",
"description" : "Push parameters",
"fields" : [
{
"description" : "Name of the local VM to push",
"name" : "name",
"required" : true,
"type" : "string"
},
{
"description" : "Base name for the image in the registry",
"name" : "imageName",
"required" : true,
"type" : "string"
},
{
"description" : "List of tags to push",
"name" : "tags",
"required" : true,
"type" : "array"
},
{
"default_value" : "ghcr.io",
"description" : "Container registry URL",
"name" : "registry",
"required" : false,
"type" : "string"
},
{
"default_value" : "trycua",
"description" : "Organization to push to",
"name" : "organization",
"required" : false,
"type" : "string"
},
{
"description" : "VM storage location",
"name" : "storage",
"required" : false,
"type" : "string"
},
{
"default_value" : "512",
"description" : "Chunk size for upload in MB",
"name" : "chunkSizeMb",
"required" : false,
"type" : "integer"
}
]
},
"response_body" : {
"content_type" : "application\/json",
"description" : "Message indicating push was initiated"
},
"status_codes" : [
{
"code" : 202,
"description" : "Push initiated (async operation)"
},
{
"code" : 400,
"description" : "Invalid request"
}
]
},
{
"category" : "Image Management",
"description" : "Remove cached images to free up disk space",
"method" : "POST",
"path" : "\/lume\/prune",
"path_parameters" : [
],
"query_parameters" : [
],
"response_body" : {
"content_type" : "application\/json",
"description" : "Success message"
},
"status_codes" : [
{
"code" : 200,
"description" : "Images pruned successfully"
},
{
"code" : 400,
"description" : "Prune operation failed"
}
]
},
{
"category" : "Configuration",
"description" : "Get current Lume configuration settings",
"method" : "GET",
"path" : "\/lume\/config",
"path_parameters" : [
],
"query_parameters" : [
],
"response_body" : {
"content_type" : "application\/json",
"description" : "Configuration object with vmLocations, defaultLocationName, cacheDirectory, cachingEnabled"
},
"status_codes" : [
{
"code" : 200,
"description" : "Success"
},
{
"code" : 400,
"description" : "Failed to get config"
}
]
},
{
"category" : "Configuration",
"description" : "Update Lume configuration settings",
"method" : "POST",
"path" : "\/lume\/config",
"path_parameters" : [
],
"query_parameters" : [
],
"request_body" : {
"content_type" : "application\/json",
"description" : "Configuration fields to update (all optional)",
"fields" : [
{
"description" : "VM home directory path",
"name" : "homeDirectory",
"required" : false,
"type" : "string"
},
{
"description" : "Cache directory path",
"name" : "cacheDirectory",
"required" : false,
"type" : "string"
},
{
"description" : "Enable or disable image caching",
"name" : "cachingEnabled",
"required" : false,
"type" : "boolean"
}
]
},
"response_body" : {
"content_type" : "application\/json",
"description" : "Success message"
},
"status_codes" : [
{
"code" : 200,
"description" : "Configuration updated successfully"
},
{
"code" : 400,
"description" : "Invalid request"
}
]
},
{
"category" : "Configuration",
"description" : "List all VM storage locations",
"method" : "GET",
"path" : "\/lume\/config\/locations",
"path_parameters" : [
],
"query_parameters" : [
],
"response_body" : {
"content_type" : "application\/json",
"description" : "Array of location objects with name and path"
},
"status_codes" : [
{
"code" : 200,
"description" : "Success"
},
{
"code" : 400,
"description" : "Failed to get locations"
}
]
},
{
"category" : "Configuration",
"description" : "Add a new VM storage location",
"method" : "POST",
"path" : "\/lume\/config\/locations",
"path_parameters" : [
],
"query_parameters" : [
],
"request_body" : {
"content_type" : "application\/json",
"description" : "Location details",
"fields" : [
{
"description" : "Storage location name",
"name" : "name",
"required" : true,
"type" : "string"
},
{
"description" : "Path to storage directory",
"name" : "path",
"required" : true,
"type" : "string"
}
]
},
"response_body" : {
"content_type" : "application\/json",
"description" : "Success message with name and path"
},
"status_codes" : [
{
"code" : 200,
"description" : "Location added successfully"
},
{
"code" : 400,
"description" : "Invalid request or location already exists"
}
]
},
{
"category" : "Configuration",
"description" : "Remove a VM storage location",
"method" : "DELETE",
"path" : "\/lume\/config\/locations\/:name",
"path_parameters" : [
{
"description" : "Name of the location to remove",
"name" : "name",
"required" : true,
"type" : "string"
}
],
"query_parameters" : [
],
"response_body" : {
"content_type" : "application\/json",
"description" : "Success message"
},
"status_codes" : [
{
"code" : 200,
"description" : "Location removed successfully"
},
{
"code" : 400,
"description" : "Location not found or cannot be removed"
}
]
},
{
"category" : "Configuration",
"description" : "Set the default VM storage location",
"method" : "POST",
"path" : "\/lume\/config\/locations\/default\/:name",
"path_parameters" : [
{
"description" : "Name of the location to set as default",
"name" : "name",
"required" : true,
"type" : "string"
}
],
"query_parameters" : [
],
"response_body" : {
"content_type" : "application\/json",
"description" : "Success message"
},
"status_codes" : [
{
"code" : 200,
"description" : "Default location set successfully"
},
{
"code" : 400,
"description" : "Location not found"
}
]
},
{
"category" : "Logs",
"description" : "Retrieve Lume server logs",
"method" : "GET",
"path" : "\/lume\/logs",
"path_parameters" : [
],
"query_parameters" : [
{
"description" : "Log type: 'info', 'error', or 'all' (default: all)",
"name" : "type",
"required" : false,
"type" : "string"
},
{
"description" : "Number of lines to return from end of log",
"name" : "lines",
"required" : false,
"type" : "integer"
}
],
"response_body" : {
"content_type" : "application\/json",
"description" : "Object with 'info' and\/or 'error' fields containing log content"
},
"status_codes" : [
{
"code" : 200,
"description" : "Success"
},
{
"code" : 400,
"description" : "Failed to read logs"
}
]
}
],
"version" : "0.5.3"
}