Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.
Rust agentai-agentapplecomputer-usecomputer-use-agentcontainerizationcuadesktop-automationhacktoberfestlumemacosmanusoperatorswiftvirtualizationvirtualization-frameworkwindowswindows-sandbox
import Foundation
// MARK: - API Documentation Types
/// Represents documentation for a single API endpoint
struct APIEndpointDoc: Codable {
let method: String
let path: String
let description: String
let category: String
let pathParameters: [APIParameterDoc]
let queryParameters: [APIParameterDoc]
let requestBody: APIRequestBodyDoc?
let responseBody: APIResponseDoc
let statusCodes: [APIStatusCodeDoc]
}
/// Represents documentation for a parameter (path or query)
struct APIParameterDoc: Codable {
let name: String
let type: String
let required: Bool
let description: String
}
/// Represents documentation for a request body
struct APIRequestBodyDoc: Codable {
let contentType: String
let description: String
let fields: [APIFieldDoc]
}
/// Represents documentation for a response body
struct APIResponseDoc: Codable {
let contentType: String
let description: String
let fields: [APIFieldDoc]?
}
/// Represents documentation for a field in request/response body
struct APIFieldDoc: Codable {
let name: String
let type: String
let required: Bool
let description: String
let defaultValue: String?
}
/// Represents documentation for an HTTP status code
struct APIStatusCodeDoc: Codable {
let code: Int
let description: String
}
/// Root documentation structure for HTTP API
struct HTTPAPIDocumentation: Codable {
let basePath: String
let version: String
let description: String
let endpoints: [APIEndpointDoc]
}
// MARK: - API Documentation Extractor
enum APIDocExtractor {
/// Extract documentation for all API endpoints
static func extractAll() -> HTTPAPIDocumentation {
return HTTPAPIDocumentation(
basePath: "/lume",
version: Lume.Version.current,
description: "HTTP API for managing macOS and Linux virtual machines",
endpoints: allEndpoints
)
}
/// All documented API endpoints
private static var allEndpoints: [APIEndpointDoc] {
return [
// VM Management
listVMs,
getVM,
createVM,
deleteVM,
cloneVM,
updateVM,
runVM,
stopVM,
suspendVM,
renameVM,
// Image Management
getImages,
getIPSW,
pullImage,
pullImageAsync,
cancelPull,
pushImage,
pruneImages,
// Configuration
getConfig,
updateConfig,
getLocations,
addLocation,
removeLocation,
setDefaultLocation,
// Logs
getLogs,
]
}
// MARK: - VM Management Endpoints
private static var listVMs: APIEndpointDoc {
APIEndpointDoc(
method: "GET",
path: "/lume/vms",
description: "List all virtual machines",
category: "VM Management",
pathParameters: [],
queryParameters: [
APIParameterDoc(name: "storage", type: "string", required: false, description: "Filter by storage location name")
],
requestBody: nil,
responseBody: APIResponseDoc(
contentType: "application/json",
description: "Array of VM details objects",
fields: nil
),
statusCodes: [
APIStatusCodeDoc(code: 200, description: "Success"),
APIStatusCodeDoc(code: 400, description: "Bad request")
]
)
}
private static var getVM: APIEndpointDoc {
APIEndpointDoc(
method: "GET",
path: "/lume/vms/:name",
description: "Get detailed information about a specific virtual machine",
category: "VM Management",
pathParameters: [
APIParameterDoc(name: "name", type: "string", required: true, description: "Name of the VM")
],
queryParameters: [
APIParameterDoc(name: "storage", type: "string", required: false, description: "VM storage location to use")
],
requestBody: nil,
responseBody: APIResponseDoc(
contentType: "application/json",
description: "VM details object with name, os, cpuCount, memorySize, diskSize, display, status, vncUrl, ipAddress, locationName",
fields: [
APIFieldDoc(name: "name", type: "string", required: true, description: "VM name", defaultValue: nil),
APIFieldDoc(name: "os", type: "string", required: true, description: "Operating system (macOS or linux)", defaultValue: nil),
APIFieldDoc(name: "cpuCount", type: "integer", required: true, description: "Number of CPU cores", defaultValue: nil),
APIFieldDoc(name: "memorySize", type: "integer", required: true, description: "Memory size in bytes", defaultValue: nil),
APIFieldDoc(name: "diskSize", type: "object", required: true, description: "Disk size with allocated and total", defaultValue: nil),
APIFieldDoc(name: "display", type: "string", required: true, description: "Display resolution (WIDTHxHEIGHT)", defaultValue: nil),
APIFieldDoc(name: "status", type: "string", required: true, description: "VM status (running, stopped)", defaultValue: nil),
APIFieldDoc(name: "vncUrl", type: "string", required: false, description: "VNC URL if running", defaultValue: nil),
APIFieldDoc(name: "ipAddress", type: "string", required: false, description: "IP address if running", defaultValue: nil),
APIFieldDoc(name: "locationName", type: "string", required: true, description: "Storage location name", defaultValue: nil),
APIFieldDoc(name: "savedState", type: "boolean", required: false, description: "The VM has a saved machine state (suspend) that its next run resumes", defaultValue: nil),
APIFieldDoc(name: "downloadProgress", type: "number", required: false, description: "While an async pull runs (status \"pulling\"): downloaded percent, 0 to 100", defaultValue: nil),
APIFieldDoc(name: "downloadedBytes", type: "integer", required: false, description: "While an async pull runs: bytes downloaded so far", defaultValue: nil),
APIFieldDoc(name: "totalBytes", type: "integer", required: false, description: "While an async pull runs: total bytes to download (0 until known)", defaultValue: nil),
APIFieldDoc(name: "bytesPerSecond", type: "number", required: false, description: "While an async pull runs: smoothed transfer rate in bytes per second", defaultValue: nil)
]
),
statusCodes: [
APIStatusCodeDoc(code: 200, description: "Success (while an async pull runs, only name, status \"pulling\", downloadProgress, downloadedBytes, totalBytes and bytesPerSecond)"),
APIStatusCodeDoc(code: 400, description: "VM not found, invalid request, or the async pull failed")
]
)
}
private static var createVM: APIEndpointDoc {
APIEndpointDoc(
method: "POST",
path: "/lume/vms",
description: "Create a new virtual machine",
category: "VM Management",
pathParameters: [],
queryParameters: [],
requestBody: APIRequestBodyDoc(
contentType: "application/json",
description: "VM creation parameters",
fields: [
APIFieldDoc(name: "name", type: "string", required: true, description: "Name for the virtual machine", defaultValue: nil),
APIFieldDoc(name: "os", type: "string", required: true, description: "Operating system to install (macOS or linux)", defaultValue: nil),
APIFieldDoc(name: "cpu", type: "integer", required: true, description: "Number of CPU cores", defaultValue: nil),
APIFieldDoc(name: "memory", type: "string", required: true, description: "Memory size (e.g., 8GB)", defaultValue: nil),
APIFieldDoc(name: "diskSize", type: "string", required: true, description: "Disk size (e.g., 50GB)", defaultValue: nil),
APIFieldDoc(name: "display", type: "string", required: true, description: "Display resolution (e.g., 1024x768)", defaultValue: nil),
APIFieldDoc(name: "ipsw", type: "string", required: false, description: "Path to IPSW file or 'latest' for macOS VMs", defaultValue: nil),
APIFieldDoc(name: "storage", type: "string", required: false, description: "VM storage location to use", defaultValue: nil)
]
),
responseBody: APIResponseDoc(
contentType: "application/json",
description: "Success message with VM name",
fields: nil
),
statusCodes: [
APIStatusCodeDoc(code: 200, description: "VM created successfully"),
APIStatusCodeDoc(code: 400, description: "Invalid request body or VM creation failed")
]
)
}
private static var deleteVM: APIEndpointDoc {
APIEndpointDoc(
method: "DELETE",
path: "/lume/vms/:name",
description: "Delete a virtual machine and its associated files",
category: "VM Management",
pathParameters: [
APIParameterDoc(name: "name", type: "string", required: true, description: "Name of the VM to delete")
],
queryParameters: [
APIParameterDoc(name: "storage", type: "string", required: false, description: "VM storage location")
],
requestBody: nil,
responseBody: APIResponseDoc(
contentType: "application/json",
description: "Empty response on success",
fields: nil
),
statusCodes: [
APIStatusCodeDoc(code: 200, description: "VM deleted successfully"),
APIStatusCodeDoc(code: 400, description: "VM not found or deletion failed")
]
)
}
private static var cloneVM: APIEndpointDoc {
APIEndpointDoc(
method: "POST",
path: "/lume/vms/clone",
description: "Create a copy of an existing virtual machine",
category: "VM Management",
pathParameters: [],
queryParameters: [],
requestBody: APIRequestBodyDoc(
contentType: "application/json",
description: "Clone parameters",
fields: [
APIFieldDoc(name: "name", type: "string", required: true, description: "Name of the source VM", defaultValue: nil),
APIFieldDoc(name: "newName", type: "string", required: true, description: "Name for the cloned VM", defaultValue: nil),
APIFieldDoc(name: "sourceLocation", type: "string", required: false, description: "Source VM storage location", defaultValue: nil),
APIFieldDoc(name: "destLocation", type: "string", required: false, description: "Destination VM storage location", defaultValue: nil),
APIFieldDoc(name: "withSavedState", type: "boolean", required: false, description: "Clone the source's saved machine state too (see suspend): the clone keeps the source's MAC address and machine identifier, which the state is bound to, and its first run resumes the saved guest", defaultValue: "false")
]
),
responseBody: APIResponseDoc(
contentType: "application/json",
description: "Success message with source and destination names",
fields: nil
),
statusCodes: [
APIStatusCodeDoc(code: 200, description: "VM cloned successfully"),
APIStatusCodeDoc(code: 400, description: "Clone operation failed")
]
)
}
private static var updateVM: APIEndpointDoc {
APIEndpointDoc(
method: "PATCH",
path: "/lume/vms/:name",
description: "Update virtual machine configuration settings",
category: "VM Management",
pathParameters: [
APIParameterDoc(name: "name", type: "string", required: true, description: "Name of the VM to update")
],
queryParameters: [],
requestBody: APIRequestBodyDoc(
contentType: "application/json",
description: "Settings to update (all fields optional)",
fields: [
APIFieldDoc(name: "cpu", type: "integer", required: false, description: "New number of CPU cores", defaultValue: nil),
APIFieldDoc(name: "memory", type: "string", required: false, description: "New memory size (e.g., 16GB)", defaultValue: nil),
APIFieldDoc(name: "diskSize", type: "string", required: false, description: "New total disk size (increase only)", defaultValue: nil),
APIFieldDoc(name: "display", type: "string", required: false, description: "New display resolution", defaultValue: nil),
APIFieldDoc(name: "storage", type: "string", required: false, description: "VM storage location", defaultValue: nil),
APIFieldDoc(name: "noBackup", type: "boolean", required: false, description: "Skip the macOS rollback backup", defaultValue: "false"),
APIFieldDoc(name: "keepBackup", type: "boolean", required: false, description: "Keep rollback files after success", defaultValue: "false"),
APIFieldDoc(name: "dryRun", type: "boolean", required: false, description: "Validate the resize plan without modifying the disk", defaultValue: "false")
]
),
responseBody: APIResponseDoc(
contentType: "application/json",
description: "Success message",
fields: nil
),
statusCodes: [
APIStatusCodeDoc(code: 200, description: "Settings updated successfully"),
APIStatusCodeDoc(code: 400, description: "Invalid settings or update failed")
]
)
}
private static var runVM: APIEndpointDoc {
APIEndpointDoc(
method: "POST",
path: "/lume/vms/:name/run",
description: "Start a virtual machine",
category: "VM Management",
pathParameters: [
APIParameterDoc(name: "name", type: "string", required: true, description: "Name of the VM to start")
],
queryParameters: [],
requestBody: APIRequestBodyDoc(
contentType: "application/json",
description: "Run options (all fields optional)",
fields: [
APIFieldDoc(name: "noDisplay", type: "boolean", required: false, description: "Run without VNC display", defaultValue: "false"),
APIFieldDoc(name: "sharedDirectories", type: "array", required: false, description: "Directories to share with the VM", defaultValue: nil),
APIFieldDoc(name: "recoveryMode", type: "boolean", required: false, description: "Boot macOS VM in recovery mode", defaultValue: "false"),
APIFieldDoc(name: "storage", type: "string", required: false, description: "VM storage location", defaultValue: nil),
APIFieldDoc(name: "clipboard", type: "boolean", required: false, description: "Enable bidirectional clipboard sync via SSH (experimental)", defaultValue: "false"),
APIFieldDoc(name: "vnc", type: "string", required: false, description: "VNC server policy: 'enabled' or 'disabled'. 'disabled' requires noDisplay=true, starts no VNC listener, and reports a null vncUrl", defaultValue: "enabled"),
APIFieldDoc(name: "forwards", type: "array", required: false, description: "Guest ports to publish on host loopback ports over a virtio socket device, through Cua's guest vsock agent. GET reports the host ports under 'forwards' once the agent answers; these connections are not subject to macOS Local Network privacy or VPN routes", defaultValue: nil)
]
),
responseBody: APIResponseDoc(
contentType: "application/json",
description: "Message indicating VM start was initiated",
fields: nil
),
statusCodes: [
APIStatusCodeDoc(code: 202, description: "VM start initiated (async operation)"),
APIStatusCodeDoc(code: 409, description: "Host limit of running macOS guests reached"),
APIStatusCodeDoc(code: 400, description: "Invalid request or VM not found")
]
)
}
private static var stopVM: APIEndpointDoc {
APIEndpointDoc(
method: "POST",
path: "/lume/vms/:name/stop",
description: "Stop a running virtual machine",
category: "VM Management",
pathParameters: [
APIParameterDoc(name: "name", type: "string", required: true, description: "Name of the VM to stop")
],
queryParameters: [],
requestBody: APIRequestBodyDoc(
contentType: "application/json",
description: "Stop options (optional)",
fields: [
APIFieldDoc(name: "storage", type: "string", required: false, description: "VM storage location", defaultValue: nil)
]
),
responseBody: APIResponseDoc(
contentType: "application/json",
description: "Success message",
fields: nil
),
statusCodes: [
APIStatusCodeDoc(code: 200, description: "VM stopped successfully"),
APIStatusCodeDoc(code: 400, description: "Stop operation failed")
]
)
}
private static var suspendVM: APIEndpointDoc {
APIEndpointDoc(
method: "POST",
path: "/lume/vms/:name/suspend",
description: "Suspend a running virtual machine to disk (its next run resumes it)",
category: "VM Management",
pathParameters: [
APIParameterDoc(name: "name", type: "string", required: true, description: "Name of the VM to suspend")
],
queryParameters: [],
requestBody: nil,
responseBody: APIResponseDoc(
contentType: "application/json",
description: "Success message",
fields: nil
),
statusCodes: [
APIStatusCodeDoc(code: 200, description: "The VM's memory and device state were saved next to its disk (macOS 14 or later) and the VM stopped; a run resumes it, a cold boot discards the state"),
APIStatusCodeDoc(code: 400, description: "The VM does not run in this lume serve, or the save failed (the VM keeps running)")
]
)
}
private static var renameVM: APIEndpointDoc {
APIEndpointDoc(
method: "POST",
path: "/lume/vms/:name/rename",
description: "Rename a virtual machine, running or stopped",
category: "VM Management",
pathParameters: [
APIParameterDoc(name: "name", type: "string", required: true, description: "Name of the VM to rename")
],
queryParameters: [],
requestBody: APIRequestBodyDoc(
contentType: "application/json",
description: "Rename parameters",
fields: [
APIFieldDoc(name: "newName", type: "string", required: true, description: "The VM's new name", defaultValue: nil),
APIFieldDoc(name: "storage", type: "string", required: false, description: "VM storage location", defaultValue: nil)
]
),
responseBody: APIResponseDoc(
contentType: "application/json",
description: "Success message with the new name",
fields: nil
),
statusCodes: [
APIStatusCodeDoc(code: 200, description: "VM renamed (a running VM keeps running)"),
APIStatusCodeDoc(code: 400, description: "The name is taken or invalid, or the VM runs in another process than this lume serve")
]
)
}
// MARK: - Image Management Endpoints
private static var getImages: APIEndpointDoc {
APIEndpointDoc(
method: "GET",
path: "/lume/images",
description: "List available images from local cache",
category: "Image Management",
pathParameters: [],
queryParameters: [
APIParameterDoc(name: "organization", type: "string", required: false, description: "Organization to list images for (default: trycua)")
],
requestBody: nil,
responseBody: APIResponseDoc(
contentType: "application/json",
description: "Array of image objects with repository and imageId",
fields: nil
),
statusCodes: [
APIStatusCodeDoc(code: 200, description: "Success"),
APIStatusCodeDoc(code: 400, description: "Failed to list images")
]
)
}
private static var getIPSW: APIEndpointDoc {
APIEndpointDoc(
method: "GET",
path: "/lume/ipsw",
description: "Get the latest macOS restore image (IPSW) URL",
category: "Image Management",
pathParameters: [],
queryParameters: [],
requestBody: nil,
responseBody: APIResponseDoc(
contentType: "application/json",
description: "Object with url field containing the IPSW download URL",
fields: nil
),
statusCodes: [
APIStatusCodeDoc(code: 200, description: "Success"),
APIStatusCodeDoc(code: 400, description: "Failed to get IPSW URL")
]
)
}
private static var pullImage: APIEndpointDoc {
APIEndpointDoc(
method: "POST",
path: "/lume/pull",
description: "Pull a VM image from a container registry",
category: "Image Management",
pathParameters: [],
queryParameters: [],
requestBody: APIRequestBodyDoc(
contentType: "application/json",
description: "Pull parameters",
fields: [
APIFieldDoc(name: "image", type: "string", required: true, description: "Image to pull (format: name:tag)", defaultValue: nil),
APIFieldDoc(name: "name", type: "string", required: false, description: "Name for the resulting VM", defaultValue: nil),
APIFieldDoc(name: "registry", type: "string", required: false, description: "Container registry URL", defaultValue: "ghcr.io"),
APIFieldDoc(name: "organization", type: "string", required: false, description: "Organization to pull from", defaultValue: "trycua"),
APIFieldDoc(name: "storage", type: "string", required: false, description: "VM storage location", defaultValue: nil)
]
),
responseBody: APIResponseDoc(
contentType: "application/json",
description: "Success message with image and name",
fields: nil
),
statusCodes: [
APIStatusCodeDoc(code: 200, description: "Image pulled successfully"),
APIStatusCodeDoc(code: 400, description: "Pull operation failed")
]
)
}
private static var pullImageAsync: APIEndpointDoc {
APIEndpointDoc(
method: "POST",
path: "/lume/pull/start",
description: "Start a background pull",
category: "Image Management",
pathParameters: [],
queryParameters: [],
requestBody: APIRequestBodyDoc(
contentType: "application/json",
description: "Pull parameters (same as POST /lume/pull)",
fields: [
APIFieldDoc(name: "image", type: "string", required: true, description: "Image to pull (format: name:tag)", defaultValue: nil),
APIFieldDoc(name: "name", type: "string", required: false, description: "Name for the resulting VM", defaultValue: nil),
APIFieldDoc(name: "registry", type: "string", required: false, description: "Container registry URL", defaultValue: "ghcr.io"),
APIFieldDoc(name: "organization", type: "string", required: false, description: "Organization to pull from", defaultValue: "trycua"),
APIFieldDoc(name: "storage", type: "string", required: false, description: "VM storage location", defaultValue: nil)
]
),
responseBody: APIResponseDoc(
contentType: "application/json",
description: "Object with message, name and image. A start for a name that is already pulling joins that pull (message \"Pull already in progress\")",
fields: nil
),
statusCodes: [
APIStatusCodeDoc(code: 202, description: "Pull started or already in progress"),
APIStatusCodeDoc(code: 400, description: "Invalid request body")
]
)
}
private static var cancelPull: APIEndpointDoc {
APIEndpointDoc(
method: "POST",
path: "/lume/pull/cancel",
description: "Cancel a background pull",
category: "Image Management",
pathParameters: [],
queryParameters: [],
requestBody: APIRequestBodyDoc(
contentType: "application/json",
description: "The VM name the pull was started for",
fields: [
APIFieldDoc(name: "name", type: "string", required: true, description: "VM name of the pull to cancel", defaultValue: nil)
]
),
responseBody: APIResponseDoc(
contentType: "application/json",
description: "Object with message (\"Pull cancelled\") and name",
fields: nil
),
statusCodes: [
APIStatusCodeDoc(code: 200, description: "The pull stopped and was cleaned up"),
APIStatusCodeDoc(code: 400, description: "Invalid request body"),
APIStatusCodeDoc(code: 404, description: "No background pull in progress for the name (for example it already finished or was cancelled)"),
APIStatusCodeDoc(code: 500, description: "The pull did not stop within 30 seconds")
]
)
}
private static var pushImage: APIEndpointDoc {
APIEndpointDoc(
method: "POST",
path: "/lume/vms/push",
description: "Push a VM image to a container registry",
category: "Image Management",
pathParameters: [],
queryParameters: [],
requestBody: APIRequestBodyDoc(
contentType: "application/json",
description: "Push parameters",
fields: [
APIFieldDoc(name: "name", type: "string", required: true, description: "Name of the local VM to push", defaultValue: nil),
APIFieldDoc(name: "imageName", type: "string", required: true, description: "Base name for the image in the registry", defaultValue: nil),
APIFieldDoc(name: "tags", type: "array", required: true, description: "List of tags to push", defaultValue: nil),
APIFieldDoc(name: "registry", type: "string", required: false, description: "Container registry URL", defaultValue: "ghcr.io"),
APIFieldDoc(name: "organization", type: "string", required: false, description: "Organization to push to", defaultValue: "trycua"),
APIFieldDoc(name: "storage", type: "string", required: false, description: "VM storage location", defaultValue: nil),
APIFieldDoc(name: "chunkSizeMb", type: "integer", required: false, description: "Chunk size for upload in MB", defaultValue: "512")
]
),
responseBody: APIResponseDoc(
contentType: "application/json",
description: "Message indicating push was initiated",
fields: nil
),
statusCodes: [
APIStatusCodeDoc(code: 202, description: "Push initiated (async operation)"),
APIStatusCodeDoc(code: 400, description: "Invalid request")
]
)
}
private static var pruneImages: APIEndpointDoc {
APIEndpointDoc(
method: "POST",
path: "/lume/prune",
description: "Remove cached images to free up disk space",
category: "Image Management",
pathParameters: [],
queryParameters: [],
requestBody: nil,
responseBody: APIResponseDoc(
contentType: "application/json",
description: "Success message",
fields: nil
),
statusCodes: [
APIStatusCodeDoc(code: 200, description: "Images pruned successfully"),
APIStatusCodeDoc(code: 400, description: "Prune operation failed")
]
)
}
// MARK: - Configuration Endpoints
private static var getConfig: APIEndpointDoc {
APIEndpointDoc(
method: "GET",
path: "/lume/config",
description: "Get current Lume configuration settings",
category: "Configuration",
pathParameters: [],
queryParameters: [],
requestBody: nil,
responseBody: APIResponseDoc(
contentType: "application/json",
description: "Configuration object with vmLocations, defaultLocationName, cacheDirectory, cachingEnabled",
fields: nil
),
statusCodes: [
APIStatusCodeDoc(code: 200, description: "Success"),
APIStatusCodeDoc(code: 400, description: "Failed to get config")
]
)
}
private static var updateConfig: APIEndpointDoc {
APIEndpointDoc(
method: "POST",
path: "/lume/config",
description: "Update Lume configuration settings",
category: "Configuration",
pathParameters: [],
queryParameters: [],
requestBody: APIRequestBodyDoc(
contentType: "application/json",
description: "Configuration fields to update (all optional)",
fields: [
APIFieldDoc(name: "homeDirectory", type: "string", required: false, description: "VM home directory path", defaultValue: nil),
APIFieldDoc(name: "cacheDirectory", type: "string", required: false, description: "Cache directory path", defaultValue: nil),
APIFieldDoc(name: "cachingEnabled", type: "boolean", required: false, description: "Enable or disable image caching", defaultValue: nil)
]
),
responseBody: APIResponseDoc(
contentType: "application/json",
description: "Success message",
fields: nil
),
statusCodes: [
APIStatusCodeDoc(code: 200, description: "Configuration updated successfully"),
APIStatusCodeDoc(code: 400, description: "Invalid request")
]
)
}
private static var getLocations: APIEndpointDoc {
APIEndpointDoc(
method: "GET",
path: "/lume/config/locations",
description: "List all VM storage locations",
category: "Configuration",
pathParameters: [],
queryParameters: [],
requestBody: nil,
responseBody: APIResponseDoc(
contentType: "application/json",
description: "Array of location objects with name and path",
fields: nil
),
statusCodes: [
APIStatusCodeDoc(code: 200, description: "Success"),
APIStatusCodeDoc(code: 400, description: "Failed to get locations")
]
)
}
private static var addLocation: APIEndpointDoc {
APIEndpointDoc(
method: "POST",
path: "/lume/config/locations",
description: "Add a new VM storage location",
category: "Configuration",
pathParameters: [],
queryParameters: [],
requestBody: APIRequestBodyDoc(
contentType: "application/json",
description: "Location details",
fields: [
APIFieldDoc(name: "name", type: "string", required: true, description: "Storage location name", defaultValue: nil),
APIFieldDoc(name: "path", type: "string", required: true, description: "Path to storage directory", defaultValue: nil)
]
),
responseBody: APIResponseDoc(
contentType: "application/json",
description: "Success message with name and path",
fields: nil
),
statusCodes: [
APIStatusCodeDoc(code: 200, description: "Location added successfully"),
APIStatusCodeDoc(code: 400, description: "Invalid request or location already exists")
]
)
}
private static var removeLocation: APIEndpointDoc {
APIEndpointDoc(
method: "DELETE",
path: "/lume/config/locations/:name",
description: "Remove a VM storage location",
category: "Configuration",
pathParameters: [
APIParameterDoc(name: "name", type: "string", required: true, description: "Name of the location to remove")
],
queryParameters: [],
requestBody: nil,
responseBody: APIResponseDoc(
contentType: "application/json",
description: "Success message",
fields: nil
),
statusCodes: [
APIStatusCodeDoc(code: 200, description: "Location removed successfully"),
APIStatusCodeDoc(code: 400, description: "Location not found or cannot be removed")
]
)
}
private static var setDefaultLocation: APIEndpointDoc {
APIEndpointDoc(
method: "POST",
path: "/lume/config/locations/default/:name",
description: "Set the default VM storage location",
category: "Configuration",
pathParameters: [
APIParameterDoc(name: "name", type: "string", required: true, description: "Name of the location to set as default")
],
queryParameters: [],
requestBody: nil,
responseBody: APIResponseDoc(
contentType: "application/json",
description: "Success message",
fields: nil
),
statusCodes: [
APIStatusCodeDoc(code: 200, description: "Default location set successfully"),
APIStatusCodeDoc(code: 400, description: "Location not found")
]
)
}
// MARK: - Logs Endpoint
private static var getLogs: APIEndpointDoc {
APIEndpointDoc(
method: "GET",
path: "/lume/logs",
description: "Retrieve Lume server logs",
category: "Logs",
pathParameters: [],
queryParameters: [
APIParameterDoc(name: "type", type: "string", required: false, description: "Log type: 'info', 'error', or 'all' (default: all)"),
APIParameterDoc(name: "lines", type: "integer", required: false, description: "Number of lines to return from end of log")
],
requestBody: nil,
responseBody: APIResponseDoc(
contentType: "application/json",
description: "Object with 'info' and/or 'error' fields containing log content",
fields: nil
),
statusCodes: [
APIStatusCodeDoc(code: 200, description: "Success"),
APIStatusCodeDoc(code: 400, description: "Failed to read logs")
]
)
}
}