openapi.yaml

openapi: 3.1.0
info:
  title: Hypeman API
  description: Generic API for managing VM lifecycle using Cloud Hypervisor with OCI-based workloads
  version: 0.2.0
servers:
  - url: http://localhost:8080
    description: Local development server
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
  schemas:
    ErrorDetail:
      type: object
      properties:
        code:
          type: string
          description: Lower-level error code providing more specific detail
          example: invalid_input
        message:
          type: string
          description: Further detail about the error
          example: Image not found
    Error:
      type: object
      required: [code, message]
      properties:
        code:
          type: string
          description: Application-specific error code (machine-readable)
          example: bad_request
        message:
          type: string
          description: Human-readable error description for debugging
          example: "Missing required field: image"
        details:
          type: array
          description: Additional error details (for multiple errors)
          items:
            $ref: "#/components/schemas/ErrorDetail"
        inner_error:
          $ref: "#/components/schemas/ErrorDetail"
    
    InstanceState:
      type: string
      enum: [Created, Initializing, Running, Paused, Shutdown, Stopped, Standby, Unknown]
      description: |
        Instance state:
        - Created: VMM created but not started (Cloud Hypervisor native)
        - Initializing: VM is running while guest init is still in progress
        - Running: Guest program has started and instance is ready
        - Paused: VM is paused (Cloud Hypervisor native)
        - Shutdown: VM shut down but VMM exists (Cloud Hypervisor native)
        - Stopped: No VMM running, no snapshot exists
        - Standby: No VMM running, snapshot exists (can be restored)
        - Unknown: Failed to determine state (see state_error for details)
    
    VolumeMount:
      type: object
      required: [volume_id, mount_path]
      properties:
        volume_id:
          type: string
          description: Volume identifier
          example: vol-abc123
        mount_path:
          type: string
          description: Path where volume is mounted in the guest
          example: /mnt/data
        readonly:
          type: boolean
          description: Whether volume is mounted read-only
          default: false
        overlay:
          type: boolean
          description: Create per-instance overlay for writes (requires readonly=true)
          default: false
        overlay_size:
          type: string
          description: Max overlay size as human-readable string (e.g., "1GB"). Required if overlay=true.
          example: "1GB"
    
    PortMapping:
      type: object
      required: [host_port, guest_port]
      properties:
        host_port:
          type: integer
          description: Port on the host
          example: 8080
        guest_port:
          type: integer
          description: Port in the guest VM
          example: 80
        protocol:
          type: string
          enum: [tcp, udp]
          default: tcp

    Tags:
      type: object
      maxProperties: 50
      description: User-defined key-value tags.
      propertyNames:
        type: string
        minLength: 1
        maxLength: 128
        pattern: ^[A-Za-z0-9 _.:/=+@-]+$
      additionalProperties:
        type: string
        minLength: 0
        maxLength: 256
        pattern: ^[A-Za-z0-9 _.:/=+@-]*$
      example:
        team: backend
        env: staging
    
    CreateInstanceRequest:
      type: object
      required: [name, image]
      properties:
        name:
          type: string
          description: Human-readable name (lowercase letters, digits, and dashes only; cannot start or end with a dash)
          pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$
          maxLength: 63
          example: my-workload-1
        image:
          type: string
          description: OCI image reference
          example: docker.io/library/alpine:latest
        size:
          type: string
          description: Base memory size (human-readable format like "1GB", "512MB", "2G")
          default: "1GB"
          example: "2GB"
        hotplug_size:
          type: string
          description: Additional memory for hotplug (human-readable format like "3GB", "1G"). Omit to disable hotplug memory.
          example: "2GB"
        overlay_size:
          type: string
          description: Writable overlay disk size (human-readable format like "10GB", "50G")
          default: "10GB"
          example: "20GB"
        disk_io_bps:
          type: string
          description: Disk I/O rate limit (e.g., "100MB/s", "500MB/s"). Defaults to proportional share based on CPU allocation if configured.
          example: "100MB/s"
        vcpus:
          type: integer
          description: Number of virtual CPUs
          default: 2
          example: 2
        env:
          type: object
          additionalProperties:
            type: string
          description: Environment variables
          example:
            PORT: "3000"
            NODE_ENV: production
        tags:
          $ref: "#/components/schemas/Tags"
        network:
          type: object
          description: Network configuration for the instance
          properties:
            enabled:
              type: boolean
              description: Whether to attach instance to the default network
              default: true
              example: true
            bandwidth_download:
              type: string
              description: Download bandwidth limit (external→VM, e.g., "1Gbps", "125MB/s"). Defaults to proportional share based on CPU allocation.
              example: "1Gbps"
            bandwidth_upload:
              type: string
              description: Upload bandwidth limit (VM→external, e.g., "1Gbps", "125MB/s"). Defaults to proportional share based on CPU allocation.
              example: "1Gbps"
        devices:
          type: array
          items:
            type: string
          description: Device IDs or names to attach for GPU/PCI passthrough
          example: ["l4-gpu"]
        gpu:
          $ref: "#/components/schemas/GPUConfig"
        volumes:
          type: array
          description: Volumes to attach to the instance at creation time
          items:
            $ref: "#/components/schemas/VolumeMount"
        hypervisor:
          type: string
          enum: [cloud-hypervisor, firecracker, qemu, vz]
          description: Hypervisor to use for this instance. Defaults to server configuration.
          example: cloud-hypervisor
        skip_kernel_headers:
          type: boolean
          description: |
            Skip kernel headers installation during boot for faster startup.
            When true, DKMS (Dynamic Kernel Module Support) will not work,
            preventing compilation of out-of-tree kernel modules (e.g., NVIDIA vGPU drivers).
            Recommended for workloads that don't need kernel module compilation.
          default: false
          example: true
        skip_guest_agent:
          type: boolean
          description: |
            Skip guest-agent installation during boot.
            When true, the exec and stat APIs will not work for this instance.
            The instance will still run, but remote command execution will be unavailable.
          default: false
          example: false
        entrypoint:
          type: array
          items:
            type: string
          description: Override image entrypoint (like docker run --entrypoint). Omit to use image default.
          example: ["/bin/sh", "-c"]
        cmd:
          type: array
          items:
            type: string
          description: Override image CMD (like docker run <image> <command>). Omit to use image default.
          example: ["echo", "hello"]
        # Future: port_mappings, timeout_seconds

    ForkInstanceRequest:
      type: object
      required: [name]
      properties:
        name:
          type: string
          description: Name for the forked instance (lowercase letters, digits, and dashes only; cannot start or end with a dash)
          pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$
          maxLength: 63
          example: my-workload-1-fork
        from_running:
          type: boolean
          description: |
            Allow forking from a running source instance.
            When true and source is Running, the source is put into standby, forked, then restored back to Running.
          default: false
          example: false
        target_state:
          $ref: "#/components/schemas/ForkTargetState"
          description: |
            Optional final state for the forked instance.
            Default is the source instance state at fork time.
            For example, forking from Running defaults the fork result to Running.

    ForkTargetState:
      type: string
      description: Target state for the forked instance after fork completes
      enum: [Stopped, Standby, Running]
      example: Running

    SnapshotKind:
      type: string
      description: Snapshot capture kind
      enum: [Standby, Stopped]
      example: Standby

    SnapshotTargetState:
      type: string
      description: Target state when restoring or forking from a snapshot
      enum: [Stopped, Standby, Running]
      example: Running

    Snapshot:
      type: object
      required: [id, kind, source_instance_id, source_instance_name, source_hypervisor, created_at, size_bytes]
      properties:
        id:
          type: string
          description: Auto-generated unique snapshot identifier
          example: q7z1w7l2af4l8y7q1h7g2m3s
        name:
          type: string
          description: Optional human-readable snapshot name (unique per source instance)
          nullable: true
          example: baseline-standby
        kind:
          $ref: "#/components/schemas/SnapshotKind"
        tags:
          $ref: "#/components/schemas/Tags"
        source_instance_id:
          type: string
          description: Source instance ID at snapshot creation time
          example: qilviffnqzck2jrim1x6s2b1
        source_instance_name:
          type: string
          description: Source instance name at snapshot creation time
          example: nginx1
        source_hypervisor:
          type: string
          enum: [cloud-hypervisor, firecracker, qemu, vz]
          description: Source instance hypervisor at snapshot creation time
          example: cloud-hypervisor
        created_at:
          type: string
          format: date-time
          description: Snapshot creation timestamp
          example: "2026-03-06T13:56:11Z"
        size_bytes:
          type: integer
          format: int64
          description: Total payload size in bytes
          example: 104857600

    CreateSnapshotRequest:
      type: object
      required: [kind]
      properties:
        kind:
          $ref: "#/components/schemas/SnapshotKind"
        name:
          type: string
          description: Optional snapshot name (lowercase letters, digits, and dashes only; cannot start or end with a dash)
          pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$
          maxLength: 63
          example: pre-upgrade
        tags:
          $ref: "#/components/schemas/Tags"

    RestoreSnapshotRequest:
      type: object
      properties:
        target_state:
          $ref: "#/components/schemas/SnapshotTargetState"
          description: |
            Optional final state after restore.
            Defaults by snapshot kind:
            - Standby snapshot defaults to Running
            - Stopped snapshot defaults to Stopped
        target_hypervisor:
          type: string
          enum: [cloud-hypervisor, firecracker, qemu, vz]
          description: |
            Optional hypervisor override. Allowed only when restoring from a Stopped snapshot.
            Standby snapshots must restore with their original hypervisor.
          example: qemu

    ForkSnapshotRequest:
      type: object
      required: [name]
      properties:
        name:
          type: string
          description: Name for the new instance (lowercase letters, digits, and dashes only; cannot start or end with a dash)
          pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$
          maxLength: 63
          example: nginx-from-snap
        target_state:
          $ref: "#/components/schemas/SnapshotTargetState"
          description: |
            Optional final state for the forked instance.
            Defaults by snapshot kind:
            - Standby snapshot defaults to Running
            - Stopped snapshot defaults to Stopped
        target_hypervisor:
          type: string
          enum: [cloud-hypervisor, firecracker, qemu, vz]
          description: |
            Optional hypervisor override. Allowed only when forking from a Stopped snapshot.
            Standby snapshots must fork with their original hypervisor.
          example: cloud-hypervisor
    
    Instance:
      type: object
      required: [id, name, image, state, created_at]
      properties:
        id:
          type: string
          description: Auto-generated unique identifier (CUID2 format)
          example: tz4a98xxat96iws9zmbrgj3a
        name:
          type: string
          description: Human-readable name
          example: my-workload-1
        image:
          type: string
          description: OCI image reference
          example: docker.io/library/alpine:latest
        state:
          $ref: "#/components/schemas/InstanceState"
        state_error:
          type: string
          description: Error message if state couldn't be determined (only set when state is Unknown)
          nullable: true
          example: "failed to query VMM: connection refused"
        size:
          type: string
          description: Base memory size (human-readable)
          example: "2GB"
        hotplug_size:
          type: string
          description: Hotplug memory size (human-readable)
          example: "2GB"
        overlay_size:
          type: string
          description: Writable overlay disk size (human-readable)
          example: "10GB"
        vcpus:
          type: integer
          description: Number of virtual CPUs
          example: 2
        disk_io_bps:
          type: string
          description: Disk I/O rate limit (human-readable, e.g., "100MB/s")
          example: "100MB/s"
        env:
          type: object
          additionalProperties:
            type: string
          description: Environment variables
        tags:
          $ref: "#/components/schemas/Tags"
        network:
          type: object
          description: Network configuration of the instance
          properties:
            enabled:
              type: boolean
              description: Whether instance is attached to the default network
              example: true
            name:
              type: string
              description: Network name (always "default" when enabled)
              example: "default"
            ip:
              type: string
              description: Assigned IP address (null if no network)
              example: "192.168.100.10"
              nullable: true
            mac:
              type: string
              description: Assigned MAC address (null if no network)
              example: "02:00:00:ab:cd:ef"
              nullable: true
            bandwidth_download:
              type: string
              description: Download bandwidth limit (human-readable, e.g., "1Gbps", "125MB/s")
              example: "125MB/s"
            bandwidth_upload:
              type: string
              description: Upload bandwidth limit (human-readable, e.g., "1Gbps", "125MB/s")
              example: "125MB/s"
        volumes:
          type: array
          description: Volumes attached to the instance
          items:
            $ref: "#/components/schemas/VolumeMount"
        gpu:
          $ref: "#/components/schemas/InstanceGPU"
        created_at:
          type: string
          format: date-time
          description: Creation timestamp (RFC3339)
          example: "2025-01-15T10:30:00Z"
        started_at:
          type: string
          format: date-time
          description: Start timestamp (RFC3339)
          example: "2025-01-15T10:30:05Z"
          nullable: true
        stopped_at:
          type: string
          format: date-time
          description: Stop timestamp (RFC3339)
          example: "2025-01-15T12:30:00Z"
          nullable: true
        exit_code:
          type: integer
          description: App exit code (null if VM hasn't exited)
          nullable: true
          example: 137
        exit_message:
          type: string
          description: Human-readable description of exit (e.g., "command not found", "killed by signal 9 (SIGKILL) - OOM")
          example: "killed by signal 9 (SIGKILL)"
        has_snapshot:
          type: boolean
          description: Whether a snapshot exists for this instance
          example: false
        hypervisor:
          type: string
          enum: [cloud-hypervisor, firecracker, qemu, vz]
          description: Hypervisor running this instance
          example: cloud-hypervisor
    
    PathInfo:
      type: object
      required: [exists]
      properties:
        exists:
          type: boolean
          description: Whether the path exists
          example: true
        is_dir:
          type: boolean
          description: True if this is a directory
          example: false
        is_file:
          type: boolean
          description: True if this is a regular file
          example: true
        is_symlink:
          type: boolean
          description: True if this is a symbolic link (only set when follow_links=false)
          example: false
        link_target:
          type: string
          description: Symlink target path (only set when is_symlink=true)
          nullable: true
          example: "/actual/target/path"
        mode:
          type: integer
          description: File mode (Unix permissions)
          example: 420
        size:
          type: integer
          format: int64
          description: File size in bytes
          example: 1024
        error:
          type: string
          description: Error message if stat failed (e.g., permission denied). Only set when exists is false due to an error rather than the path not existing.
          nullable: true
          example: "permission denied"
    
    InstanceStats:
      type: object
      required: [instance_id, instance_name, cpu_seconds, memory_rss_bytes, memory_vms_bytes, network_rx_bytes, network_tx_bytes, allocated_vcpus, allocated_memory_bytes]
      description: Real-time resource utilization statistics for a VM instance
      properties:
        instance_id:
          type: string
          description: Instance identifier
          example: "qilviffnqzck2jrim1x6s2b1"
        instance_name:
          type: string
          description: Instance name
          example: "my-web-server"
        cpu_seconds:
          type: number
          format: double
          description: Total CPU time consumed by the VM hypervisor process in seconds
          example: 29.94
        memory_rss_bytes:
          type: integer
          format: int64
          description: Resident Set Size - actual physical memory used by the VM in bytes
          example: 443338752
        memory_vms_bytes:
          type: integer
          format: int64
          description: Virtual Memory Size - total virtual memory allocated in bytes
          example: 4330745856
        network_rx_bytes:
          type: integer
          format: int64
          description: Total network bytes received by the VM (from TAP interface)
          example: 12345678
        network_tx_bytes:
          type: integer
          format: int64
          description: Total network bytes transmitted by the VM (from TAP interface)
          example: 87654321
        allocated_vcpus:
          type: integer
          description: Number of vCPUs allocated to the VM
          example: 2
        allocated_memory_bytes:
          type: integer
          format: int64
          description: Total memory allocated to the VM (Size + HotplugSize) in bytes
          example: 4294967296
        memory_utilization_ratio:
          type: number
          format: double
          description: Memory utilization ratio (RSS / allocated memory). Only present when allocated_memory_bytes > 0.
          nullable: true
          example: 0.103
    
    CreateImageRequest:
      type: object
      required: [name]
      properties:
        name:
          type: string
          description: OCI image reference (e.g., docker.io/library/nginx:latest)
          example: docker.io/library/nginx:latest
        tags:
          $ref: "#/components/schemas/Tags"
    
    Image:
      type: object
      required: [name, digest, status, created_at]
      properties:
        name:
          type: string
          description: Normalized OCI image reference (tag or digest)
          example: docker.io/library/nginx:latest
        digest:
          type: string
          description: Resolved manifest digest
          example: sha256:abc123def456...
        status:
          type: string
          enum: [pending, pulling, converting, ready, failed]
          description: Build status
          example: ready
        queue_position:
          type: integer
          description: Position in build queue (null if not queued)
          example: 2
          nullable: true
        error:
          type: string
          description: Error message if status is failed
          example: "pull failed: connection timeout"
          nullable: true
        size_bytes:
          type: integer
          format: int64
          description: Disk size in bytes (null until ready)
          example: 536870912
          nullable: true
        entrypoint:
          type: array
          items:
            type: string
          description: Entrypoint from container metadata
          example: ["/docker-entrypoint.sh"]
          nullable: true
        cmd:
          type: array
          items:
            type: string
          description: CMD from container metadata
          example: ["nginx", "-g", "daemon off;"]
          nullable: true
        env:
          type: object
          additionalProperties:
            type: string
          description: Environment variables from container metadata
          example:
            PATH: /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
        tags:
          $ref: "#/components/schemas/Tags"
        working_dir:
          type: string
          description: Working directory from container metadata
          example: /app
          nullable: true
        created_at:
          type: string
          format: date-time
          description: Creation timestamp (RFC3339)
          example: "2025-01-15T10:00:00Z"
    
    CreateVolumeRequest:
      type: object
      required: [name, size_gb]
      properties:
        id:
          type: string
          description: Optional custom identifier (auto-generated if not provided)
          example: vol-data-1
        name:
          type: string
          description: Volume name
          example: my-data-volume
        size_gb:
          type: integer
          description: Size in gigabytes
          example: 10
        tags:
          $ref: "#/components/schemas/Tags"
    
    VolumeAttachment:
      type: object
      required: [instance_id, mount_path, readonly]
      properties:
        instance_id:
          type: string
          description: ID of the instance this volume is attached to
          example: inst-abc123
        mount_path:
          type: string
          description: Mount path in the guest
          example: /mnt/data
        readonly:
          type: boolean
          description: Whether the attachment is read-only
          example: false
    
    Volume:
      type: object
      required: [id, name, size_gb, created_at]
      properties:
        id:
          type: string
          description: Unique identifier
          example: vol-data-1
        name:
          type: string
          description: Volume name
          example: my-data-volume
        size_gb:
          type: integer
          description: Size in gigabytes
          example: 10
        tags:
          $ref: "#/components/schemas/Tags"
        attachments:
          type: array
          description: List of current attachments (empty if not attached)
          items:
            $ref: "#/components/schemas/VolumeAttachment"
        created_at:
          type: string
          format: date-time
          description: Creation timestamp (RFC3339)
          example: "2025-01-15T09:00:00Z"
    
    AttachVolumeRequest:
      type: object
      required: [mount_path]
      properties:
        mount_path:
          type: string
          description: Path where volume should be mounted
          example: /mnt/data
        readonly:
          type: boolean
          description: Mount as read-only
          default: false

    Health:
      type: object
      required: [status]
      properties:
        status:
          type: string
          enum: [ok]
          example: ok
    
    IngressMatch:
      type: object
      required: [hostname]
      properties:
        hostname:
          type: string
          description: |
            Hostname to match. Can be:
            - Literal: "api.example.com" (exact match on Host header)
            - Pattern: "{instance}.example.com" (dynamic routing based on subdomain)
            
            Pattern hostnames use named captures in curly braces (e.g., {instance}, {app})
            that extract parts of the hostname for routing. The extracted values can be
            referenced in the target.instance field.
          example: "{instance}.example.com"
        port:
          type: integer
          description: Host port to listen on for this rule (default 80)
          default: 80
          example: 8080
    
    IngressTarget:
      type: object
      required: [instance, port]
      properties:
        instance:
          type: string
          description: |
            Target instance name, ID, or capture reference.
            - For literal hostnames: Use the instance name or ID directly (e.g., "my-api")
            - For pattern hostnames: Reference a capture from the hostname (e.g., "{instance}")
            
            When using pattern hostnames, the instance is resolved dynamically at request time.
          example: "{instance}"
        port:
          type: integer
          description: Target port on the instance
          example: 8080
    
    IngressRule:
      type: object
      required: [match, target]
      properties:
        match:
          $ref: "#/components/schemas/IngressMatch"
        target:
          $ref: "#/components/schemas/IngressTarget"
        tls:
          type: boolean
          description: Enable TLS termination (certificate auto-issued via ACME).
          default: false
        redirect_http:
          type: boolean
          description: Auto-create HTTP to HTTPS redirect for this hostname (only applies when tls is enabled)
          default: false
    
    CreateIngressRequest:
      type: object
      required: [name, rules]
      properties:
        name:
          type: string
          description: Human-readable name (lowercase letters, digits, and dashes only; cannot start or end with a dash)
          pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$
          maxLength: 63
          example: my-api-ingress
        rules:
          type: array
          description: Routing rules for this ingress
          items:
            $ref: "#/components/schemas/IngressRule"
          minItems: 1
        tags:
          $ref: "#/components/schemas/Tags"
    
    Ingress:
      type: object
      required: [id, name, rules, created_at]
      properties:
        id:
          type: string
          description: Auto-generated unique identifier
          example: 2OgJqXsP7j1qLVVYvGJDNiYVlPO
        name:
          type: string
          description: Human-readable name
          example: my-api-ingress
        tags:
          $ref: "#/components/schemas/Tags"
        rules:
          type: array
          description: Routing rules for this ingress
          items:
            $ref: "#/components/schemas/IngressRule"
        created_at:
          type: string
          format: date-time
          description: Creation timestamp (RFC3339)
          example: "2025-01-15T10:00:00Z"

    DeviceType:
      type: string
      enum: [gpu, pci]
      description: Type of PCI device
    
    GPUConfig:
      type: object
      description: GPU configuration for the instance
      properties:
        profile:
          type: string
          description: vGPU profile name (e.g., "L40S-1Q"). Only used in vGPU mode.
          example: "L40S-1Q"
    
    InstanceGPU:
      type: object
      description: GPU information attached to the instance
      properties:
        profile:
          type: string
          description: vGPU profile name
          example: "L40S-1Q"
        mdev_uuid:
          type: string
          description: mdev device UUID
          example: "aa618089-8b16-4d01-a136-25a0f3c73123"
    
    GPUProfile:
      type: object
      description: Available vGPU profile
      required: [name, framebuffer_mb, available]
      properties:
        name:
          type: string
          description: Profile name (user-facing)
          example: "L40S-1Q"
        framebuffer_mb:
          type: integer
          description: Frame buffer size in MB
          example: 1024
        available:
          type: integer
          description: Number of instances that can be created with this profile
          example: 59
    
    PassthroughDevice:
      type: object
      description: Physical GPU available for passthrough
      required: [name, available]
      properties:
        name:
          type: string
          description: GPU name
          example: "NVIDIA L40S"
        available:
          type: boolean
          description: Whether this GPU is available (not attached to an instance)
          example: true
    
    GPUResourceStatus:
      type: object
      description: GPU resource status. Null if no GPUs available.
      nullable: true
      required: [mode, total_slots, used_slots]
      properties:
        mode:
          type: string
          enum: [vgpu, passthrough]
          description: GPU mode (vgpu for SR-IOV/mdev, passthrough for whole GPU)
          example: "vgpu"
        total_slots:
          type: integer
          description: Total slots (VFs for vGPU, physical GPUs for passthrough)
          example: 64
        used_slots:
          type: integer
          description: Slots currently in use
          example: 5
        profiles:
          type: array
          description: Available vGPU profiles (only in vGPU mode)
          items:
            $ref: "#/components/schemas/GPUProfile"
        devices:
          type: array
          description: Physical GPUs (only in passthrough mode)
          items:
            $ref: "#/components/schemas/PassthroughDevice"
    
    CreateDeviceRequest:
      type: object
      required: [pci_address]
      properties:
        name:
          type: string
          description: Optional globally unique device name. If not provided, a name is auto-generated from the PCI address (e.g., "pci-0000-a2-00-0")
          pattern: ^[a-zA-Z0-9][a-zA-Z0-9_.-]+$
          example: l4-gpu
        pci_address:
          type: string
          description: PCI address of the device (required, e.g., "0000:a2:00.0")
          example: "0000:a2:00.0"
        tags:
          $ref: "#/components/schemas/Tags"
    
    Device:
      type: object
      required: [id, type, pci_address, vendor_id, device_id, iommu_group, bound_to_vfio, created_at]
      properties:
        id:
          type: string
          description: Auto-generated unique identifier (CUID2 format)
          example: tz4a98xxat96iws9zmbrgj3a
        name:
          type: string
          description: Device name (user-provided or auto-generated from PCI address)
          example: l4-gpu
        type:
          $ref: "#/components/schemas/DeviceType"
        tags:
          $ref: "#/components/schemas/Tags"
        pci_address:
          type: string
          description: PCI address
          example: "0000:a2:00.0"
        vendor_id:
          type: string
          description: PCI vendor ID (hex)
          example: "10de"
        device_id:
          type: string
          description: PCI device ID (hex)
          example: "27b8"
        iommu_group:
          type: integer
          description: IOMMU group number
          example: 82
        bound_to_vfio:
          type: boolean
          description: |
            Whether the device is currently bound to the vfio-pci driver, which is required for VM passthrough.
            - true: Device is bound to vfio-pci and ready for (or currently in use by) a VM. The device's native driver has been unloaded.
            - false: Device is using its native driver (e.g., nvidia) or no driver. Hypeman will automatically bind to vfio-pci when attaching to an instance.
          example: false
        attached_to:
          type: string
          description: Instance ID if attached
          nullable: true
          example: null
        created_at:
          type: string
          format: date-time
          description: Registration timestamp (RFC3339)
          example: "2025-01-15T10:00:00Z"
    
    AvailableDevice:
      type: object
      required: [pci_address, vendor_id, device_id, iommu_group]
      properties:
        pci_address:
          type: string
          description: PCI address
          example: "0000:a2:00.0"
        vendor_id:
          type: string
          description: PCI vendor ID (hex)
          example: "10de"
        device_id:
          type: string
          description: PCI device ID (hex)
          example: "27b8"
        vendor_name:
          type: string
          description: Human-readable vendor name
          example: "NVIDIA Corporation"
        device_name:
          type: string
          description: Human-readable device name
          example: "L4"
        iommu_group:
          type: integer
          description: IOMMU group number
          example: 82
        current_driver:
          type: string
          description: Currently bound driver (null if none)
          nullable: true
          example: "nvidia"

    BuildStatus:
      type: string
      enum: [queued, building, pushing, ready, failed, cancelled]
      description: Build job status
    
    BuildPolicy:
      type: object
      properties:
        timeout_seconds:
          type: integer
          description: Maximum build duration (default 600)
          default: 600
        memory_mb:
          type: integer
          description: Memory limit for builder VM (default 2048)
          default: 2048
        cpus:
          type: integer
          description: Number of vCPUs for builder VM (default 2)
          default: 2
        network_mode:
          type: string
          enum: [isolated, egress]
          description: Network access during build
          default: egress
    
    BuildProvenance:
      type: object
      properties:
        base_image_digest:
          type: string
          description: Pinned base image digest used
        source_hash:
          type: string
          description: SHA256 hash of source tarball
        lockfile_hashes:
          type: object
          additionalProperties:
            type: string
          description: Map of lockfile names to SHA256 hashes
        buildkit_version:
          type: string
          description: BuildKit version used
        timestamp:
          type: string
          format: date-time
          description: Build completion timestamp
    
    BuildEvent:
      type: object
      required: [type, timestamp]
      properties:
        type:
          type: string
          enum: [log, status, heartbeat]
          description: Event type
        timestamp:
          type: string
          format: date-time
          description: Event timestamp
        content:
          type: string
          description: Log line content (only for type=log)
        status:
          $ref: "#/components/schemas/BuildStatus"
          description: New build status (only for type=status)
    
    Build:
      type: object
      required: [id, status, created_at]
      properties:
        id:
          type: string
          description: Build job identifier
          example: "build-abc123"
        status:
          $ref: "#/components/schemas/BuildStatus"
        tags:
          $ref: "#/components/schemas/Tags"
        queue_position:
          type: integer
          description: Position in build queue (only when status is queued)
          nullable: true
        image_digest:
          type: string
          description: Digest of built image (only when status is ready)
          nullable: true
        image_ref:
          type: string
          description: Full image reference (only when status is ready)
          nullable: true
        error:
          type: string
          description: Error message (only when status is failed)
          nullable: true
        provenance:
          $ref: "#/components/schemas/BuildProvenance"
        created_at:
          type: string
          format: date-time
          description: Build creation timestamp
        started_at:
          type: string
          format: date-time
          description: Build start timestamp
          nullable: true
        completed_at:
          type: string
          format: date-time
          description: Build completion timestamp
          nullable: true
        duration_ms:
          type: integer
          format: int64
          description: Build duration in milliseconds
          nullable: true
        builder_instance_id:
          type: string
          description: Instance ID of the builder VM (for debugging)
          nullable: true

    ResourceStatus:
      type: object
      required: [type, capacity, effective_limit, allocated, available, oversub_ratio]
      properties:
        type:
          type: string
          description: Resource type
          example: "cpu"
        capacity:
          type: integer
          format: int64
          description: Raw host capacity
          example: 64
        effective_limit:
          type: integer
          format: int64
          description: Capacity after oversubscription (capacity * ratio)
          example: 128
        allocated:
          type: integer
          format: int64
          description: Currently allocated resources
          example: 48
        available:
          type: integer
          format: int64
          description: Available for allocation (effective_limit - allocated)
          example: 80
        oversub_ratio:
          type: number
          format: double
          description: Oversubscription ratio applied
          example: 2.0
        source:
          type: string
          description: How capacity was determined (detected, configured)
          example: "detected"

    DiskBreakdown:
      type: object
      properties:
        images_bytes:
          type: integer
          format: int64
          description: Disk used by exported rootfs images
          example: 214748364800
        oci_cache_bytes:
          type: integer
          format: int64
          description: Disk used by OCI layer cache (shared blobs)
          example: 53687091200
        volumes_bytes:
          type: integer
          format: int64
          description: Disk used by volumes
          example: 107374182400
        overlays_bytes:
          type: integer
          format: int64
          description: Disk used by instance overlays (rootfs + volume overlays)
          example: 227633306624

    ResourceAllocation:
      type: object
      properties:
        instance_id:
          type: string
          description: Instance identifier
          example: "abc123"
        instance_name:
          type: string
          description: Instance name
          example: "my-vm"
        cpu:
          type: integer
          description: vCPUs allocated
          example: 4
        memory_bytes:
          type: integer
          format: int64
          description: Memory allocated in bytes
          example: 8589934592
        disk_bytes:
          type: integer
          format: int64
          description: Disk allocated in bytes (overlay + volumes)
          example: 10737418240
        network_download_bps:
          type: integer
          format: int64
          description: Download bandwidth limit in bytes/sec (external→VM)
          example: 125000000
        network_upload_bps:
          type: integer
          format: int64
          description: Upload bandwidth limit in bytes/sec (VM→external)
          example: 125000000
        disk_io_bps:
          type: integer
          format: int64
          description: Disk I/O bandwidth limit in bytes/sec
          example: 104857600

    Resources:
      type: object
      required: [cpu, memory, disk, network, allocations]
      properties:
        cpu:
          $ref: "#/components/schemas/ResourceStatus"
        memory:
          $ref: "#/components/schemas/ResourceStatus"
        disk:
          $ref: "#/components/schemas/ResourceStatus"
        network:
          $ref: "#/components/schemas/ResourceStatus"
        disk_io:
          $ref: "#/components/schemas/ResourceStatus"
        disk_breakdown:
          $ref: "#/components/schemas/DiskBreakdown"
        gpu:
          $ref: "#/components/schemas/GPUResourceStatus"
        allocations:
          type: array
          items:
            $ref: "#/components/schemas/ResourceAllocation"

paths:
  /health:
    get:
      summary: Health check
      operationId: getHealth
      responses:
        200:
          description: Service is healthy
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Health"
  
  /resources:
    get:
      summary: Get host resource capacity and allocations
      description: |
        Returns current host resource capacity, allocation status, and per-instance breakdown.
        Resources include CPU, memory, disk, and network. Oversubscription ratios are applied
        to calculate effective limits.
      operationId: getResources
      security:
        - bearerAuth: []
      responses:
        200:
          description: Resource status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Resources"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  
  /images:
    get:
      summary: List images
      operationId: listImages
      security:
        - bearerAuth: []
      parameters:
        - name: tags
          in: query
          required: false
          style: deepObject
          explode: true
          schema:
            $ref: "#/components/schemas/Tags"
          description: Filter images by tag key-value pairs.
      responses:
        200:
          description: List of images
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Image"
        401:
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    post:
      summary: Pull and convert OCI image
      operationId: createImage
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateImageRequest"
      responses:
        202:
          description: Image build started (async)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Image"
        400:
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: Image not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        401:
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  
  /images/{name}:
    get:
      summary: Get image details
      operationId: getImage
      security:
        - bearerAuth: []
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
          description: URL-encoded image name (e.g. docker.io%2Flibrary%2Falpine%3Alatest)
      responses:
        200:
          description: Image details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Image"
        404:
          description: Image not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    delete:
      summary: Delete image
      operationId: deleteImage
      security:
        - bearerAuth: []
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
          description: URL-encoded image name
      responses:
        204:
          description: Image deleted
        404:
          description: Image not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  
  /instances:
    get:
      summary: List instances
      operationId: listInstances
      security:
        - bearerAuth: []
      parameters:
        - name: state
          in: query
          required: false
          schema:
            $ref: "#/components/schemas/InstanceState"
          description: Filter instances by state (e.g., Running, Stopped)
        - name: tags
          in: query
          required: false
          style: deepObject
          explode: true
          schema:
            $ref: "#/components/schemas/Tags"
          description: |
            Filter instances by tag key-value pairs. Uses deepObject style:
            ?tags[team]=backend&tags[env]=staging
            Multiple entries are ANDed together. All specified key-value pairs must match.
      responses:
        200:
          description: List of instances
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Instance"
        401:
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    post:
      summary: Create and start instance
      operationId: createInstance
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateInstanceRequest"
      responses:
        201:
          description: Instance created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Instance"
        400:
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        401:
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        409:
          description: Conflict - insufficient resources or name already exists
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  
  /instances/{id}:
    get:
      summary: Get instance details
      operationId: getInstance
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Instance ID or name
      responses:
        200:
          description: Instance details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Instance"
        404:
          description: Instance not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    delete:
      summary: Stop and delete instance
      operationId: deleteInstance
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Instance ID or name
      responses:
        204:
          description: Instance deleted
        404:
          description: Instance not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  
  /instances/{id}/standby:
    post:
      summary: Put instance in standby (pause, snapshot, delete VMM)
      operationId: standbyInstance
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Instance ID or name
      responses:
        200:
          description: Instance in standby
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Instance"
        404:
          description: Instance not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        409:
          description: Conflict - instance not in correct state
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  
  /instances/{id}/restore:
    post:
      summary: Restore instance from standby
      operationId: restoreInstance
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Instance ID or name
      responses:
        200:
          description: Instance restored
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Instance"
        404:
          description: Instance not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        409:
          description: Conflict - instance not in standby or no snapshot
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /instances/{id}/fork:
    post:
      summary: Fork an instance from stopped, standby, or running (with from_running=true)
      operationId: forkInstance
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Source instance ID or name
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ForkInstanceRequest"
      responses:
        201:
          description: Forked instance created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Instance"
        400:
          description: Bad request - invalid fork request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: Source instance not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        409:
          description: Conflict - invalid state (including running without from_running=true) or target name conflict
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        501:
          description: Not implemented - fork not supported by this hypervisor
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /instances/{id}/snapshots:
    post:
      summary: Create a snapshot for an instance
      operationId: createInstanceSnapshot
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Source instance ID or name
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateSnapshotRequest"
      responses:
        201:
          description: Snapshot created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Snapshot"
        400:
          description: Bad request - invalid snapshot request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: Source instance not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        409:
          description: Conflict - invalid state or duplicate snapshot name
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        501:
          description: Not implemented - operation unsupported by source hypervisor
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /instances/{id}/snapshots/{snapshotId}/restore:
    post:
      summary: Restore an instance from a snapshot in-place
      operationId: restoreInstanceSnapshot
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Source instance ID or name
        - name: snapshotId
          in: path
          required: true
          schema:
            type: string
          description: Snapshot ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RestoreSnapshotRequest"
      responses:
        200:
          description: Instance restored from snapshot
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Instance"
        400:
          description: Bad request - invalid restore request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: Instance or snapshot not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        409:
          description: Conflict - invalid source state or unsupported transition
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        501:
          description: Not implemented - operation unsupported by target hypervisor
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /snapshots:
    get:
      summary: List snapshots
      operationId: listSnapshots
      security:
        - bearerAuth: []
      parameters:
        - name: source_instance_id
          in: query
          required: false
          schema:
            type: string
          description: Filter snapshots by source instance ID
        - name: kind
          in: query
          required: false
          schema:
            $ref: "#/components/schemas/SnapshotKind"
          description: Filter snapshots by kind
        - name: name
          in: query
          required: false
          schema:
            type: string
          description: Filter snapshots by snapshot name
        - name: tags
          in: query
          required: false
          style: deepObject
          explode: true
          schema:
            $ref: "#/components/schemas/Tags"
          description: Filter snapshots by tag key-value pairs.
      responses:
        200:
          description: List of snapshots
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Snapshot"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /snapshots/{snapshotId}:
    get:
      summary: Get snapshot details
      operationId: getSnapshot
      security:
        - bearerAuth: []
      parameters:
        - name: snapshotId
          in: path
          required: true
          schema:
            type: string
          description: Snapshot ID
      responses:
        200:
          description: Snapshot details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Snapshot"
        404:
          description: Snapshot not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    delete:
      summary: Delete a snapshot
      operationId: deleteSnapshot
      security:
        - bearerAuth: []
      parameters:
        - name: snapshotId
          in: path
          required: true
          schema:
            type: string
          description: Snapshot ID
      responses:
        204:
          description: Snapshot deleted
        404:
          description: Snapshot not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /snapshots/{snapshotId}/fork:
    post:
      summary: Fork a new instance from a snapshot
      operationId: forkSnapshot
      security:
        - bearerAuth: []
      parameters:
        - name: snapshotId
          in: path
          required: true
          schema:
            type: string
          description: Snapshot ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ForkSnapshotRequest"
      responses:
        201:
          description: Forked instance created from snapshot
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Instance"
        400:
          description: Bad request - invalid fork snapshot request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: Snapshot not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        409:
          description: Conflict - invalid target state or name conflict
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        501:
          description: Not implemented - operation unsupported by target hypervisor
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  
  /instances/{id}/stop:
    post:
      summary: Stop instance (graceful shutdown)
      operationId: stopInstance
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Instance ID or name
      responses:
        200:
          description: Instance stopped
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Instance"
        404:
          description: Instance not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        409:
          description: Conflict - instance not in correct state
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  
  /instances/{id}/start:
    post:
      summary: Start a stopped instance
      operationId: startInstance
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Instance ID or name
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                entrypoint:
                  type: array
                  items:
                    type: string
                  description: Override image entrypoint for this run. Omit to keep previous value.
                cmd:
                  type: array
                  items:
                    type: string
                  description: Override image CMD for this run. Omit to keep previous value.
      responses:
        200:
          description: Instance started
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Instance"
        404:
          description: Instance not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        409:
          description: Conflict - instance not in stopped state
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  
  /instances/{id}/logs:
    get:
      summary: Stream instance logs (SSE)
      description: |
        Streams instance logs as Server-Sent Events.
        Use the `source` parameter to select which log to stream:
        - `app` (default): Guest application logs (serial console)
        - `vmm`: Cloud Hypervisor VMM logs
        - `hypeman`: Hypeman operations log
        
        Returns the last N lines (controlled by `tail` parameter), then optionally
        continues streaming new lines if `follow=true`.
      operationId: getInstanceLogs
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Instance ID or name
        - name: tail
          in: query
          required: false
          schema:
            type: integer
            default: 100
          description: Number of lines to return from end
        - name: follow
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: Continue streaming new lines after initial output
        - name: source
          in: query
          required: false
          schema:
            type: string
            enum: [app, vmm, hypeman]
            default: app
          description: |
            Log source to stream:
            - app: Guest application logs (serial console output)
            - vmm: Cloud Hypervisor VMM logs (hypervisor stdout+stderr)
            - hypeman: Hypeman operations log (actions taken on this instance)
      responses:
        200:
          description: Log stream (SSE)
          content:
            text/event-stream:
              schema:
                type: string
        404:
          description: Instance not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  
  /instances/{id}/stat:
    get:
      summary: Get filesystem path info
      description: |
        Returns information about a path in the guest filesystem.
        Useful for checking if a path exists, its type, and permissions
        before performing file operations.
      operationId: statInstancePath
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Instance ID or name
        - name: path
          in: query
          required: true
          schema:
            type: string
          description: Path to stat in the guest filesystem
          example: "/app/data"
        - name: follow_links
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: Follow symbolic links (like stat vs lstat)
      responses:
        200:
          description: Path information
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PathInfo"
        404:
          description: Instance not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        409:
          description: Instance not in running state
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  
  /instances/{id}/stats:
    get:
      summary: Get instance resource utilization stats
      description: |
        Returns real-time resource utilization statistics for a running VM instance.
        Metrics are collected from /proc/<pid>/stat and /proc/<pid>/statm for CPU and memory,
        and from TAP interface statistics for network I/O.
      operationId: getInstanceStats
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Instance ID or name
      responses:
        200:
          description: Instance utilization statistics
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InstanceStats"
        404:
          description: Instance not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  
  /instances/{id}/volumes/{volumeId}:
    post:
      summary: Attach volume to instance
      operationId: attachVolume
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Instance ID or name
        - name: volumeId
          in: path
          required: true
          schema:
            type: string
          description: Volume ID or name
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AttachVolumeRequest"
      responses:
        200:
          description: Volume attached
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Instance"
        404:
          description: Instance or volume not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        409:
          description: Conflict - volume already attached
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    delete:
      summary: Detach volume from instance
      operationId: detachVolume
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Instance ID or name
        - name: volumeId
          in: path
          required: true
          schema:
            type: string
          description: Volume ID or name
      responses:
        200:
          description: Volume detached
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Instance"
        404:
          description: Instance or volume not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  
  /volumes:
    get:
      summary: List volumes
      operationId: listVolumes
      security:
        - bearerAuth: []
      parameters:
        - name: tags
          in: query
          required: false
          style: deepObject
          explode: true
          schema:
            $ref: "#/components/schemas/Tags"
          description: Filter volumes by tag key-value pairs.
      responses:
        200:
          description: List of volumes
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Volume"
        401:
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    post:
      summary: Create empty volume
      description: Creates a new empty volume of the specified size.
      operationId: createVolume
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateVolumeRequest"
      responses:
        201:
          description: Volume created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Volume"
        400:
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        401:
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        409:
          description: Conflict - volume with this ID already exists
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  
  /volumes/from-archive:
    post:
      summary: Create volume from archive
      description: |
        Creates a new volume pre-populated with content from a tar.gz archive.
        The archive is streamed directly into the volume's root directory.
      operationId: createVolumeFromArchive
      security:
        - bearerAuth: []
      parameters:
        - name: name
          in: query
          required: true
          schema:
            type: string
          description: Volume name
          example: my-data-volume
        - name: size_gb
          in: query
          required: true
          schema:
            type: integer
          description: Maximum size in GB (extraction fails if content exceeds this)
          example: 10
        - name: id
          in: query
          required: false
          schema:
            type: string
          description: Optional custom volume ID (auto-generated if not provided)
          example: vol-data-1
        - name: tags
          in: query
          required: false
          style: deepObject
          explode: true
          schema:
            $ref: "#/components/schemas/Tags"
          description: Tags for the created volume.
      requestBody:
        required: true
        description: tar.gz archive file containing the volume content
        content:
          application/gzip:
            schema:
              type: string
              format: binary
      responses:
        201:
          description: Volume created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Volume"
        400:
          description: Bad request (invalid data or archive too large)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        401:
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        409:
          description: Conflict - volume with this ID already exists
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  
  /volumes/{id}:
    get:
      summary: Get volume details
      operationId: getVolume
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Volume ID or name
      responses:
        200:
          description: Volume details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Volume"
        404:
          description: Volume not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    delete:
      summary: Delete volume
      operationId: deleteVolume
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Volume ID or name
      responses:
        204:
          description: Volume deleted
        404:
          description: Volume not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        409:
          description: Conflict - volume is attached
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  
  /devices:
    get:
      summary: List registered devices
      operationId: listDevices
      security:
        - bearerAuth: []
      parameters:
        - name: tags
          in: query
          required: false
          style: deepObject
          explode: true
          schema:
            $ref: "#/components/schemas/Tags"
          description: Filter devices by tag key-value pairs.
      responses:
        200:
          description: List of registered devices
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Device"
        401:
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    post:
      summary: Register a device for passthrough
      operationId: createDevice
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateDeviceRequest"
      responses:
        201:
          description: Device registered
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Device"
        400:
          description: Bad request (invalid name or PCI address)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        401:
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        404:
          description: PCI device not found on host
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        409:
          description: Conflict - device or name already registered
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /devices/available:
    get:
      summary: Discover passthrough-capable devices on host
      operationId: listAvailableDevices
      security:
        - bearerAuth: []
      responses:
        200:
          description: List of available PCI devices
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/AvailableDevice"
        401:
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /devices/{id}:
    get:
      summary: Get device details
      operationId: getDevice
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Device ID or name
      responses:
        200:
          description: Device details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Device"
        404:
          description: Device not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    delete:
      summary: Unregister device
      operationId: deleteDevice
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Device ID or name
      responses:
        204:
          description: Device unregistered
        404:
          description: Device not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        409:
          description: Conflict - device is attached to an instance
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  
  /ingresses:
    get:
      summary: List ingresses
      operationId: listIngresses
      security:
        - bearerAuth: []
      parameters:
        - name: tags
          in: query
          required: false
          style: deepObject
          explode: true
          schema:
            $ref: "#/components/schemas/Tags"
          description: Filter ingresses by tag key-value pairs.
      responses:
        200:
          description: List of ingresses
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Ingress"
        401:
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    post:
      summary: Create ingress
      operationId: createIngress
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateIngressRequest"
      responses:
        201:
          description: Ingress created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Ingress"
        400:
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        401:
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        409:
          description: Conflict - ingress with this name already exists or hostname in use
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  
  /ingresses/{id}:
    get:
      summary: Get ingress details
      operationId: getIngress
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Ingress ID, name, or ID prefix
      responses:
        200:
          description: Ingress details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Ingress"
        404:
          description: Ingress not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        409:
          description: Ambiguous identifier matches multiple ingresses
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    delete:
      summary: Delete ingress
      operationId: deleteIngress
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Ingress ID, name, or ID prefix
      responses:
        204:
          description: Ingress deleted
        404:
          description: Ingress not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        409:
          description: Ambiguous identifier matches multiple ingresses
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /builds:
    get:
      summary: List builds
      operationId: listBuilds
      security:
        - bearerAuth: []
      parameters:
        - name: tags
          in: query
          required: false
          style: deepObject
          explode: true
          schema:
            $ref: "#/components/schemas/Tags"
          description: Filter builds by tag key-value pairs.
      responses:
        200:
          description: List of builds
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Build"
        401:
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    post:
      summary: Create a new build
      description: |
        Creates a new build job. Source code should be uploaded as a tar.gz archive
        in the multipart form data.
      operationId: createBuild
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - source
              properties:
                source:
                  type: string
                  format: binary
                  description: Source tarball (tar.gz) containing application code and optionally a Dockerfile
                dockerfile:
                  type: string
                  description: Dockerfile content. Required if not included in the source tarball.
                base_image_digest:
                  type: string
                  description: Optional pinned base image digest
                cache_scope:
                  type: string
                  description: Tenant-specific cache key prefix
                timeout_seconds:
                  type: integer
                  description: Build timeout (default 600)
                memory_mb:
                  type: integer
                  description: Memory limit for builder VM in MB (default 2048)
                cpus:
                  type: integer
                  description: Number of vCPUs for builder VM (default 2)
                image_name:
                  type: string
                  description: |
                    Custom image name for the build output. When set, the image is pushed
                    to {registry}/{image_name} instead of {registry}/builds/{id}.
                secrets:
                  type: string
                  description: |
                    JSON array of secret references to inject during build.
                    Each object has "id" (required) for use with --mount=type=secret,id=...
                    Example: [{"id": "npm_token"}, {"id": "github_token"}]
                is_admin_build:
                  type: string
                  description: |
                    Set to "true" to grant push access to global cache (operator-only).
                    Admin builds can populate the shared global cache that all tenant builds read from.
                global_cache_key:
                  type: string
                  description: |
                    Global cache identifier (e.g., "node", "python", "ubuntu", "browser").
                    When specified, the build will import from cache/global/{key}.
                    Admin builds will also export to this location.
                tags:
                  type: string
                  description: |
                    JSON object of tags.
                    Example: {"team":"backend","env":"staging"}
      responses:
        202:
          description: Build created and queued
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Build"
        400:
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        401:
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /builds/{id}:
    get:
      summary: Get build details
      operationId: getBuild
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Build ID
      responses:
        200:
          description: Build details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Build"
        404:
          description: Build not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    delete:
      summary: Cancel build
      operationId: cancelBuild
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Build ID
      responses:
        204:
          description: Build cancelled
        404:
          description: Build not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        409:
          description: Build already completed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /builds/{id}/events:
    get:
      summary: Stream build events (SSE)
      description: |
        Streams build events as Server-Sent Events. Events include:
        - `log`: Build log lines with timestamp and content
        - `status`: Build status changes (queued→building→pushing→ready/failed)
        - `heartbeat`: Keep-alive events sent every 30s to prevent connection timeouts
        
        Returns existing logs as events, then continues streaming if follow=true.
      operationId: getBuildEvents
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Build ID
        - name: follow
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: Continue streaming new events after initial output
      responses:
        200:
          description: Event stream (SSE). Each event is a JSON BuildEvent object.
          content:
            text/event-stream:
              schema:
                $ref: "#/components/schemas/BuildEvent"
        404:
          description: Build not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"