swagger: "2.0"
info:
  title: Firecracker API
  description: RESTful public-facing API.
    The API is accessible through HTTP calls on specific URLs
    carrying JSON modeled data.
    The transport medium is a Unix Domain Socket.
  version: 1.15.0-dev
  termsOfService: ""
  contact:
    email: "firecracker-maintainers@amazon.com"
  license:
    name: "Apache 2.0"
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"

host: "localhost"
basePath: "/"

schemes:
  - http
consumes:
  - application/json
produces:
  - application/json

paths:
  /:
    get:
      summary: Returns general information about an instance.
      operationId: describeInstance
      responses:
        200:
          description: The instance information
          schema:
            $ref: "#/definitions/InstanceInfo"
        default:
          description: Internal Server Error
          schema:
            $ref: "#/definitions/Error"

  /actions:
    put:
      summary: Creates a synchronous action.
      operationId: createSyncAction
      parameters:
        - name: info
          in: body
          required: true
          schema:
            $ref: "#/definitions/InstanceActionInfo"
      responses:
        204:
          description: The update was successful
        400:
          description: The action cannot be executed due to bad input
          schema:
            $ref: "#/definitions/Error"
        default:
          description: Internal Server Error
          schema:
            $ref: "#/definitions/Error"

  /balloon:
    get:
      summary: Returns the current balloon device configuration.
      operationId: describeBalloonConfig
      responses:
        200:
          description: The balloon device configuration
          schema:
            $ref: "#/definitions/Balloon"
        400:
          description: Balloon device not configured.
          schema:
            $ref: "#/definitions/Error"
        default:
          description: Internal Server Error
          schema:
            $ref: "#/definitions/Error"
    put:
      summary: Creates or updates a balloon device.
      description:
        Creates a new balloon device if one does not already exist, otherwise updates it, before machine startup.
        This will fail after machine startup.
        Will fail if update is not possible.
      operationId: putBalloon
      parameters:
      - name: body
        in: body
        description: Balloon properties
        required: true
        schema:
          $ref: "#/definitions/Balloon"
      responses:
        204:
          description: Balloon device created/updated
        400:
          description: Balloon device cannot be created/updated due to bad input
          schema:
            $ref: "#/definitions/Error"
        default:
          description: Internal server error
          schema:
            $ref: "#/definitions/Error"
    patch:
      summary: Updates a balloon device.
      description:
        Updates an existing balloon device, before or after machine startup.
        Will fail if update is not possible.
      operationId: patchBalloon
      parameters:
      - name: body
        in: body
        description: Balloon properties
        required: true
        schema:
          $ref: "#/definitions/BalloonUpdate"
      responses:
        204:
          description: Balloon device updated
        400:
          description: Balloon device cannot be updated due to bad input
          schema:
            $ref: "#/definitions/Error"
        default:
          description: Internal server error
          schema:
            $ref: "#/definitions/Error"

  /balloon/statistics:
    get:
      summary: Returns the latest balloon device statistics, only if enabled pre-boot.
      operationId: describeBalloonStats
      responses:
        200:
          description: The balloon device statistics
          schema:
            $ref: "#/definitions/BalloonStats"
        400:
          description: The balloon device statistics were not enabled when the device was configured.
          schema:
            $ref: "#/definitions/Error"
        default:
          description: Internal Server Error
          schema:
            $ref: "#/definitions/Error"
    patch:
      summary: Updates a balloon device statistics polling interval.
      description:
        Updates an existing balloon device statistics interval, before or after machine startup.
        Will fail if update is not possible.
      operationId: patchBalloonStatsInterval
      parameters:
      - name: body
        in: body
        description: Balloon properties
        required: true
        schema:
          $ref: "#/definitions/BalloonStatsUpdate"
      responses:
        204:
          description: Balloon statistics interval updated
        400:
          description: Balloon statistics interval cannot be updated due to bad input
          schema:
            $ref: "#/definitions/Error"
        default:
          description: Internal server error
          schema:
            $ref: "#/definitions/Error"

  /balloon/hinting/start:
    patch:
      summary: Starts a free page hinting run only if enabled pre-boot.
      operationId: startBalloonHinting
      parameters:
        - name: body
          in: body
          description: When the device completes the hinting whether we should automatically ack this.
          required: false
          schema:
            $ref: "#/definitions/BalloonStartCmd"
      responses:
        200:
          description: Free page hinting run started.
        400:
          description: The balloon free hinting was not enabled when the device was configured.
          schema:
            $ref: "#/definitions/Error"
        default:
          description: Internal Server Error
          schema:
            $ref: "#/definitions/Error"

  /balloon/hinting/status:
    get:
      summary: Returns the balloon hinting statistics, only if enabled pre-boot.
      operationId: describeBalloonHinting
      responses:
        200:
          description: The balloon free page hinting statistics
          schema:
            $ref: "#/definitions/BalloonHintingStatus"
        400:
          description: The balloon free hinting was not enabled when the device was configured.
          schema:
            $ref: "#/definitions/Error"
        default:
          description: Internal Server Error
          schema:
            $ref: "#/definitions/Error"

  /balloon/hinting/stop:
    patch:
      summary: Stops a free page hinting run only if enabled pre-boot.
      operationId: stopBalloonHinting
      responses:
        200:
          description: Free page hinting run stopped.
        400:
          description: The balloon free hinting was not enabled when the device was configured.
          schema:
            $ref: "#/definitions/Error"
        default:
          description: Internal Server Error
          schema:
            $ref: "#/definitions/Error"

  /boot-source:
    put:
      summary: Creates or updates the boot source. Pre-boot only.
      description:
        Creates new boot source if one does not already exist, otherwise updates it.
        Will fail if update is not possible.
      operationId: putGuestBootSource
      parameters:
        - name: body
          in: body
          description: Guest boot source properties
          required: true
          schema:
            $ref: "#/definitions/BootSource"
      responses:
        204:
          description: Boot source created/updated
        400:
          description: Boot source cannot be created due to bad input
          schema:
            $ref: "#/definitions/Error"
        default:
          description: Internal server error
          schema:
            $ref: "#/definitions/Error"

  /cpu-config:
    put:
      summary: Configures CPU features flags for the vCPUs of the guest VM. Pre-boot only.
      description:
        Provides configuration to the Firecracker process to specify vCPU resource configuration prior to
        launching the guest machine.
      operationId: putCpuConfiguration
      parameters:
        - name: body
          in: body
          description: CPU configuration request
          schema:
            $ref: "#/definitions/CpuConfig"
      responses:
        204:
          description: CPU configuration set successfully
        400:
          description: CPU configuration cannot be updated due to invalid input format
          schema:
            $ref: "#/definitions/Error"
        default:
          description: Internal server error
          schema:
            $ref: "#/definitions/Error"


  /drives/{drive_id}:
    put:
      summary: Creates or updates a drive. Pre-boot only.
      description:
        Creates new drive with ID specified by drive_id path parameter.
        If a drive with the specified ID already exists, updates its state based on new input.
        Will fail if update is not possible.
      operationId: putGuestDriveByID
      parameters:
        - name: drive_id
          in: path
          description: The id of the guest drive
          required: true
          type: string
        - name: body
          in: body
          description: Guest drive properties
          required: true
          schema:
            $ref: "#/definitions/Drive"
      responses:
        204:
          description: Drive created/updated
        400:
          description: Drive cannot be created/updated due to bad input
          schema:
            $ref: "#/definitions/Error"
        default:
          description: Internal server error.
          schema:
            $ref: "#/definitions/Error"
    patch:
      summary: Updates the properties of a drive. Post-boot only.
      description:
        Updates the properties of the drive with the ID specified by drive_id path parameter.
        Will fail if update is not possible.
      operationId: patchGuestDriveByID
      parameters:
        - name: drive_id
          in: path
          description: The id of the guest drive
          required: true
          type: string
        - name: body
          in: body
          description: Guest drive properties
          required: true
          schema:
            $ref: "#/definitions/PartialDrive"
      responses:
        204:
          description: Drive updated
        400:
          description: Drive cannot be updated due to bad input
          schema:
            $ref: "#/definitions/Error"
        default:
          description: Internal server error.
          schema:
            $ref: "#/definitions/Error"

  /pmem/{id}:
    put:
      summary: Creates or updates a pmem device. Pre-boot only.
      description:
        Creates new pmem device with ID specified by id parameter.
        If a pmem device with the specified ID already exists, updates its state based on new input.
        Will fail if update is not possible.
      operationId: putGuestPmemByID
      parameters:
        - name: id
          in: path
          description: The id of the guest pmem device
          required: true
          type: string
        - name: body
          in: body
          description: Guest pmem device properties
          required: true
          schema:
            $ref: "#/definitions/Pmem"
      responses:
        204:
          description: Pmem device is created/updated
        400:
          description: Pmem device cannot be created/updated due to bad input
          schema:
            $ref: "#/definitions/Error"
        default:
          description: Internal server error.
          schema:
            $ref: "#/definitions/Error"

  /logger:
    put:
      summary: Initializes the logger by specifying a named pipe or a file for the logs output.
      operationId: putLogger
      parameters:
        - name: body
          in: body
          description: Logging system description
          required: true
          schema:
            $ref: "#/definitions/Logger"
      responses:
        204:
          description: Logger created.
        400:
          description: Logger cannot be initialized due to bad input.
          schema:
            $ref: "#/definitions/Error"
        default:
          description: Internal server error.
          schema:
            $ref: "#/definitions/Error"

  /machine-config:
    get:
      summary: Gets the machine configuration of the VM.
      description:
        Gets the machine configuration of the VM. When called before the PUT operation, it
        will return the default values for the vCPU count (=1), memory size (=128 MiB).
        By default SMT is disabled and there is no CPU Template.
      operationId: getMachineConfiguration
      responses:
        200:
          description: OK
          schema:
            $ref: "#/definitions/MachineConfiguration"
        default:
          description: Internal server error
          schema:
            $ref: "#/definitions/Error"

    put:
      summary: Updates the Machine Configuration of the VM. Pre-boot only.
      description:
        Updates the Virtual Machine Configuration with the specified input.
        Firecracker starts with default values for vCPU count (=1) and memory size (=128 MiB).
        The vCPU count is restricted to the [1, 32] range.
        With SMT enabled, the vCPU count is required to be either 1 or an even number in the range.
        otherwise there are no restrictions regarding the vCPU count.
        If 2M hugetlbfs pages are specified, then `mem_size_mib` must be a multiple of 2.
        If any of the parameters has an incorrect value, the whole update fails.
        All parameters that are optional and are not specified are set to their default values
        (smt = false, track_dirty_pages = false, cpu_template = None, huge_pages = None).
      operationId: putMachineConfiguration
      parameters:
        - name: body
          in: body
          description: Machine Configuration Parameters
          schema:
            $ref: "#/definitions/MachineConfiguration"
      responses:
        204:
          description: Machine Configuration created/updated
        400:
          description: Machine Configuration cannot be updated due to bad input
          schema:
            $ref: "#/definitions/Error"
        default:
          description: Internal server error
          schema:
            $ref: "#/definitions/Error"

    patch:
      summary: Partially updates the Machine Configuration of the VM. Pre-boot only.
      description:
        Partially updates the Virtual Machine Configuration with the specified input.
        If any of the parameters has an incorrect value, the whole update fails.
      operationId: patchMachineConfiguration
      parameters:
        - name: body
          in: body
          description: A subset of Machine Configuration Parameters
          schema:
            $ref: "#/definitions/MachineConfiguration"
      responses:
        204:
          description: Machine Configuration created/updated
        400:
          description: Machine Configuration cannot be updated due to bad input
          schema:
            $ref: "#/definitions/Error"
        default:
          description: Internal server error
          schema:
            $ref: "#/definitions/Error"

  /metrics:
    put:
      summary: Initializes the metrics system by specifying a named pipe or a file for the metrics output.
      operationId: putMetrics
      parameters:
        - name: body
          in: body
          description: Metrics system description
          required: true
          schema:
            $ref: "#/definitions/Metrics"
      responses:
        204:
          description: Metrics system created.
        400:
          description: Metrics system cannot be initialized due to bad input request or metrics system already initialized.
          schema:
            $ref: "#/definitions/Error"
        default:
          description: Internal server error.
          schema:
            $ref: "#/definitions/Error"

  /mmds:
    put:
      summary: Creates a MMDS (Microvm Metadata Service) data store.
      operationId: putMmds
      parameters:
        - name: body
          in: body
          description: The MMDS data store as JSON.
          schema:
            $ref: "#/definitions/MmdsContentsObject"
      responses:
        204:
          description: MMDS data store created/updated.
        400:
          description: MMDS data store cannot be created due to bad input.
          schema:
            $ref: "#/definitions/Error"
        default:
          description: Internal server error
          schema:
            $ref: "#/definitions/Error"
    patch:
      summary: Updates the MMDS data store.
      operationId: patchMmds
      parameters:
        - name: body
          in: body
          description: The MMDS data store patch JSON.
          schema:
            $ref: "#/definitions/MmdsContentsObject"
      responses:
        204:
          description: MMDS data store updated.
        400:
          description: MMDS data store cannot be updated due to bad input.
          schema:
            $ref: "#/definitions/Error"
        default:
          description: Internal server error
          schema:
            $ref: "#/definitions/Error"
    get:
      summary: Get the MMDS data store.
      operationId: getMmds
      responses:
        200:
          description: The MMDS data store JSON.
          schema:
            type: object
            additionalProperties: true
        404:
          description: The MMDS data store content can not be found.
          schema:
            $ref: "#/definitions/Error"
        default:
          description: Internal server error
          schema:
            $ref: "#/definitions/Error"

  /mmds/config:
    put:
      summary: Set MMDS configuration. Pre-boot only.
      operationId: putMmdsConfig
      description:
        Configures MMDS version, IPv4 address used by the MMDS network stack
        and interfaces that allow MMDS requests.
      parameters:
        - name: body
          in: body
          description: The MMDS configuration as JSON.
          required: true
          schema:
            $ref: "#/definitions/MmdsConfig"
      responses:
        204:
          description: MMDS configuration was created/updated.
        400:
          description: MMDS configuration cannot be updated due to bad input.
          schema:
            $ref: "#/definitions/Error"
        default:
          description: Internal server error
          schema:
            $ref: "#/definitions/Error"

  /entropy:
    put:
      summary: Creates an entropy device. Pre-boot only.
      description:
        Enables an entropy device that provides high-quality random data to the guest.
      operationId: putEntropyDevice
      parameters:
        - name: body
          in: body
          description: Guest entropy device properties
          required: true
          schema:
            $ref: "#/definitions/EntropyDevice"
      responses:
        204:
          description: Entropy device created
        default:
          description: Internal server error
          schema:
            $ref: "#/definitions/Error"

  /serial:
    put:
      summary: Configures the serial console
      operationId: putSerialDevice
      description:
        Configure the serial console, which the guest can write its kernel logs to. Has no effect if
        the serial console is not also enabled on the guest kernel command line
      parameters:
        - name: body
          in: body
          description: Serial console properties
          required: true
          schema:
            $ref: "#/definitions/SerialDevice"
      responses:
        204:
          description: Serial device configured
        default:
          description: Internal server error
          schema:
            $ref: "#/definitions/Error"

  /hotplug/memory:
    put:
      summary: Configures the hotpluggable memory
      operationId: putMemoryHotplug
      description:
        Configure the hotpluggable memory, which is a virtio-mem device, with an associated memory area
        that can be hot(un)plugged in the guest on demand using the PATCH API.
      parameters:
        - name: body
          in: body
          description: Hotpluggable memory configuration
          required: true
          schema:
            $ref: "#/definitions/MemoryHotplugConfig"
      responses:
        204:
          description: Hotpluggable memory configured
        default:
          description: Internal server error
          schema:
            $ref: "#/definitions/Error"
    patch:
      summary: Updates the size of the hotpluggable memory region
      operationId: patchMemoryHotplug
      description:
        Updates the size of the hotpluggable memory region. The guest will plug and unplug memory to
        hit the requested memory.
      parameters:
        - name: body
          in: body
          description: Hotpluggable memory size update
          required: true
          schema:
            $ref: "#/definitions/MemoryHotplugSizeUpdate"
      responses:
        204:
          description: Hotpluggable memory configured
        default:
          description: Internal server error
          schema:
            $ref: "#/definitions/Error"
    get:
      summary: Retrieves the status of the hotpluggable memory
      operationId: getMemoryHotplug
      description:
        Reuturn the status of the hotpluggable memory. This can be used to follow the progress of the guest
        after a PATCH API.
      responses:
        200:
          description: OK
          schema:
            $ref: "#/definitions/MemoryHotplugStatus"
        default:
          description: Internal server error
          schema:
            $ref: "#/definitions/Error"

  /network-interfaces/{iface_id}:
    put:
      summary: Creates a network interface. Pre-boot only.
      description:
        Creates new network interface with ID specified by iface_id path parameter.
      operationId: putGuestNetworkInterfaceByID
      parameters:
        - name: iface_id
          in: path
          description: The id of the guest network interface
          required: true
          type: string
        - name: body
          in: body
          description: Guest network interface properties
          required: true
          schema:
            $ref: "#/definitions/NetworkInterface"
      responses:
        204:
          description: Network interface created/updated
        400:
          description: Network interface cannot be created due to bad input
          schema:
            $ref: "#/definitions/Error"
        default:
          description: Internal server error
          schema:
            $ref: "#/definitions/Error"
    patch:
      summary: Updates the rate limiters applied to a network interface. Post-boot only.
      description:
        Updates the rate limiters applied to a network interface.
      operationId: patchGuestNetworkInterfaceByID
      parameters:
        - name: iface_id
          in: path
          description: The id of the guest network interface
          required: true
          type: string
        - name: body
          in: body
          description: A subset of the guest network interface properties
          required: true
          schema:
            $ref: "#/definitions/PartialNetworkInterface"
      responses:
        204:
          description: Network interface updated
        400:
          description: Network interface cannot be updated due to bad input
          schema:
            $ref: "#/definitions/Error"
        default:
          description: Internal server error
          schema:
            $ref: "#/definitions/Error"

  /snapshot/create:
    put:
      summary: Creates a full or diff snapshot. Post-boot only.
      description:
        Creates a snapshot of the microVM state. The microVM should be
        in the `Paused` state.
      operationId: createSnapshot
      parameters:
        - name: body
          in: body
          description: The configuration used for creating a snapshot.
          required: true
          schema:
            $ref: "#/definitions/SnapshotCreateParams"
      responses:
        204:
          description: Snapshot created
        400:
          description: Snapshot cannot be created due to bad input
          schema:
            $ref: "#/definitions/Error"
        default:
          description: Internal server error
          schema:
            $ref: "#/definitions/Error"

  /snapshot/load:
    put:
      summary: Loads a snapshot. Pre-boot only.
      description:
        Loads the microVM state from a snapshot.
        Only accepted on a fresh Firecracker process (before configuring
        any resource other than the Logger and Metrics).
      operationId: loadSnapshot
      parameters:
        - name: body
          in: body
          description: The configuration used for loading a snapshot.
          required: true
          schema:
            $ref: "#/definitions/SnapshotLoadParams"
      responses:
        204:
          description: Snapshot loaded
        400:
          description: Snapshot cannot be loaded due to bad input
          schema:
            $ref: "#/definitions/Error"
        default:
          description: Internal server error
          schema:
            $ref: "#/definitions/Error"

  /version:
    get:
      summary: Gets the Firecracker version.
      operationId: getFirecrackerVersion
      responses:
        200:
          description: OK
          schema:
            $ref: "#/definitions/FirecrackerVersion"
        default:
          description: Internal server error
          schema:
            $ref: "#/definitions/Error"

  /vm:
    patch:
      summary: Updates the microVM state.
      description:
        Sets the desired state (Paused or Resumed) for the microVM.
      operationId: patchVm
      parameters:
        - name: body
          in: body
          description: The microVM state
          required: true
          schema:
            $ref: "#/definitions/Vm"
      responses:
        204:
          description: Vm state updated
        400:
          description: Vm state cannot be updated due to bad input
          schema:
            $ref: "#/definitions/Error"
        default:
          description: Internal server error
          schema:
            $ref: "#/definitions/Error"

  /vm/config:
    get:
      summary: Gets the full VM configuration.
      description:
        Gets configuration for all VM resources. If the VM is restored from a snapshot, the boot-source,
        machine-config.smt and machine-config.cpu_template will be empty.
      operationId: getExportVmConfig
      responses:
        200:
          description: OK
          schema:
            $ref: "#/definitions/FullVmConfiguration"
        default:
          description: Internal server error
          schema:
            $ref: "#/definitions/Error"

  /vsock:
    put:
      summary: Creates/updates a vsock device. Pre-boot only.
      description:
        The first call creates the device with the configuration specified
        in body. Subsequent calls will update the device configuration.
        May fail if update is not possible.
      operationId: putGuestVsock
      parameters:
        - name: body
          in: body
          description: Guest vsock properties
          required: true
          schema:
            $ref: "#/definitions/Vsock"
      responses:
        204:
          description: Vsock created/updated
        400:
          description: Vsock cannot be created due to bad input
          schema:
            $ref: "#/definitions/Error"
        default:
          description: Internal server error
          schema:
            $ref: "#/definitions/Error"

definitions:
  Balloon:
    type: object
    required:
      - amount_mib
      - deflate_on_oom
    description:
      Balloon device descriptor.
    properties:
      amount_mib:
        type: integer
        description: Target balloon size in MiB.
      deflate_on_oom:
        type: boolean
        description: Whether the balloon should deflate when the guest has memory pressure.
      stats_polling_interval_s:
        type: integer
        description: Interval in seconds between refreshing statistics. A non-zero value will enable the statistics. Defaults to 0.
      free_page_hinting:
        type: boolean
        description: Whether the free page hinting feature is enabled.
      free_page_reporting:
        type: boolean
        description: Whether the free page reporting feature is enabled.

  BalloonUpdate:
    type: object
    required:
      - amount_mib
    description:
      Balloon device descriptor.
    properties:
      amount_mib:
        type: integer
        description: Target balloon size in MiB.

  BalloonStats:
    type: object
    description:
      Describes the balloon device statistics.
    required:
      - target_pages
      - actual_pages
      - target_mib
      - actual_mib
    properties:
      target_pages:
        description: Target number of pages the device aims to hold.
        type: integer
      actual_pages:
        description: Actual number of pages the device is holding.
        type: integer
      target_mib:
        description: Target amount of memory (in MiB) the device aims to hold.
        type: integer
      actual_mib:
        description: Actual amount of memory (in MiB) the device is holding.
        type: integer
      swap_in:
        description: The amount of memory that has been swapped in (in bytes).
        type: integer
        format: int64
      swap_out:
        description: The amount of memory that has been swapped out to disk (in bytes).
        type: integer
        format: int64
      major_faults:
        description: The number of major page faults that have occurred.
        type: integer
        format: int64
      minor_faults:
        description: The number of minor page faults that have occurred.
        type: integer
        format: int64
      free_memory:
        description: The amount of memory not being used for any purpose (in bytes).
        type: integer
        format: int64
      total_memory:
        description: The total amount of memory available (in bytes).
        type: integer
        format: int64
      available_memory:
        description: An estimate of how much memory is available (in bytes) for starting new applications, without pushing the system to swap.
        type: integer
        format: int64
      disk_caches:
        description: The amount of memory, in bytes, that can be quickly reclaimed without additional I/O. Typically these pages are used for caching files from disk.
        type: integer
        format: int64
      hugetlb_allocations:
        description: The number of successful hugetlb page allocations in the guest.
        type: integer
        format: int64
      hugetlb_failures:
        description: The number of failed hugetlb page allocations in the guest.
        type: integer
        format: int64
      oom_kill:
        description: OOM killer invocations, indicating critical memory pressure.
        type: integer
        format: int64
      alloc_stall:
        description: Counter of Allocation enter a slow path to gain more memory page. The reclaim/scan metrics can reveal what is actually happening.
        type: integer
        format: int64
      async_scan:
        description: Amount of memory scanned asynchronously.
        type: integer
        format: int64
      direct_scan:
        description: Amount of memory scanned directly.
        type: integer
        format: int64
      async_reclaim:
        description: Amount of memory reclaimed asynchronously.
        type: integer
        format: int64
      direct_reclaim:
        description: Amount of memory reclaimed directly.
        type: integer
        format: int64

  BalloonStartCmd:
    type: object
    description:
      Command used to start a free page hinting run.
    properties:
      acknowledge_on_stop:
        description: If Firecracker should automatically acknowledge when the guest submits a done cmd.
        type: boolean

  BalloonHintingStatus:
    type: object
    description:
      Describes the free page hinting status.
    required:
      - host_cmd
    properties:
      host_cmd:
        description: The last command issued by the host.
        type: integer
      guest_cmd:
        description: The last command provided by the guest.
        type: integer

  BalloonStatsUpdate:
    type: object
    required:
      - stats_polling_interval_s
    description:
      Update the statistics polling interval, with the first statistics update scheduled immediately. Statistics cannot be turned on/off after boot.
    properties:
      stats_polling_interval_s:
        type: integer
        description: Interval in seconds between refreshing statistics.

  BootSource:
    type: object
    required:
      - kernel_image_path
    description:
      Boot source descriptor.
    properties:
      boot_args:
        type: string
        description: Kernel boot arguments
      initrd_path:
        type: string
        description: Host level path to the initrd image used to boot the guest
      kernel_image_path:
        type: string
        description: Host level path to the kernel image used to boot the guest

  CpuTemplate:
    type: string
    description:
      The CPU Template defines a set of flags to be disabled from the microvm so that
      the features exposed to the guest are the same as in the selected instance type.
      This parameter has been deprecated and it will be removed in future Firecracker
      release.
    enum:
      - C3
      - T2
      - T2S
      - T2CL
      - T2A
      - V1N1
      - None
    default: "None"

  CpuConfig:
    type: object
    description:
      The CPU configuration template defines a set of bit maps as modifiers of flags accessed by register
      to be disabled/enabled for the microvm.
    properties:
      kvm_capabilities:
        type: array
        description: A collection of KVM capabilities to be added or removed (both x86_64 and aarch64)
        items:
          type: string
          description: KVM capability as a numeric string. Prefix with '!' to remove capability. Example "121" (add) or "!121" (remove)
      cpuid_modifiers:
        type: array
        description: A collection of CPUID leaf modifiers (x86_64 only)
        items:
          $ref: "#/definitions/CpuidLeafModifier"
      msr_modifiers:
        type: array
        description: A collection of model specific register modifiers (x86_64 only)
        items:
          $ref: "#/definitions/MsrModifier"
      reg_modifiers:
        type: array
        description: A collection of register modifiers (aarch64 only)
        items:
          $ref: "#/definitions/ArmRegisterModifier"
      vcpu_features:
        type: array
        description: A collection of vCPU features to be modified (aarch64 only)
        items:
          $ref: "#/definitions/VcpuFeatures"

  CpuidLeafModifier:
    type: object
    description: Modifier for a CPUID leaf and subleaf (x86_64)
    required:
      - leaf
      - subleaf
      - flags
      - modifiers
    properties:
      leaf:
        type: string
        description: CPUID leaf index as hex, binary, or decimal string (e.g., "0x0", "0b0", "0"))
      subleaf:
        type: string
        description: CPUID subleaf index as hex, binary, or decimal string (e.g., "0x0", "0b0", "0")
      flags:
        type: integer
        format: int32
        description: KVM feature flags for this leaf-subleaf
      modifiers:
        type: array
        description: Register modifiers for this CPUID leaf
        items:
          $ref: "#/definitions/CpuidRegisterModifier"

  CpuidRegisterModifier:
    type: object
    description: Modifier for a specific CPUID register within a leaf (x86_64)
    required:
      - register
      - bitmap
    properties:
      register:
        type: string
        description: Target CPUID register name
        enum:
          - eax
          - ebx
          - ecx
          - edx
      bitmap:
        type: string
        description: 32-bit bitmap string defining which bits to modify. Format is "0b" followed by 32 characters where '0' = clear bit, '1' = set bit, 'x' = don't modify. Example "0b00000000000000000000000000000001" or "0bxxxxxxxxxxxxxxxxxxxxxxxxxxxx0001"

  MsrModifier:
    type: object
    description: Modifier for a model specific register (x86_64)
    required:
      - addr
      - bitmap
    properties:
      addr:
        type: string
        description: 32-bit MSR address as hex, binary, or decimal string (e.g., "0x10a", "0b100001010", "266")
      bitmap:
        type: string
        description: 64-bit bitmap string defining which bits to modify. Format is "0b" followed by 64 characters where '0' = clear bit, '1' = set bit, 'x' = don't modify. Underscores can be used for readability. Example "0b0000000000000000000000000000000000000000000000000000000000000001"

  ArmRegisterModifier:
    type: object
    description: Modifier for an ARM register (aarch64)
    required:
      - addr
      - bitmap
    properties:
      addr:
        type: string
        description: 64-bit register address as hex, binary, or decimal string (e.g., "0x0", "0b0", "0")
      bitmap:
        type: string
        description: 128-bit bitmap string defining which bits to modify. Format is "0b" followed by up to 128 characters where '0' = clear bit, '1' = set bit, 'x' = don't modify. Underscores can be used for readability. Example "0b0000000000000000000000000000000000000000000000000000000000000001"

  VcpuFeatures:
    type: object
    description: vCPU feature modifier (aarch64)
    required:
      - index
      - bitmap
    properties:
      index:
        type: integer
        format: int32
        description: Index in the kvm_vcpu_init.features array
      bitmap:
        type: string
        description: 32-bit bitmap string defining which bits to modify. Format is "0b" followed by 32 characters where '0' = clear bit, '1' = set bit, 'x' = don't modify. Example "0b00000000000000000000000001100000"

  Drive:
    type: object
    required:
      - drive_id
      - is_root_device
    properties:
      drive_id:
        type: string
      partuuid:
        type: string
        description:
          Represents the unique id of the boot partition of this device. It is
          optional and it will be taken into account only if the is_root_device
          field is true.
      is_root_device:
        type: boolean
      cache_type:
        type: string
        description:
          Represents the caching strategy for the block device.
        enum: ["Unsafe", "Writeback"]
        default: "Unsafe"

      # VirtioBlock specific parameters
      is_read_only:
        type: boolean
        description:
          Is block read only.
          This field is required for virtio-block config and should be omitted for vhost-user-block configuration.
      path_on_host:
        type: string
        description:
          Host level path for the guest drive.
          This field is required for virtio-block config and should be omitted for vhost-user-block configuration.
      rate_limiter:
        $ref: "#/definitions/RateLimiter"
      io_engine:
        type: string
        description:
          Type of the IO engine used by the device. "Async" is supported on
          host kernels newer than 5.10.51.
          This field is optional for virtio-block config and should be omitted for vhost-user-block configuration.
        enum: ["Sync", "Async"]
        default: "Sync"

      # VhostUserBlock specific parameters
      socket:
        type: string
        description:
          Path to the socket of vhost-user-block backend.
          This field is required for vhost-user-block config should be omitted for virtio-block configuration.

  Pmem:
    type: object
    required:
      - id
      - path_on_host
    properties:
      id:
        type: string
        description:
          Identificator for this device.
      path_on_host:
        type: string
        description:
          Host level path for the virtio-pmem device to use as a backing file.
      root_device:
        type: boolean
        description:
          Flag to make this device be the root device for VM boot.
          Setting this flag will fail if there is another device configured to be a root device already.
      read_only:
        type: boolean
        description:
          Flag to map backing file in read-only mode.

  Error:
    type: object
    properties:
      fault_message:
        type: string
        description: A description of the error condition
        readOnly: true

  FullVmConfiguration:
    type: object
    properties:
      balloon:
        $ref: "#/definitions/Balloon"
      drives:
        type: array
        description: Configurations for all block devices.
        items:
          $ref: "#/definitions/Drive"
      boot-source:
        $ref: "#/definitions/BootSource"
      cpu-config:
        $ref: "#/definitions/CpuConfig"
      logger:
        $ref: "#/definitions/Logger"
      machine-config:
        $ref: "#/definitions/MachineConfiguration"
      metrics:
        $ref: "#/definitions/Metrics"
      memory-hotplug:
        $ref: "#/definitions/MemoryHotplugConfig"
      mmds-config:
        $ref: "#/definitions/MmdsConfig"
      network-interfaces:
        type: array
        description: Configurations for all net devices.
        items:
          $ref: "#/definitions/NetworkInterface"
      pmem:
        type: array
        description: Configurations for all pmem devices.
        items:
          $ref: "#/definitions/Pmem"
      vsock:
        $ref: "#/definitions/Vsock"
      entropy:
        $ref: "#/definitions/EntropyDevice"

  InstanceActionInfo:
    type: object
    description:
      Variant wrapper containing the real action.
    required:
      - action_type
    properties:
      action_type:
        description: Enumeration indicating what type of action is contained in the payload
        type: string
        enum:
          - FlushMetrics
          - InstanceStart
          - SendCtrlAltDel

  InstanceInfo:
    type: object
    description:
      Describes MicroVM instance information.
    required:
      - app_name
      - id
      - state
      - vmm_version
    properties:
      app_name:
        description: Application name.
        type: string
      id:
        description: MicroVM / instance ID.
        type: string
      state:
        description:
          The current detailed state (Not started, Running, Paused) of the Firecracker instance.
          This value is read-only for the control-plane.
        type: string
        enum:
          - Not started
          - Running
          - Paused
      vmm_version:
        description: MicroVM hypervisor build version.
        type: string

  Logger:
    type: object
    description:
      Describes the configuration option for the logging capability.
    properties:
      level:
        type: string
        description: Set the level. The possible values are case-insensitive.
        enum: [Error, Warning, Info, Debug, Trace, Off]
        default: Info
      log_path:
        type: string
        description: Path to the named pipe or file for the human readable log output.
      show_level:
        type: boolean
        description: Whether or not to output the level in the logs.
        default: false
      show_log_origin:
        type: boolean
        description: Whether or not to include the file path and line number of the log's origin.
        default: false
      module:
        type: string
        description: The module path to filter log messages by.
        example: api_server::request

  MachineConfiguration:
    type: object
    description:
      Describes the number of vCPUs, memory size, SMT capabilities, huge page configuration and
      the CPU template.
    required:
      - mem_size_mib
      - vcpu_count
    properties:
      cpu_template:
        $ref: "#/definitions/CpuTemplate"
      # gdb_socket_path:
      #   type: string
      #   description: Path to the GDB socket. Requires the gdb feature to be enabled.
      smt:
        type: boolean
        description: Flag for enabling/disabling simultaneous multithreading. Can be enabled only on x86.
        default: false
      mem_size_mib:
        type: integer
        description: Memory size of VM
      track_dirty_pages:
        type: boolean
        description:
          Enable dirty page tracking. If this is enabled, then incremental guest memory
          snapshots can be created. These belong to diff snapshots, which contain, besides
          the microVM state, only the memory dirtied since a previous snapshot. Full snapshots
          each contain a full copy of the guest memory.
        default: false
      vcpu_count:
        type: integer
        minimum: 1
        maximum: 32
        description: Number of vCPUs (either 1 or an even number)
      huge_pages:
        type: string
        enum:
          - None
          - 2M
        description: Which huge pages configuration (if any) should be used to back guest memory.

  MemoryBackend:
    type: object
    required:
      - backend_type
      - backend_path
    properties:
      backend_type:
        type: string
        enum:
          - File
          - Uffd
      backend_path:
        type: string
        description: Based on 'backend_type' it is either
          1) Path to the file that contains the guest memory to be loaded
          2) Path to the UDS where a process is listening for a UFFD initialization
          control payload and open file descriptor that it can use to serve this
          process's guest memory page faults

  Metrics:
    type: object
    description:
      Describes the configuration option for the metrics capability.
    required:
      - metrics_path
    properties:
      metrics_path:
        type: string
        description: Path to the named pipe or file where the JSON-formatted metrics are flushed.

  MmdsConfig:
    type: object
    description:
      Defines the MMDS configuration.
    required:
      - network_interfaces
    properties:
      version:
        description: Enumeration indicating the MMDS version to be configured.
        type: string
        enum:
          - V1
          - V2
        default: V1
      network_interfaces:
        description:
          List of the network interface IDs capable of forwarding packets to
          the MMDS. Network interface IDs mentioned must be valid at the time
          of this request. The net device model will reply to HTTP GET requests
          sent to the MMDS address via the interfaces mentioned. In this
          case, both ARP requests and TCP segments heading to `ipv4_address`
          are intercepted by the device model, and do not reach the associated
          TAP device.
        type: array
        items:
          type: string
      ipv4_address:
        type: string
        format: "169.254.([1-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-4]).([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])"
        default: "169.254.169.254"
        description: A valid IPv4 link-local address.
      imds_compat:
        type: boolean
        description:
          MMDS operates compatibly with EC2 IMDS (i.e. responds "text/plain"
          content regardless of Accept header in requests).
        default: false

  MmdsContentsObject:
    type: object
    description:
      Describes the contents of MMDS in JSON format.
    additionalProperties: true

  NetworkInterface:
    type: object
    description:
      Defines a network interface.
    required:
      - host_dev_name
      - iface_id
    properties:
      guest_mac:
        type: string
      host_dev_name:
        type: string
        description: Host level path for the guest network interface
      iface_id:
        type: string
      rx_rate_limiter:
        $ref: "#/definitions/RateLimiter"
      tx_rate_limiter:
        $ref: "#/definitions/RateLimiter"

  PartialDrive:
    type: object
    required:
      - drive_id
    properties:
      drive_id:
        type: string
      path_on_host:
        type: string
        description:
          Host level path for the guest drive.
          This field is optional for virtio-block config and should be omitted for vhost-user-block configuration.
      rate_limiter:
        $ref: "#/definitions/RateLimiter"

  PartialNetworkInterface:
    type: object
    description:
      Defines a partial network interface structure, used to update the rate limiters
      for that interface, after microvm start.
    required:
      - iface_id
    properties:
      iface_id:
        type: string
      rx_rate_limiter:
        $ref: "#/definitions/RateLimiter"
      tx_rate_limiter:
        $ref: "#/definitions/RateLimiter"

  RateLimiter:
    type: object
    description:
      Defines an IO rate limiter with independent bytes/s and ops/s limits.
      Limits are defined by configuring each of the _bandwidth_ and _ops_ token buckets.
      This field is optional for virtio-block config and should be omitted for vhost-user-block configuration.
    properties:
      bandwidth:
        $ref: "#/definitions/TokenBucket"
        description: Token bucket with bytes as tokens
      ops:
        $ref: "#/definitions/TokenBucket"
        description: Token bucket with operations as tokens

  SnapshotCreateParams:
    type: object
    required:
      - mem_file_path
      - snapshot_path
    properties:
      mem_file_path:
        type: string
        description: Path to the file that will contain the guest memory.
      snapshot_path:
        type: string
        description: Path to the file that will contain the microVM state.
      snapshot_type:
        type: string
        enum:
          - Full
          - Diff
        description:
          Type of snapshot to create. It is optional and by default, a full
          snapshot is created.

  NetworkOverride:
    type: object
    description:
      Allows for changing the backing TAP device of a network interface
      during snapshot restore.
    required:
      - iface_id
      - host_dev_name
    properties:
      iface_id:
        type: string
        description:
          The name of the interface to modify
      host_dev_name:
        type: string
        description:
          The new host device of the interface

  SnapshotLoadParams:
    type: object
    description:
      Defines the configuration used for handling snapshot resume. Exactly one of
      the two `mem_*` fields must be present in the body of the request.
    required:
      - snapshot_path
    properties:
      enable_diff_snapshots:
        type: boolean
        description:
          (Deprecated) Enable dirty page tracking to improve space efficiency of diff snapshots
      track_dirty_pages:
        type: boolean
        description:
          Enable dirty page tracking to improve space efficiency of diff snapshots
      mem_file_path:
        type: string
        description:
          Path to the file that contains the guest memory to be loaded.
          It is only allowed if `mem_backend` is not present. This parameter has
          been deprecated and it will be removed in future Firecracker release.
      mem_backend:
        $ref: "#/definitions/MemoryBackend"
        description:
          Configuration for the backend that handles memory load. If this field
          is specified, `mem_file_path` is forbidden. Either `mem_backend` or
          `mem_file_path` must be present at a time.
      snapshot_path:
        type: string
        description: Path to the file that contains the microVM state to be loaded.
      resume_vm:
        type: boolean
        description:
          When set to true, the vm is also resumed if the snapshot load is successful.
      network_overrides:
        type: array
        description: Network host device names to override
        items:
          $ref: "#/definitions/NetworkOverride"


  TokenBucket:
    type: object
    description:
      Defines a token bucket with a maximum capacity (size), an initial burst size
      (one_time_burst) and an interval for refilling purposes (refill_time).
      The refill-rate is derived from size and refill_time, and it is the constant
      rate at which the tokens replenish. The refill process only starts happening after
      the initial burst budget is consumed.
      Consumption from the token bucket is unbounded in speed which allows for bursts
      bound in size by the amount of tokens available.
      Once the token bucket is empty, consumption speed is bound by the refill_rate.
    required:
      - refill_time
      - size
    properties:
      one_time_burst:
        type: integer
        format: int64
        description: The initial size of a token bucket.
        minimum: 0
      refill_time:
        type: integer
        format: int64
        description: The amount of milliseconds it takes for the bucket to refill.
        minimum: 0
      size:
        type: integer
        format: int64
        description: The total number of tokens this bucket can hold.
        minimum: 0

  Vm:
    type: object
    description:
      Defines the microVM running state. It is especially useful in the snapshotting context.
    required:
      - state
    properties:
      state:
        type: string
        enum:
          - Paused
          - Resumed

  EntropyDevice:
    type: object
    description:
      Defines an entropy device.
    properties:
      rate_limiter:
        $ref: "#/definitions/RateLimiter"

  SerialDevice:
    type: object
    description:
      The configuration of the serial device
    properties:
      serial_out_path:
        type: string
        description: Path to a file or named pipe on the host to which serial output should be written.

  MemoryHotplugConfig:
    type: object
    description:
      The configuration of the hotpluggable memory device (virtio-mem)
    properties:
      total_size_mib:
        type: integer
        description: Total size of the hotpluggable memory in MiB.
      slot_size_mib:
        type: integer
        default: 128
        minimum: 128
        description: Slot size for the hotpluggable memory in MiB. This will determine the granularity of
          hot-plug memory from the host. Refer to the device documentation on how to tune this value.
      block_size_mib:
        type: integer
        default: 2
        minimum: 2
        description: (Logical) Block size for the hotpluggable memory in MiB. This will determine the logical
          granularity of hot-plug memory for the guest. Refer to the device documentation on how to tune this value.

  MemoryHotplugSizeUpdate:
    type: object
    description:
      An update to the size of the hotpluggable memory region.
    properties:
      requested_size_mib:
        type: integer
        description: New target region size.

  MemoryHotplugStatus:
    type: object
    description:
      The status of the hotpluggable memory device (virtio-mem)
    properties:
      total_size_mib:
        type: integer
        description: Total size of the hotpluggable memory in MiB.
      slot_size_mib:
        type: integer
        description: Slot size for the hotpluggable memory in MiB.
      block_size_mib:
        type: integer
        description: (Logical) Block size for the hotpluggable memory in MiB.
      plugged_size_mib:
        type: integer
        description: Plugged size for the hotpluggable memory in MiB.
      requested_size_mib:
        type: integer
        description: Requested size for the hotpluggable memory in MiB.

  FirecrackerVersion:
    type: object
    description:
      Describes the Firecracker version.
    required:
      - firecracker_version
    properties:
      firecracker_version:
        description: Firecracker build version.
        type: string

  Vsock:
    type: object
    description:
      Defines a vsock device, backed by a set of Unix Domain Sockets, on the host side.
      For host-initiated connections, Firecracker will be listening on the Unix socket
      identified by the path `uds_path`. Firecracker will create this socket, bind and
      listen on it. Host-initiated connections will be performed by connection to this
      socket and issuing a connection forwarding request to the desired guest-side vsock
      port (i.e. `CONNECT 52\n`, to connect to port 52).
      For guest-initiated connections, Firecracker will expect host software to be
      bound and listening on Unix sockets at `uds_path_<PORT>`.
      E.g. "/path/to/host_vsock.sock_52" for port number 52.
    required:
      - guest_cid
      - uds_path
    properties:
      guest_cid:
        type: integer
        minimum: 3
        description: Guest Vsock CID
      uds_path:
        type: string
        description: Path to UNIX domain socket, used to proxy vsock connections.
      vsock_id:
        type: string
        description:
          This parameter has been deprecated and it will be removed in future
          Firecracker release.