The Vm API from Firecracker — 2 operation(s) for vm.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/firecracker-vm-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Firecracker Actions Vm 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.16.0-dev
termsOfService: ''
contact:
email: firecracker-maintainers@amazon.com
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: http://localhost/
tags:
- name: Vm
paths:
/vm:
patch:
summary: Updates the microVM state.
description: Sets the desired state (Paused or Resumed) for the microVM.
operationId: patchVm
responses:
204:
description: Vm state updated
400:
description: Vm state cannot be updated due to bad input
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
default:
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
tags:
- Vm
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Vm'
description: The microVM state
required: true
/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
content:
application/json:
schema:
$ref: '#/components/schemas/FullVmConfiguration'
default:
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
tags:
- Vm
components:
schemas:
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.
EntropyDevice:
type: object
description: Defines an entropy device.
properties:
rate_limiter:
$ref: '#/components/schemas/RateLimiter'
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: '#/components/schemas/CpuidRegisterModifier'
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"
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.
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: '#/components/schemas/TokenBucket'
description: Token bucket with bytes as tokens
ops:
$ref: '#/components/schemas/TokenBucket'
description: Token bucket with operations as tokens
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.
rate_limiter:
$ref: '#/components/schemas/RateLimiter'
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
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
FullVmConfiguration:
type: object
properties:
balloon:
$ref: '#/components/schemas/Balloon'
drives:
type: array
description: Configurations for all block devices.
items:
$ref: '#/components/schemas/Drive'
boot-source:
$ref: '#/components/schemas/BootSource'
cpu-config:
$ref: '#/components/schemas/CpuConfig'
logger:
$ref: '#/components/schemas/Logger'
machine-config:
$ref: '#/components/schemas/MachineConfiguration'
metrics:
$ref: '#/components/schemas/Metrics'
memory-hotplug:
$ref: '#/components/schemas/MemoryHotplugConfig'
mmds-config:
$ref: '#/components/schemas/MmdsConfig'
network-interfaces:
type: array
description: Configurations for all net devices.
items:
$ref: '#/components/schemas/NetworkInterface'
pmem:
type: array
description: Configurations for all pmem devices.
items:
$ref: '#/components/schemas/Pmem'
vsock:
$ref: '#/components/schemas/Vsock'
entropy:
$ref: '#/components/schemas/EntropyDevice'
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
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
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: '#/components/schemas/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
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.
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
- false
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
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: '#/components/schemas/RateLimiter'
tx_rate_limiter:
$ref: '#/components/schemas/RateLimiter'
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"
Error:
type: object
properties:
fault_message:
type: string
description: A description of the error condition
readOnly: true
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"
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"
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.
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.
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: '#/components/schemas/CpuTemplate'
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.
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: '#/components/schemas/CpuidLeafModifier'
msr_modifiers:
type: array
description: A collection of model specific register modifiers (x86_64 only)
items:
$ref: '#/components/schemas/MsrModifier'
reg_modifiers:
type: array
description: A collection of register modifiers (aarch64 only)
items:
$ref: '#/components/schemas/ArmRegisterModifier'
vcpu_features:
type: array
description: A collection of vCPU features to be modified (aarch64 only)
items:
$ref: '#/components/schemas/VcpuFeatures'
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