The Balloon API from Firecracker — 5 operation(s) for balloon.
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-balloon-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 Balloon 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: Balloon
paths:
/balloon:
get:
summary: Returns the current balloon device configuration.
operationId: describeBalloonConfig
responses:
200:
description: The balloon device configuration
content:
application/json:
schema:
$ref: '#/components/schemas/Balloon'
400:
description: Balloon device not configured.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
default:
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
tags:
- Balloon
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
responses:
204:
description: Balloon device created/updated
400:
description: Balloon device cannot be created/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:
- Balloon
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Balloon'
description: Balloon properties
required: true
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
responses:
204:
description: Balloon device updated
400:
description: Balloon device 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:
- Balloon
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BalloonUpdate'
description: Balloon properties
required: true
/balloon/statistics:
get:
summary: Returns the latest balloon device statistics, only if enabled pre-boot.
operationId: describeBalloonStats
responses:
200:
description: The balloon device statistics
content:
application/json:
schema:
$ref: '#/components/schemas/BalloonStats'
400:
description: The balloon device statistics were not enabled when the device was configured.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
default:
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
tags:
- Balloon
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
responses:
204:
description: Balloon statistics interval updated
400:
description: Balloon statistics interval 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:
- Balloon
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BalloonStatsUpdate'
description: Balloon properties
required: true
/balloon/hinting/start:
patch:
summary: Starts a free page hinting run only if enabled pre-boot.
operationId: startBalloonHinting
responses:
200:
description: Free page hinting run started.
400:
description: The balloon free hinting was not enabled when the device was configured.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
default:
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
tags:
- Balloon
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BalloonStartCmd'
description: When the device completes the hinting whether we should automatically ack this.
/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
content:
application/json:
schema:
$ref: '#/components/schemas/BalloonHintingStatus'
400:
description: The balloon free hinting was not enabled when the device was configured.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
default:
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
tags:
- Balloon
/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.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
default:
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
tags:
- Balloon
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.
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
BalloonUpdate:
type: object
required:
- amount_mib
description: Balloon device descriptor.
properties:
amount_mib:
type: integer
description: Target balloon size in MiB.
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.
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
Error:
type: object
properties:
fault_message:
type: string
description: A description of the error condition
readOnly: true