openapi: 3.1.0 info: title: Freestyle VMs API version: 0.1.0 description: "Manage Linux microVMs designed for AI agents \u2014 create, snapshot, fork, suspend, resume, exec, file I/O,\ \ watch, systemd services, terminals, and resize. Real Linux VMs that start in under 600ms." contact: name: Ben email: ben@freestyle.sh license: name: Closed Source servers: - url: https://api.freestyle.sh description: Production tags: - name: VM description: APIs for managing lightweight virtual machines (VMs) to run your code in isolated environments. paths: /v1/vms: get: tags: - VM description: List VMs operationId: list_vms parameters: - name: limit in: query required: false schema: type: - integer - 'null' format: int32 minimum: 0 - name: offset in: query required: false schema: type: - integer - 'null' format: int32 minimum: 0 - name: vmState in: query required: false schema: oneOf: - type: 'null' - $ref: '#/components/schemas/VMState' - name: includeDeleted in: query required: false schema: type: - boolean - 'null' - name: search in: query required: false schema: type: - string - 'null' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/ListVmsResponse' '500': description: 'Error: InternalError' content: application/json: schema: type: object required: - error - message properties: error: type: string description: Error code in SCREAMING_SNAKE_CASE message: type: string description: Human-readable error message post: tags: - VM description: Create VM operationId: create_vm requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateVmRequest' required: true responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/CreateVmResponse' /v1/vms/builds/{build_id}: get: tags: - VM description: Fetch a single build by id. operationId: get_build parameters: - name: build_id in: path description: Build id required: true schema: $ref: '#/components/schemas/BuildId' responses: '200': description: Build record content: application/json: schema: $ref: '#/components/schemas/BuildRecord' '404': description: 'Possible errors: BuildNotFound, BuildNotFoundForSnapshot, BuildNotFoundForVm' content: application/json: schema: type: object required: - error - message properties: error: type: string description: Error code in SCREAMING_SNAKE_CASE message: type: string description: Human-readable error message '500': description: 'Error: InternalError' content: application/json: schema: type: object required: - error - message properties: error: type: string description: Error code in SCREAMING_SNAKE_CASE message: type: string description: Human-readable error message /v1/vms/builds/{build_id}/phases: get: tags: - VM description: Append-only timeline of phases this build passed through. Phases are ordered by started_at; the last entry is the current phase. operationId: list_build_phases parameters: - name: build_id in: path description: Build id required: true schema: $ref: '#/components/schemas/BuildId' responses: '200': description: Ordered phase timeline for a build content: application/json: schema: $ref: '#/components/schemas/ListBuildPhasesResponse' '404': description: 'Possible errors: BuildNotFound, BuildNotFoundForSnapshot, BuildNotFoundForVm' content: application/json: schema: type: object required: - error - message properties: error: type: string description: Error code in SCREAMING_SNAKE_CASE message: type: string description: Human-readable error message '500': description: 'Error: InternalError' content: application/json: schema: type: object required: - error - message properties: error: type: string description: Error code in SCREAMING_SNAKE_CASE message: type: string description: Human-readable error message /v1/vms/snapshots: get: tags: - VM description: List all snapshots. operationId: list_snapshots parameters: - name: includeDeleted in: query required: false schema: type: - boolean - 'null' - name: includeFailed in: query required: false schema: type: - boolean - 'null' - name: includeBuilding in: query required: false schema: type: - boolean - 'null' responses: '200': description: List of snapshots content: application/json: schema: $ref: '#/components/schemas/ListSnapshotsResponse' '400': description: 'Error: SnapshotVmBadRequest' content: application/json: schema: type: object required: - error - message properties: error: type: string description: Error code in SCREAMING_SNAKE_CASE message: type: string description: Human-readable error message '500': description: 'Possible errors: SnapshotSetupFailed, FinalizeSnapshotFailed, InternalError' content: application/json: schema: type: object required: - error - message properties: error: type: string description: Error code in SCREAMING_SNAKE_CASE message: type: string description: Human-readable error message post: tags: - VM description: Create a snapshot by creating a temporary VM, starting it, snapshotting it, then deleting the VM. Supports multi-layer recursive specs via `spec.snapshot`. operationId: create_snapshot requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateSnapshotRequest' required: true responses: '200': description: Created snapshot content: application/json: schema: $ref: '#/components/schemas/CreateSnapshotResponse' /v1/vms/snapshots/{snapshot_id}: get: tags: - VM description: "Fetch a single snapshot by id. Returns deleted/failed rows too \u2014 useful for opening a deep-link to\ \ a layer-snapshot that's since been cleaned up." operationId: get_snapshot parameters: - name: snapshot_id in: path description: Snapshot id required: true schema: $ref: '#/components/schemas/SnapshotId' responses: '200': description: Snapshot record content: application/json: schema: $ref: '#/components/schemas/SnapshotInfo' '404': description: 'Error: SnapshotNotFound' content: application/json: schema: type: object required: - error - message properties: error: type: string description: Error code in SCREAMING_SNAKE_CASE message: type: string description: Human-readable error message '500': description: 'Error: InternalError' content: application/json: schema: type: object required: - error - message properties: error: type: string description: Error code in SCREAMING_SNAKE_CASE message: type: string description: Human-readable error message delete: tags: - VM description: Delete a snapshot operationId: delete_snapshot parameters: - name: snapshot_id in: path description: The ID of the snapshot to delete required: true schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/DeleteSnapshotResponses' '404': description: 'Error: SnapshotNotFound' content: application/json: schema: type: object required: - error - message properties: error: type: string description: Error code in SCREAMING_SNAKE_CASE message: type: string description: Human-readable error message '409': description: 'Possible errors: SnapshotAlreadyDeleted, SnapshotIsAccountDefault' content: application/json: schema: type: object required: - error - message properties: error: type: string description: Error code in SCREAMING_SNAKE_CASE message: type: string description: Human-readable error message '500': description: 'Error: InternalError' content: application/json: schema: type: object required: - error - message properties: error: type: string description: Error code in SCREAMING_SNAKE_CASE message: type: string description: Human-readable error message patch: tags: - VM description: Update snapshot metadata operationId: update_snapshot parameters: - name: snapshot_id in: path description: The ID of the snapshot to update required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateSnapshotRequest' required: true responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/UpdateSnapshotResponses' '404': description: 'Error: SnapshotNotFound' content: application/json: schema: type: object required: - error - message properties: error: type: string description: Error code in SCREAMING_SNAKE_CASE message: type: string description: Human-readable error message '500': description: 'Error: InternalError' content: application/json: schema: type: object required: - error - message properties: error: type: string description: Error code in SCREAMING_SNAKE_CASE message: type: string description: Human-readable error message /v1/vms/{id}/resize: post: tags: - VM description: Resize VM operationId: resize_vm parameters: - name: id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/ResizeVmRequest' required: true responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/ResizeVmResponse' '400': description: 'Error: InvalidParameters' content: application/json: schema: type: object required: - error - message properties: error: type: string description: Error code in SCREAMING_SNAKE_CASE message: type: string description: Human-readable error message '404': description: 'Error: InternalResizeVmNotFound' content: application/json: schema: type: object required: - error - message properties: error: type: string description: Error code in SCREAMING_SNAKE_CASE message: type: string description: Human-readable error message '500': description: 'Error: ResizeFailed' content: application/json: schema: type: object required: - error - message properties: error: type: string description: Error code in SCREAMING_SNAKE_CASE message: type: string description: Human-readable error message /v1/vms/{vm_id}: get: tags: - VM description: Get VM operationId: get_vm parameters: - name: vm_id in: path required: true schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/GetVmResponse' '500': description: 'Possible errors: VmDeleted, InternalError' content: application/json: schema: type: object required: - error - message properties: error: type: string description: Error code in SCREAMING_SNAKE_CASE message: type: string description: Human-readable error message delete: tags: - VM description: Delete VM operationId: delete_vm parameters: - name: vm_id in: path description: The ID of the VM to delete required: true schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/DeleteVmResponses' '500': description: 'Possible errors: ClientError, CleanupError' content: application/json: schema: type: object required: - error - message properties: error: type: string description: Error code in SCREAMING_SNAKE_CASE message: type: string description: Human-readable error message /v1/vms/{vm_id}/await: post: tags: - VM description: Wait for VM to stop operationId: wait_vm parameters: - name: vm_id in: path description: The ID of the VM to wait for required: true schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/WaitVmResponse' '500': description: 'Error: InternalError' content: application/json: schema: type: object required: - error - message properties: error: type: string description: Error code in SCREAMING_SNAKE_CASE message: type: string description: Human-readable error message /v1/vms/{vm_id}/build: get: tags: - VM description: Fetch the build that produced a VM. Joins through vm_records.build_id. operationId: get_build_for_vm parameters: - name: vm_id in: path description: VM id required: true schema: $ref: '#/components/schemas/VmId' responses: '200': description: Build that produced this VM content: application/json: schema: $ref: '#/components/schemas/BuildRecord' '404': description: 'Possible errors: BuildNotFound, BuildNotFoundForSnapshot, BuildNotFoundForVm' content: application/json: schema: type: object required: - error - message properties: error: type: string description: Error code in SCREAMING_SNAKE_CASE message: type: string description: Human-readable error message '500': description: 'Error: InternalError' content: application/json: schema: type: object required: - error - message properties: error: type: string description: Error code in SCREAMING_SNAKE_CASE message: type: string description: Human-readable error message /v1/vms/{vm_id}/exec-await: post: tags: - VM description: Execute command in VM and await result operationId: exec_await parameters: - name: vm_id in: path description: The ID of the VM to execute the command in required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/ExecAwaitRequest' required: true responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/ExecAwaitVmResponse' '408': description: 'Error: ExecTimedOut' content: application/json: schema: type: object required: - error - message properties: error: type: string description: Error code in SCREAMING_SNAKE_CASE message: type: string description: Human-readable error message '500': description: 'Error: InternalError' content: application/json: schema: type: object required: - error - message properties: error: type: string description: Error code in SCREAMING_SNAKE_CASE message: type: string description: Human-readable error message /v1/vms/{vm_id}/files/{filepath}: get: tags: - VM description: Get file from VM operationId: get_file parameters: - name: vm_id in: path description: The ID of the VM to get the file from required: true schema: type: string - name: filepath in: path description: The path of the file to get required: true schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/FileSystemResponse' '400': description: 'Error: FilesBadRequest' content: application/json: schema: type: object required: - error - message properties: error: type: string description: Error code in SCREAMING_SNAKE_CASE message: type: string description: Human-readable error message '404': description: 'Error: FileNotFound' content: application/json: schema: type: object required: - error - message properties: error: type: string description: Error code in SCREAMING_SNAKE_CASE message: type: string description: Human-readable error message '500': description: 'Error: InternalError' content: application/json: schema: type: object required: - error - message properties: error: type: string description: Error code in SCREAMING_SNAKE_CASE message: type: string description: Human-readable error message put: tags: - VM description: Put file to VM operationId: put_file parameters: - name: vm_id in: path description: The ID of the VM to put the file to required: true schema: type: string - name: filepath in: path description: The path of the file to put required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/WriteFileRequest' required: true responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/WriteFileResponse' '400': description: 'Error: FilesBadRequest' content: application/json: schema: type: object required: - error - message properties: error: type: string description: Error code in SCREAMING_SNAKE_CASE message: type: string description: Human-readable error message '404': description: 'Error: FileNotFound' content: application/json: schema: type: object required: - error - message properties: error: type: string description: Error code in SCREAMING_SNAKE_CASE message: type: string description: Human-readable error message '500': description: 'Error: InternalError' content: application/json: schema: type: object required: - error - message properties: error: type: string description: Error code in SCREAMING_SNAKE_CASE message: type: string description: Human-readable error message /v1/vms/{vm_id}/fork: post: tags: - VM description: Fork VM operationId: fork_vm parameters: - name: vm_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/ForkVmRequest' required: true responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/ForkVmResponse' '403': description: 'Error: AccessDenied' content: application/json: schema: type: object required: - error - message properties: error: type: string description: Error code in SCREAMING_SNAKE_CASE message: type: string description: Human-readable error message '500': description: 'Error: FailedToPreRegister' content: application/json: schema: type: object required: - error - message properties: error: type: string description: Error code in SCREAMING_SNAKE_CASE message: type: string description: Human-readable error message /v1/vms/{vm_id}/kill: post: tags: - VM description: Kill VM operationId: kill_vm parameters: - name: vm_id in: path description: The ID of the VM to kill required: true schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/KillVmResponse' '500': description: 'Possible errors: InternalError, NotVmOwner' content: application/json: schema: type: object required: - error - message properties: error: type: string description: Error code in SCREAMING_SNAKE_CASE message: type: string description: Human-readable error message /v1/vms/{vm_id}/optimize: post: tags: - VM description: Suspends a VM and reallocates storage for more efficient forking. operationId: optimize_vm parameters: - name: vm_id in: path description: The ID of the VM to optimize required: true schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/OptimizeVmResponse' '500': description: 'Error: InternalError' content: application/json: schema: type: object required: - error - message properties: error: type: string description: Error code in SCREAMING_SNAKE_CASE message: type: string description: Human-readable error message /v1/vms/{vm_id}/snapshot: post: tags: - VM description: Create a snapshot of a VM. The snapshot is stored in a special snapshots folder and cannot be booted directly, but can be used to create new VMs. operationId: snapshot_vm parameters: - name: vm_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/SnapshotVmRequest' required: true responses: '200': description: Created snapshot content: application/json: schema: $ref: '#/components/schemas/SnapshotVmResponse' /v1/vms/{vm_id}/start: post: tags: - VM description: Start VM operationId: start_vm parameters: - name: vm_id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/StartVmRequest' required: true responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/StartedVmResponse' /v1/vms/{vm_id}/stats/stream: get: tags: - VM description: "Stream live VM stats (memory + CPU) as NDJSON. Sourced from inside the guest \u2014 untrusted, do not\ \ use for billing." operationId: stats_stream parameters: - name: vm_id in: path description: The ID of the VM to stream stats for required: true schema: type: string - name: interval_ms in: query description: Sample interval in ms (default 1000, clamped 100-10000) required: false schema: type: integer format: int64 minimum: 0 responses: {} /v1/vms/{vm_id}/stop: post: tags: - VM description: Stop VM operationId: stop_vm parameters: - name: vm_id in: path description: The ID of the VM to stop required: true schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/StopVmResponse' '400': description: 'Error: VmNotRunning' content: application/json: schema: type: object required: - error - message properties: error: type: string description: Error code in SCREAMING_SNAKE_CASE message: type: string description: Human-readable error message '500': description: 'Error: InternalError' content: application/json: schema: type: object required: - error - message properties: error: type: string description: Error code in SCREAMING_SNAKE_CASE message: type: string description: Human-readable error message /v1/vms/{vm_id}/suspend: post: tags: - VM description: Suspend VM operationId: suspend_vm parameters: - name: vm_id in: path description: The ID of the VM to suspend required: true schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/SuspendVmResponse' '500': description: 'Possible errors: InternalError, PauseFailed, SnapshotFailed, NetworkInterfaceLookupFailed, SuspendFailedAndStopped, SuspendFailedAndStopFailed' content: application/json: schema: type: object required: - error - message properties: error: type: string description: Error code in SCREAMING_SNAKE_CASE message: type: string description: Human-readable error message /v1/vms/{vm_id}/systemd/restart: post: tags: - VM description: Restart multiple systemd services operationId: batch_restart_services parameters: - name: vm_id in: path description: The ID of the VM required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/BatchServiceRequest' required: true responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/BatchServiceResponse' '500': description: 'Error: Internal' content: application/json: schema: type: object required: - error - message properties: error: type: string description: Error code in SCREAMING_SNAKE_CASE message: type: string description: Human-readable error message /v1/vms/{vm_id}/systemd/services: get: tags: - VM description: List all systemd services for a VM operationId: list_services parameters: - name: vm_id in: path description: The ID of the VM required: true schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/SystemdListServicesResponse' '500': description: 'Error: Internal' content: application/json: schema: type: object required: - error - message properties: error: type: string description: Error code in SCREAMING_SNAKE_CASE message: type: string description: Human-readable error message post: tags: - VM description: Create a new systemd service operationId: create_service parameters: - name: vm_id in: path description: The ID of the VM required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/SystemdUnitSpec' required: true responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/SystemdCreateServiceResponse' '409': description: 'Error: ServiceAlreadyExists' content: application/json: schema: type: object required: - error - message properties: error: type: string description: Error code in SCREAMING_SNAKE_CASE message: type: string description: Human-readable error message '500': description: 'Error: Internal' content: application/json: schema: type: object required: - error - message properties: error: type: string description: Error code in SCREAMING_SNAKE_CASE message: type: string description: Human-readable error message /v1/vms/{vm_id}/systemd/services/{service_id}: delete: tags: - VM description: Delete a systemd service operationId: delete_service parameters: - name: vm_id in: path description: The ID of the VM required: true schema: type: string - name: service_id in: path description: The ID of the service required: true schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/SystemdDeleteServiceResponse' '404': description: 'Error: ServiceNotFound' content: application/json: schema: type: object required: - error - message properties: error: type: string description: Error code in SCREAMING_SNAKE_CASE message: type: string description: Human-readable error message '500': description: 'Error: Internal' content: application/json: schema: type: object required: - error - message properties: error: type: string description: Error code in SCREAMING_SNAKE_CASE message: type: string description: Human-readable error message /v1/vms/{vm_id}/systemd/services/{service_id}/logs: get: tags: - VM description: Get logs for a systemd service operationId: get_service_logs parameters: - name: vm_id in: path description: The ID of the VM required: true schema: type: string - name: service_id in: path description: The ID of the service required: true schema: type: string - name: lines in: query description: Number of log lines to return required: false schema: type: integer format: int32 minimum: 0 - name: since in: query description: Only show logs since this timestamp required: false schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/JournaldLogsResponse' '404': description: 'Error: ServiceNotFound' content: application/json: schema: type: object required: - error - message properties: error: type: string description: Error code in SCREAMING_SNAKE_CASE message: type: string description: Human-readable error message '500': description: 'Error: Internal' content: application/json: schema: type: object required: - error - message properties: error: type: string description: Error code in SCREAMING_SNAKE_CASE message: type: string description: Human-readable error message /v1/vms/{vm_id}/systemd/services/{service_id}/status: get: tags: - VM description: Get status of a systemd service operationId: get_service_status parameters: - name: vm_id in: path description: The ID of the VM required: true schema: type: string - name: service_id in: path description: The ID of the service required: true schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/SystemdServiceStatus' '404': description: 'Error: ServiceNotFound' content: application/json: schema: type: object required: - error - message properties: error: type: string description: Error code in SCREAMING_SNAKE_CASE message: type: string description: Human-readable error message '500': description: 'Error: Internal' content: application/json: schema: type: object required: - error - message properties: error: type: string description: Error code in SCREAMING_SNAKE_CASE message: type: string description: Human-readable error message /v1/vms/{vm_id}/systemd/start: post: tags: - VM description: Start multiple systemd services operationId: batch_start_services parameters: - name: vm_id in: path description: The ID of the VM required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/BatchServiceRequest' required: true responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/BatchServiceResponse' '500': description: 'Error: Internal' content: application/json: schema: type: object required: - error - message properties: error: type: string description: Error code in SCREAMING_SNAKE_CASE message: type: string description: Human-readable error message /v1/vms/{vm_id}/systemd/stop: post: tags: - VM description: Stop multiple systemd services operationId: batch_stop_services parameters: - name: vm_id in: path description: The ID of the VM required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/BatchServiceRequest' required: true responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/BatchServiceResponse' '500': description: 'Error: Internal' content: application/json: schema: type: object required: - error - message properties: error: type: string description: Error code in SCREAMING_SNAKE_CASE message: type: string description: Human-readable error message /v1/vms/{vm_id}/terminals: get: tags: - VM description: List all terminal sessions for a VM operationId: list_terminals parameters: - name: vm_id in: path description: The ID of the VM required: true schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/TerminalListResponse' '500': description: 'Error: InternalError' content: application/json: schema: type: object required: - error - message properties: error: type: string description: Error code in SCREAMING_SNAKE_CASE message: type: string description: Human-readable error message /v1/vms/{vm_id}/terminals/{terminal_id}/logs: get: tags: - VM description: Get terminal logs as plain text array operationId: get_terminal_logs parameters: - name: vm_id in: path description: The ID of the VM required: true schema: type: string - name: terminal_id in: path description: The ID of the terminal session required: true schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/TerminalLogsArrayResponse' '500': description: 'Error: InternalError' content: application/json: schema: type: object required: - error - message properties: error: type: string description: Error code in SCREAMING_SNAKE_CASE message: type: string description: Human-readable error message /v1/vms/{vm_id}/terminals/{terminal_id}/xterm-256color: get: tags: - VM description: Get terminal output with xterm formatting operationId: get_terminal_xterm parameters: - name: vm_id in: path description: The ID of the VM required: true schema: type: string - name: terminal_id in: path description: The ID of the terminal session required: true schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/TerminalLogsResponse' '500': description: 'Error: InternalError' content: application/json: schema: type: object required: - error - message properties: error: type: string description: Error code in SCREAMING_SNAKE_CASE message: type: string description: Human-readable error message /v1/vms/{vm_id}/watch-files: post: tags: - VM description: Watch VM Files operationId: watch_files parameters: - name: vm_id in: path description: The ID of the VM to watch files for required: true schema: type: string responses: {} components: securitySchemes: bearerAuth: type: http scheme: bearer schemas: TerminalListResponse: type: object required: - terminals properties: terminals: type: array items: $ref: '#/components/schemas/TerminalSession' FileSystemResponse: oneOf: - type: object required: - content properties: content: type: string encoding: $ref: '#/components/schemas/FileEncoding' - type: object required: - files properties: files: type: array items: $ref: '#/components/schemas/FileInfo' VmDeleteEvent: type: string enum: - OnStop - OnSuspend SystemdServiceListItem: type: object required: - name properties: name: type: string VmMetricsInfo: type: object required: - wallTimeSeconds - billingDay - isActiveToday properties: wallTimeSeconds: type: integer format: int64 minimum: 0 billingDay: type: string isActiveToday: type: boolean VmDomainConfig: type: object description: Domain configuration for a VM, specifying the domain and optional target port required: - domain properties: domain: type: string description: The domain name to map to the VM example: myapp.example.com vmPort: type: - integer - 'null' format: int32 description: The port on the VM to route traffic to. Defaults to 443 if not specified. example: 3000 SystemdDeleteServiceResponse: type: object required: - success - message properties: success: type: boolean message: type: string GitRepositorySpec: type: object required: - repo - path properties: repo: type: string description: url or id of the git repository path: type: string description: path to place the repo on rev: type: - string - 'null' description: optional rev (branch, tag, commit) SystemdCreateServiceResponse: type: object required: - success - message - serviceName properties: success: type: boolean message: type: string serviceName: type: string TerminalLogsArrayResponse: type: object required: - logs properties: logs: type: array items: $ref: '#/components/schemas/LogEntry' SnapshotVmResponse: type: object required: - snapshotId - sourceVmId properties: snapshotId: $ref: '#/components/schemas/SnapshotId' description: The ID of the snapshot sourceVmId: $ref: '#/components/schemas/VmId' description: The ID of the source VM sourceVmInstanceId: oneOf: - type: 'null' - $ref: '#/components/schemas/VmInstanceId' description: The instance ID of the source VM GitUser: type: object properties: name: type: - string - 'null' email: type: - string - 'null' signingkey: type: - string - 'null' RequestId: type: string description: "Branded request identifier \u2014 `ri-<20 lowercase alphanumeric chars>` for newly\nminted IDs. The wrapped\ \ string is otherwise opaque, so legacy UUID-formatted\nIDs (from in-flight requests during rollout) round-trip unchanged." SystemdUnitSpec: type: object required: - name - mode - exec properties: name: type: string description: Unique slug; becomes unit name ".service". mode: $ref: '#/components/schemas/SystemdUnitMode' description: '"oneshot" (run and exit) or "service" (long-running/healing).' exec: type: array items: type: string description: Executable to run (can specify multiple commands that run sequentially). env: type: - object - 'null' description: Environment variables. additionalProperties: type: string propertyNames: type: string user: type: - string - 'null' description: Linux user to run the service as. group: type: - string - 'null' description: Linux group to run the service in. workdir: type: - string - 'null' description: Working directory. after: type: - array - 'null' items: type: string description: 'Establishes an ordering dependency. The current unit will start only after the units listed in After= have started. This is useful for ensuring that certain services are up and running before the current service begins its operation.' requires: type: - array - 'null' items: type: string description: 'Establishes a strong dependency. If the required unit fails to start or stops unexpectedly, the current unit will also be stopped. This ensures that a service critical to the functioning of the current unit is running and stable. Units listed in Requires= are activated along with the current unit. If the required unit is not active, systemd will attempt to start it. This directive signifies a tight coupling between services, where the current service cannot function without the required service.' onFailure: type: - array - 'null' items: type: string description: 'Units to activate when this unit enters a failed state. This is useful for triggering recovery actions, notifications, or cleanup services when the current service fails.' wantedBy: type: - array - 'null' items: type: string description: 'Target used when enabling (default: multi-user.target).' default: multi-user.target enable: type: - boolean - 'null' description: 'Whether to enable this service (calls `systemctl enable `). When enabled, the service will start automatically at boot.' default: true timeoutSec: type: - integer - 'null' format: int64 description: Overall start/stop timeout. minimum: 0 deleteAfterSuccess: type: - boolean - 'null' description: 'For oneshot: remove unit on success.' default: false remainAfterExit: type: - boolean - 'null' description: 'For oneshot: remain active after exit (default: true). When false, the service can be started again even if it already ran.' default: true readySignal: type: - boolean - 'null' description: Use sd_notify; maps to Type=notify. default: false watchdogSec: type: - integer - 'null' format: int64 description: Enable systemd watchdog (seconds). minimum: 0 restartPolicy: oneOf: - type: 'null' - $ref: '#/components/schemas/SystemdRestartPolicy' description: Restart semantics (service mode). VmTemplate: type: object properties: snapshotId: oneOf: - type: 'null' - $ref: '#/components/schemas/SnapshotId' description: 'Optional snapshot ID to create a VM from. If provided, the new VM will be created from the specified snapshot. Cannot be used together with fork_vm_id or docker_image.' baseImage: oneOf: - type: 'null' - $ref: '#/components/schemas/BaseImageSpec' description: 'Optional inline Dockerfile content to build and import a custom image from. Cannot be used together with snapshot_id. The image is built inside a temporary sandbox VM (no build context is used).' rootfsSizeGb: type: - integer - 'null' format: int64 minimum: 0 memSizeGb: type: - integer - 'null' format: int64 minimum: 0 vcpuCount: type: - integer - 'null' format: int32 minimum: 0 workdir: type: - string - 'null' description: Optional working directory for the VM. If not provided, the default to '/' idleTimeoutSeconds: type: - integer - 'null' format: int64 description: 'Idle timeout in seconds. If set, the VM will be automatically suspended after this many seconds of no network activity. Defaults to 300 seconds (5 minutes) if not provided or the last used timeout for the forked VM.' minimum: 0 waitForReadySignal: type: - boolean - 'null' readySignalTimeoutSeconds: type: - integer - 'null' format: int64 minimum: 0 persistence: oneOf: - type: 'null' - $ref: '#/components/schemas/VmPersistence' description: 'Persistence strategy for the VM. If not provided, defaults to ''sticky'' with priority 5.' ports: type: - array - 'null' items: type: object required: - port - targetPort properties: port: type: integer format: int32 minimum: 0 targetPort: type: integer format: int32 minimum: 0 description: 'Optional list of ports to expose externally. If not provided, port 3000 will be exposed on port 443 by default. Pass an empty array to disable external ports. Only ports 8081 and 443 can be configured externally for now. Any target port is allowed.' example: - port: 443 targetPort: 3000 systemd: oneOf: - type: 'null' - $ref: '#/components/schemas/SystemdConfig' users: type: - array - 'null' items: $ref: '#/components/schemas/LinuxUserSpec' description: Linux users to create on VM startup groups: type: - array - 'null' items: $ref: '#/components/schemas/LinuxGroupSpec' description: Linux groups to create on VM startup additionalFiles: type: - object - 'null' additionalProperties: $ref: '#/components/schemas/FreestyleFile' propertyNames: type: string gitRepos: type: - array - 'null' items: $ref: '#/components/schemas/GitRepositorySpec' deprecated: true git: oneOf: - type: 'null' - $ref: '#/components/schemas/GitOptions' description: Repositories to clone and git options for the VM. discriminator: type: - string - 'null' description: Optional discriminator to differentiate snapshots with otherwise identical configurations aptDeps: type: - array - 'null' items: type: string description: 'Optional list of apt packages to install when setting up the VM. These packages will be installed using `apt-get install` on VM startup.' example: - git - curl - vim skipCache: type: - boolean - 'null' description: 'When true, bypasses the snapshot cache and always creates a new snapshot. The new snapshot still stores the template hash, so it becomes the updated cache entry for future requests that do not set skip_cache.' WriteFileRequest: type: object required: - content properties: content: type: string encoding: $ref: '#/components/schemas/FileEncoding' KillVmResponse: type: object required: - id properties: id: $ref: '#/components/schemas/VmId' ForkedVmResponse: type: object required: - id - domains properties: id: type: string domains: type: array items: type: string consoleUrl: type: - string - 'null' SystemdUnitSpecPatch: type: object required: - name properties: name: type: string description: Unique slug; becomes unit name ".service". mode: oneOf: - type: 'null' - $ref: '#/components/schemas/SystemdUnitMode' description: '"oneshot" (run and exit) or "service" (long-running/healing).' exec: type: - array - 'null' items: type: string description: Executable to run (can specify multiple commands that run sequentially). env: type: - object - 'null' description: Environment variables. additionalProperties: type: string propertyNames: type: string user: type: - string - 'null' description: Linux user to run the service as. group: type: - string - 'null' description: Linux group to run the service in. workdir: type: - string - 'null' description: Working directory. after: type: - array - 'null' items: type: string description: 'Establishes an ordering dependency. The current unit will start only after the units listed in After= have started. This is useful for ensuring that certain services are up and running before the current service begins its operation.' requires: type: - array - 'null' items: type: string description: 'Establishes a strong dependency. If the required unit fails to start or stops unexpectedly, the current unit will also be stopped. This ensures that a service critical to the functioning of the current unit is running and stable. Units listed in Requires= are activated along with the current unit. If the required unit is not active, systemd will attempt to start it. This directive signifies a tight coupling between services, where the current service cannot function without the required service.' onFailure: type: - array - 'null' items: type: string description: 'Units to activate when this unit enters a failed state. This is useful for triggering recovery actions, notifications, or cleanup services when the current service fails.' wantedBy: type: - array - 'null' items: type: string description: 'Target used when enabling (default: multi-user.target).' enable: type: - boolean - 'null' description: 'Whether to enable this service (calls `systemctl enable `). When enabled, the service will start automatically at boot.' timeoutSec: type: - integer - 'null' format: int64 description: Overall start/stop timeout. minimum: 0 deleteAfterSuccess: type: - boolean - 'null' description: 'For oneshot: remove unit on success.' readySignal: type: - boolean - 'null' description: Use sd_notify; maps to Type=notify. watchdogSec: type: - integer - 'null' format: int64 description: Enable systemd watchdog (seconds). minimum: 0 restartPolicy: oneOf: - type: 'null' - $ref: '#/components/schemas/SystemdRestartPolicy' description: Restart semantics (service mode). CreateVmRequest: type: object properties: spec: oneOf: - type: 'null' - $ref: '#/components/schemas/VmSpec' description: "Top-level recursive spec for the VM. When set, all other top-level\nfields (including `template`)\ \ must be omitted \u2014 use the fields inside\n`spec` instead. Supports arbitrary-depth snapshot layering through\n\ `spec.snapshot`, materialized server-side into a chain of cached\nsnapshots." name: type: - string - 'null' description: "Optional name/label for the VM. VM-instance metadata \u2014 not part of the\ncacheable spec, so it\ \ lives at the top level alongside `spec`." idleTimeoutSeconds: type: - integer - 'null' format: int64 description: 'Idle timeout in seconds. If set, the VM will be automatically suspended after this many seconds of no network activity.' ports: type: - array - 'null' items: $ref: '#/components/schemas/PortMapping' description: 'Optional list of ports to expose externally. If not provided, port 3000 will be exposed on port 443 by default. Pass an empty array to disable external ports. Only ports 8081 and 443 can be configured externally for now. Any target port is allowed.' example: - port: 443 targetPort: 3000 waitForReadySignal: type: - boolean - 'null' description: 'Whether the api request should wait for the VM to be ready before returning. By default, the VM is considered ready when the serial console is ready for login.' default: true example: true readySignalTimeoutSeconds: type: - integer - 'null' format: int64 description: 'How long to wait for the ready signal before timing out. Defaults to 120 seconds if not provided.' workdir: type: - string - 'null' description: 'Optional working directory for the VM. File system and shell commands will be executed in this directory. **Deprecated: use `spec.snapshot.workdir` instead.**' deprecated: true persistence: oneOf: - type: 'null' - $ref: '#/components/schemas/VmPersistence' description: 'Persistence strategy for the VM instance. If not provided, defaults to ''sticky'' with priority 5.' systemd: oneOf: - type: 'null' - $ref: '#/components/schemas/SystemdConfig' description: Optional systemd configuration for services to run in the VM. users: type: - array - 'null' items: $ref: '#/components/schemas/LinuxUserSpec' groups: type: - array - 'null' items: $ref: '#/components/schemas/LinuxGroupSpec' additionalFiles: type: - object - 'null' additionalProperties: $ref: '#/components/schemas/FreestyleFile' propertyNames: type: string snapshotId: oneOf: - type: 'null' - $ref: '#/components/schemas/SnapshotId' description: 'ID of a previously-created snapshot to boot directly as the VM''s base. This is distinct from `spec.snapshot.snapshotId`, which materializes a new cacheable snapshot layer based on that snapshot before creating the VM.' template: oneOf: - type: 'null' - $ref: '#/components/schemas/VmTemplate' description: 'Legacy single-layer VM template. Subsumed by the recursive `spec.snapshot` chain, which supports multiple cacheable layers. **Deprecated: use `spec.snapshot` instead.**' gitRepos: type: - array - 'null' items: $ref: '#/components/schemas/GitRepositorySpec' description: 'Legacy list of git repositories to clone into the VM at startup. **Deprecated: use `spec.git.repos` instead.**' deprecated: true git: oneOf: - type: 'null' - $ref: '#/components/schemas/GitOptions' description: Git configuration for the VM, including user settings and repositories to clone into the VM at startup. recreate: type: - boolean - 'null' description: 'If true, the VM can be recreated if it is deleted. The VM will keep the same ID and be recreated with the same configuration when something tries to start it.' default: false aptDeps: type: - array - 'null' items: type: string description: 'Optional list of apt packages to install when setting up the VM. These packages will be installed using `apt-get install` on VM startup.' example: - git - curl - vim domains: type: - array - 'null' items: $ref: '#/components/schemas/VmDomainConfig' description: 'Optional list of custom domains to map to this VM. Each domain can optionally specify a vm port. If vm_port is not specified, defaults to 443. Domains must be verified and owned by the account before they can be mapped.' example: - domain: myapp.example.com vmPort: 3000 activityThresholdBytes: type: - integer - 'null' format: int64 description: 'Minimum bytes of network traffic per check interval to count as real activity for the idle timer.' minimum: 0 dockerCredentials: oneOf: - type: 'null' - $ref: '#/components/schemas/DockerCredentials' description: 'Optional Docker registry credentials required when using a private image in the spec''s base image.' SnapshotSpec: type: object description: "A cacheable snapshot layer. Recursive via `snapshot` \u2014 an optional inner\nlayer that is materialized\ \ into a snapshot before this layer builds. The\nresulting `snapshot_id` becomes the base for this layer. `snapshot`,\n\ `snapshot_id`, and `base_image` are mutually exclusive." properties: snapshot: oneOf: - type: 'null' - $ref: '#/components/schemas/SnapshotSpec' description: 'Inner cacheable layer. Materialized first, its resulting snapshot_id becomes the base for this layer.' snapshotId: oneOf: - type: 'null' - $ref: '#/components/schemas/SnapshotId' description: 'Pre-existing snapshot to base this layer on. Mutually exclusive with `snapshot` and `base_image`.' baseImage: oneOf: - type: 'null' - $ref: '#/components/schemas/BaseImageSpec' description: 'Inline Dockerfile content to build and import a custom base image for this layer. Mutually exclusive with `snapshot` and `snapshot_id`.' rootfsSizeGb: type: - integer - 'null' format: int64 minimum: 0 memSizeGb: type: - integer - 'null' format: int64 minimum: 0 vcpuCount: type: - integer - 'null' format: int32 minimum: 0 workdir: type: - string - 'null' description: Optional working directory for the VM. Defaults to '/'. idleTimeoutSeconds: type: - integer - 'null' format: int64 description: 'Idle timeout in seconds. If set, the VM will be automatically suspended after this many seconds of no network activity.' minimum: 0 waitForReadySignal: type: - boolean - 'null' readySignalTimeoutSeconds: type: - integer - 'null' format: int64 minimum: 0 ports: type: - array - 'null' items: $ref: '#/components/schemas/PortConfig' description: Optional list of ports to expose externally. systemd: oneOf: - type: 'null' - $ref: '#/components/schemas/SystemdConfig' users: type: - array - 'null' items: $ref: '#/components/schemas/LinuxUserSpec' description: Linux users to create on VM startup. groups: type: - array - 'null' items: $ref: '#/components/schemas/LinuxGroupSpec' description: Linux groups to create on VM startup. additionalFiles: type: - object - 'null' additionalProperties: $ref: '#/components/schemas/FreestyleFile' propertyNames: type: string git: oneOf: - type: 'null' - $ref: '#/components/schemas/GitOptions' description: Repositories to clone and git options for the VM. aptDeps: type: - array - 'null' items: type: string description: apt packages to install on VM startup. example: - git - curl - vim discriminator: type: - string - 'null' description: 'Optional discriminator to differentiate snapshots with otherwise identical configurations.' skipCache: type: - boolean - 'null' description: 'When true, bypasses the snapshot cache and always creates a new snapshot. The new snapshot still stores the template hash, so it becomes the updated cache entry for future requests that do not set skip_cache.' BatchServiceResponse: type: object required: - results properties: results: type: array items: $ref: '#/components/schemas/BatchServiceOperationResult' BuildId: type: string description: Branded build ID in the format `bld-<20 lowercase alphanumeric chars>`. LinuxGroupSpec: type: object required: - name properties: name: type: string description: Unique group name gid: type: - integer - 'null' format: int32 description: Optional fixed GID; if None, allocate minimum: 0 system: type: - boolean - 'null' description: System group (allocator uses system range) default: false GitOptions: type: object required: - config properties: config: $ref: '#/components/schemas/GitConfig' repos: type: - array - 'null' items: $ref: '#/components/schemas/GitRepositorySpec' BuildRecord: type: object description: "One row in the `builds` table \u2014 a long-running snapshot creation task.\n\nBuilds do not form trees.\ \ Sub-work (Docker pulls, systemd installs,\nper-layer captures of a multi-layer spec) is captured via append-only\n\ `build_phases` rows on this build, not via child builds. Builds related\nto one user request (e.g. retries that produce\ \ a fresh build for the\nsame template) share a `request_id` \u2014 that's the only correlation\nmechanism between\ \ builds.\n\nBuild outputs are recorded on the artifact, not the build:\n`vm_snapshots.build_id` is the only link." required: - buildId - accountId - state - plannedPhases - startedAt - updatedAt properties: buildId: $ref: '#/components/schemas/BuildId' accountId: $ref: '#/components/schemas/AccountId' requestId: oneOf: - type: 'null' - $ref: '#/components/schemas/RequestId' state: $ref: '#/components/schemas/BuildState' templateHash: type: - string - 'null' description: "Inputs that identify the unit of work. Historical / informational\nonly \u2014 not used for dedupe\ \ in Phase 1." failureReason: type: - string - 'null' description: Set when state is `Failed` or `RolledBack`. plannedPhases: type: array items: type: string description: 'Phase names this build plans to emit, in order, populated once at build open and never updated. Diffing against `build_phases.name` yields "what''s still pending" without polling for state changes.' startedAt: type: string format: date-time finishedAt: type: - string - 'null' format: date-time updatedAt: type: string format: date-time UpdateSnapshotRequest: type: object properties: name: type: - string - 'null' FileInfo: type: object required: - name - kind properties: name: type: string kind: $ref: '#/components/schemas/FileKind' StartVmRequest: type: object properties: idleTimeoutSeconds: type: - integer - 'null' format: int64 readySignalTimeoutSeconds: type: - integer - 'null' format: int64 waitForReadySignal: type: - boolean - 'null' activityThresholdBytes: type: - integer - 'null' format: int64 minimum: 0 PortMapping: type: object required: - port - targetPort properties: port: type: integer format: int32 targetPort: type: integer format: int32 SystemdListServicesResponse: type: object required: - services properties: services: type: array items: $ref: '#/components/schemas/SystemdServiceListItem' CreateSnapshotResponse: type: object required: - snapshotId properties: snapshotId: $ref: '#/components/schemas/SnapshotId' LogEntry: type: object required: - line properties: line: type: string timestamp: type: - string - 'null' SystemdRestartPolicyKind: type: string enum: - 'no' - on-failure - always - on-abnormal FileEncoding: type: string description: File content encoding enum: - utf8 - base64 WriteFileResponse: oneOf: - type: object ListVmsResponse: type: object required: - vms - totalCount - runningCount - startingCount - suspendedCount - stoppedCount properties: vms: type: array items: $ref: '#/components/schemas/VmInfo' totalCount: type: integer minimum: 0 buildingCount: type: integer minimum: 0 runningCount: type: integer minimum: 0 startingCount: type: integer minimum: 0 suspendingCount: type: integer minimum: 0 suspendedCount: type: integer minimum: 0 stoppedCount: type: integer minimum: 0 lostCount: type: integer minimum: 0 userId: type: - string - 'null' CreateSnapshotRequest: type: object properties: name: type: - string - 'null' spec: oneOf: - type: 'null' - $ref: '#/components/schemas/SnapshotSpec' description: 'Recursive snapshot spec. When set, `template` must be omitted. `spec.snapshot` materializes into a chain of cached snapshots before the outermost layer is built.' template: oneOf: - type: 'null' - $ref: '#/components/schemas/VmTemplate' description: 'Legacy single-layer snapshot template. Subsumed by the recursive `spec` chain, which supports multiple cacheable layers. **Deprecated: use `spec` instead.**' persistence: oneOf: - type: 'null' - $ref: '#/components/schemas/SnapshotPersistence' description: Defaults to persistent. If set to sticky we will intelligently clean it up as your account reaches its limits. dockerCredentials: oneOf: - type: 'null' - $ref: '#/components/schemas/DockerCredentials' description: 'Optional Docker registry credentials required when using a private image in `spec.baseImage`.' BatchServiceOperationResult: type: object required: - serviceId - success - message properties: serviceId: type: string success: type: boolean message: type: string ExecAwaitVmResponse: type: object properties: stdout: type: - string - 'null' stderr: type: - string - 'null' statusCode: type: - integer - 'null' format: int32 TerminalSession: type: object required: - name - status properties: name: type: string status: type: string created: type: - string - 'null' VmInfo: type: object required: - id - state properties: id: $ref: '#/components/schemas/VmId' name: type: - string - 'null' state: $ref: '#/components/schemas/VMState' metrics: oneOf: - type: 'null' - $ref: '#/components/schemas/VmMetricsInfo' createdAt: type: - string - 'null' format: date-time lastNetworkActivity: type: - string - 'null' format: date-time cpuTimeSeconds: type: - number - 'null' format: double persistence: oneOf: - type: 'null' - $ref: '#/components/schemas/VmPersistence' snapshotId: oneOf: - type: 'null' - $ref: '#/components/schemas/SnapshotId' description: The snapshot this VM was created from, if any. deleted: type: boolean createdDeclaratively: type: boolean buildId: oneOf: - type: 'null' - $ref: '#/components/schemas/BuildId' description: Build that produced this VM, if it was created via a build saga. VmInstanceId: type: string JournaldLogsResponse: type: object required: - logs properties: logs: type: array items: $ref: '#/components/schemas/JournaldLogItem' CreateVmResponse: type: object required: - id - domains properties: id: type: string domains: type: array items: type: string consoleUrl: type: - string - 'null' description: '**Deprecated:** this field is scheduled for removal and is no longer populated. The default `{vm_id}.style.dev` hostname still resolves via firecracker''s host registry; consumers should construct it themselves if needed.' deprecated: true snapshotId: oneOf: - type: 'null' - $ref: '#/components/schemas/SnapshotId' description: Debugging tool, if you believe its base is incorrect you can go off it. JournaldLogItem: type: object required: - message - timestamp properties: message: type: string timestamp: type: string priority: type: - string - 'null' unit: type: - string - 'null' ResizeVmRequest: type: object properties: rootfsSizeGb: type: - integer - 'null' format: int64 minimum: 0 memSizeGb: type: - integer - 'null' format: int32 minimum: 0 vcpuCount: type: - integer - 'null' format: int32 minimum: 0 SystemdUnitMode: type: string enum: - oneshot - service VmPersistence: oneOf: - type: object description: 'When your storage quota is reached, the least recently used VMs will be deleted.' required: - type properties: priority: type: - integer - 'null' format: int32 description: 'Priority for eviction when storage quota is reached. Higher values mean the VM is less likely to be evicted. Range is 0-10, default is 5.' default: 5 maximum: 10 minimum: 0 type: type: string enum: - sticky - type: object description: 'The VM will be deleted after the idle timeout. It''s not guaranteed that the VM will be deleted immediately.' required: - type properties: deleteEvent: oneOf: - type: 'null' - $ref: '#/components/schemas/VmDeleteEvent' type: type: string enum: - ephemeral - type: object required: - type properties: type: type: string enum: - persistent DockerCredentials: type: object required: - registry - username - password properties: registry: type: string description: Docker registry URL (e.g., "ghcr.io", "docker.io") username: type: string description: Username for the registry password: type: string description: Password or token for the registry BatchServiceRequest: type: object required: - services properties: services: type: array items: $ref: '#/components/schemas/ServiceIdItem' BaseImageSpec: type: object description: 'Specifies a Docker base image via inline Dockerfile content. Used as an alternative to `docker_image` when you want to build a custom image on the fly without a pre-published registry image. No build context is supported yet.' required: - dockerfileContent properties: dockerfileContent: type: string description: The text content of a Dockerfile (e.g., `"FROM debian:trixie-slim"`). DeleteSnapshotResponses: oneOf: - type: object required: - snapshot_id properties: snapshot_id: $ref: '#/components/schemas/SnapshotId' StopVmResponse: type: object required: - vmId - vmInstanceId properties: vmId: $ref: '#/components/schemas/VmId' vmInstanceId: $ref: '#/components/schemas/VmInstanceId' SystemdRestartPolicy: type: object required: - policy properties: policy: $ref: '#/components/schemas/SystemdRestartPolicyKind' description: '"no" | "on-failure" | "always" | "on-abnormal"' restartSec: type: - integer - 'null' format: int64 minimum: 0 startLimitBurst: type: - integer - 'null' format: int32 minimum: 0 startLimitIntervalSec: type: - integer - 'null' format: int64 minimum: 0 BuildState: type: string description: Lifecycle state of a build row. enum: - pending - running - succeeded - failed SystemdServiceStatus: type: object required: - name - activeState - subState - loadState - description properties: name: type: string activeState: type: string subState: type: string loadState: type: string description: type: string SystemdConfig: type: object properties: services: type: - array - 'null' items: $ref: '#/components/schemas/SystemdUnitSpec' patchedServices: type: - array - 'null' items: $ref: '#/components/schemas/SystemdUnitSpecPatch' BuildPhase: type: object description: "One phase the build passed through. Append-only \u2014 rows are never\nupdated. The implicit `finished_at`\ \ of any phase is the next phase\nrow's `started_at`, or `builds.finished_at` for the last phase." required: - phaseId - buildId - name - startedAt properties: phaseId: $ref: '#/components/schemas/BuildPhaseId' buildId: $ref: '#/components/schemas/BuildId' name: type: string snapshotId: oneOf: - type: 'null' - $ref: '#/components/schemas/SnapshotId' description: 'Snapshot this phase is about, when applicable: the cached snapshot a "(cached)" phase references, or the snapshot a build phase produces. `None` for phases that don''t map to a single snapshot (e.g. variant resize prep that hasn''t been pre-allocated yet).' startedAt: type: string format: date-time SuspendVmResponse: type: object required: - id - vmInstanceId - snapshotLayerId properties: id: type: string description: The ID of the VM that was suspended vmInstanceId: $ref: '#/components/schemas/VmInstanceId' description: The ID of the VM instance that was suspended snapshotLayerId: $ref: '#/components/schemas/SnapshotLayerId' description: "The ID of the snapshot layer created for this VM \u2014 if a layer was created" VmId: type: string description: "VM ID \u2014 always 20 alphanumeric lowercase characters.\nNew IDs are fully random. Legacy short IDs\ \ are right-padded with '0' on parse." SnapshotLayerId: type: string description: "Branded snapshot layer ID \u2014 always a 16-character alphanumeric lowercase string prefixed with \"\ sl-\"." ListSnapshotsResponse: type: object required: - snapshots - totalCount - buildingCount - readyCount - failedCount - cancelledCount - lostCount - deletedCount properties: snapshots: type: array items: $ref: '#/components/schemas/SnapshotInfo' totalCount: type: integer minimum: 0 buildingCount: type: integer minimum: 0 readyCount: type: integer minimum: 0 failedCount: type: integer minimum: 0 cancelledCount: type: integer minimum: 0 lostCount: type: integer minimum: 0 deletedCount: type: integer minimum: 0 ResizeVmResponse: type: object WaitVmResponse: type: object required: - id - exitStatus properties: id: $ref: '#/components/schemas/VmId' exitStatus: type: string TerminalLogsResponse: type: object required: - output properties: output: type: string SnapshotStateTag: type: string description: "Lifecycle state of a snapshot row.\n\n `Building` \u2014 saga in flight, late-bound fields NULL.\n \ \ `Ready` \u2014 saga finalized cleanly; usable as a base.\n `Failed` \u2014 bytes complete but VM was broken\ \ at capture; bookable\n for debugging.\n `Cancelled` \u2014 saga rolled back / dependency failed;\ \ no bytes.\n `Lost` \u2014 reaper terminated a `building` row after a node\n crash; bytes absent\ \ or partial." enum: - building - ready - failed - cancelled - lost UpdateSnapshotResponses: oneOf: - type: object required: - snapshot_id properties: snapshot_id: $ref: '#/components/schemas/SnapshotId' name: type: - string - 'null' SnapshotInfo: type: object required: - snapshotId - state - createdAt - failed - cancelled - lost - deleted - snapshotPersistence properties: snapshotId: $ref: '#/components/schemas/SnapshotId' description: The ID of the snapshot state: $ref: '#/components/schemas/SnapshotStateTag' description: 'Lifecycle state. `building` rows are in flight and may have late-bound fields (sourceVmId, etc) unset.' sourceVmId: oneOf: - type: 'null' - $ref: '#/components/schemas/VmId' description: Source VM the snapshot was captured from. None while state=building. accountId: oneOf: - type: 'null' - $ref: '#/components/schemas/AccountId' description: Account ID of the creator createdAt: type: string description: When the snapshot was created name: type: - string - 'null' description: Optional name for the snapshot failed: type: boolean description: '`state == failed`. Kept for backward compat; prefer reading `state`.' deprecated: true cancelled: type: boolean description: '`state == cancelled`.' lost: type: boolean description: '`state == lost`.' failureReason: type: - string - 'null' deleted: type: boolean description: Whether the snapshot has been soft-deleted snapshotPersistence: $ref: '#/components/schemas/SnapshotPersistence' description: Snapshot persistence strategy buildId: oneOf: - type: 'null' - $ref: '#/components/schemas/BuildId' description: Build that produced this snapshot, if any. templateHash: type: - string - 'null' description: Template hash used for cache lookups. vcpuCount: type: - integer - 'null' format: int32 description: Number of vCPUs configured at snapshot time minimum: 0 memSizeMib: type: - integer - 'null' format: int32 description: Memory size in MiB configured at snapshot time minimum: 0 rootfsSizeMb: type: - integer - 'null' format: int64 description: Root filesystem size in MB minimum: 0 LinuxUserSpec: type: object required: - name properties: name: type: string description: Unique username uid: type: - integer - 'null' format: int32 description: Optional fixed UID; if None, allocate minimum: 0 gecos: type: - string - 'null' description: GECOS field (descriptive string, e.g., full name) groups: type: array items: type: string description: Groups to add user to (all groups use 'm' membership lines) home: type: - string - 'null' description: Home directory path (optional, defaults to /home/{username} for regular users, / for system users) shell: type: - string - 'null' description: Login shell (optional, defaults to /bin/bash for regular users, /usr/sbin/nologin for system users) system: type: - boolean - 'null' description: System user (allocator uses system range) default: false VmSpec: type: object description: 'Top-level spec for `POST /v1/vms`. Identifies a reusable unit via `name` and carries the cacheable `snapshot` chain that produces this VM''s base.' properties: snapshot: oneOf: - type: 'null' - $ref: '#/components/schemas/SnapshotSpec' description: Cacheable snapshot chain. The outermost layer becomes this VM's base. name: type: - string - 'null' description: "Name of the spec itself \u2014 identifies this spec as a reusable unit,\nindependent of any VM instance\ \ created from it. Distinct from the\ntop-level VM `name` in `CreateVmRequest`, which names a VM instance." FileKind: type: string enum: - file - directory ExecAwaitRequest: type: object required: - command properties: command: type: string terminal: type: - string - 'null' timeoutMs: type: - integer - 'null' format: int64 minimum: 0 ServiceIdItem: type: object required: - id properties: id: type: string PortConfig: type: object required: - port - targetPort properties: port: type: integer format: int32 minimum: 0 targetPort: type: integer format: int32 minimum: 0 SnapshotId: type: string description: 'Branded snapshot ID in the format `sc-<20 lowercase alphanumeric chars>`. Unlike `VmShortId`, this is a plain `String` wrapper with no fixed-size array or padding.' BuildPhaseId: type: string description: Branded build phase ID in the format `bph-<20 lowercase alphanumeric chars>`. OptimizeVmResponse: type: object required: - id - message properties: id: type: string message: type: string ListBuildPhasesResponse: type: object description: 'Ordered timeline of phases for a single build. Phases are append-only; consumers wanting the "current phase" pick the last entry. Empty for a build whose top-level saga short-circuited (e.g. fully-cached chain) before any phase was recorded.' required: - phases properties: phases: type: array items: $ref: '#/components/schemas/BuildPhase' AccountId: type: string description: "Account identifier \u2014 either \"system\" or a user UUID" GitConfig: type: object properties: user: oneOf: - type: 'null' - $ref: '#/components/schemas/GitUser' ForkVmRequest: type: object properties: count: type: - integer - 'null' format: int32 minimum: 0 GetVmResponse: type: object required: - id - state properties: id: $ref: '#/components/schemas/VmId' name: type: - string - 'null' vmInstanceId: oneOf: - type: 'null' - $ref: '#/components/schemas/VmInstanceId' description: Unique ID for the current VM run (new ID generated on each start/resume) lastNetworkActivity: type: - string - 'null' format: date-time state: $ref: '#/components/schemas/VMState' cpuTimeSeconds: type: - number - 'null' format: double buildId: oneOf: - type: 'null' - $ref: '#/components/schemas/BuildId' description: Build that produced this VM, if it was created via a build saga. SnapshotPersistence: oneOf: - type: object description: 'When storage quota is reached, the least recently used snapshots will be deleted. Higher priority = less likely to be evicted. Range 0-10, default 5.' required: - type properties: priority: type: - integer - 'null' format: int32 default: 5 maximum: 10 minimum: 0 type: type: string enum: - sticky - type: object description: The snapshot will be stored until manually deleted. required: - type properties: type: type: string enum: - persistent VMState: type: string enum: - building - starting - running - suspending - suspended - stopped - lost ForkVmResponse: type: object required: - vmId - forks properties: vmId: type: string forks: type: array items: $ref: '#/components/schemas/ForkedVmResponse' SnapshotVmRequest: type: object properties: name: type: - string - 'null' description: Optional name/label for the snapshot persistence: oneOf: - type: 'null' - $ref: '#/components/schemas/SnapshotPersistence' description: Persistence strategy for the snapshot. Defaults to Sticky with priority 5. DeleteVmResponses: oneOf: - type: object required: - id properties: id: type: string FreestyleFile: type: object required: - content properties: content: type: string description: The content of the file encoding: type: string description: The encoding of the file. Either **utf-8** or **base64** executable: type: boolean description: Whether the file should be marked executable after being written StartedVmResponse: type: object required: - id - domains properties: id: type: string domains: type: array items: type: string console_url: type: - string - 'null' security: - bearerAuth: []