Documentation > API > Air-Gap

Air-Gap API

Endpoint reference for moving package and repository data into and out of disconnected (air-gapped) environments. Covers the collector that builds signed ISOs, the bundle builder, repository mirroring, removable-device ingest, and the trusted-key keyrings that establish trust between a collector and a repository. All endpoints require Bearer-token auth except the explicitly token-authenticated download streams noted below.

Collector Schedules

Recurring collection jobs that build signed ISOs on a cron-style cadence. The tick endpoint is the driver hook an external scheduler calls to fire any schedules that are due.

  • GET /api/v1/airgap/collector/schedules — list all collection schedules
  • POST /api/v1/airgap/collector/schedules — create a new collection schedule
  • GET /api/v1/airgap/collector/schedules/{schedule_id} — get a specific schedule
  • PUT /api/v1/airgap/collector/schedules/{schedule_id} — update a schedule
  • DELETE /api/v1/airgap/collector/schedules/{schedule_id} — delete a schedule
  • POST /api/v1/airgap/collector/schedules/tick — driver hook; fire all due schedules

Collector Runs

One-shot collection runs. A run produces one or more disc ISOs and a set of signed manifests. ISOs can be streamed with header auth, or downloaded natively via a short-lived minted token so a browser or native tool can pull the stream without a Bearer header.

  • POST /api/v1/airgap/collector/runs — create a one-shot collection run
  • GET /api/v1/airgap/collector/runs — list collection runs (newest first)
  • GET /api/v1/airgap/collector/runs/{run_id} — get a run's status
  • GET /api/v1/airgap/collector/runs/{run_id}/discs — list disc ISOs for multi-disc runs
  • GET /api/v1/airgap/collector/runs/{run_id}/iso — stream the run ISO (header-authenticated)
  • POST /api/v1/airgap/collector/runs/{run_id}/iso-token — mint a token for native ISO download
  • GET /api/v1/airgap/collector/runs/{run_id}/iso-download — stream the run ISO (token-authenticated)
  • DELETE /api/v1/airgap/collector/runs/{run_id} — delete a run and its data
  • GET /api/v1/airgap/collector/runs/{run_id}/manifests — list signed manifests for a run
  • GET /api/v1/airgap/collector/manifests/{manifest_id}/download — stream the signed ISO referenced by a manifest

Air-Gap Bundles

The bundle builder produces a self-contained ISO for installing or updating a fully disconnected server. Build jobs run in Docker and return a job ID; resource and Docker readiness can be checked before kicking off a build. Like collector runs, the ISO can be streamed with header auth or via a minted download token.

  • GET /api/airgap-bundles/docker-status — check Docker installation and readiness
  • GET /api/airgap-bundles/resource-status — check RAM, swap, and disk for a build
  • POST /api/airgap-bundles — trigger a new bundle build (returns a job ID)
  • GET /api/airgap-bundles — list all bundles (newest first)
  • GET /api/airgap-bundles/{bundle_id} — get a bundle's status
  • GET /api/airgap-bundles/{bundle_id}/download — stream the bundle ISO (header-authenticated)
  • POST /api/airgap-bundles/{bundle_id}/download-token — mint a token for native ISO download
  • GET /api/airgap-bundles/{bundle_id}/download-stream — stream the bundle ISO (token-authenticated)
  • DELETE /api/airgap-bundles/{bundle_id} — remove the bundle and its on-disk artifacts

Device Import

On the repository (disconnected) side, ISOs arrive on removable media. These endpoints enumerate candidate drives, persist the chosen import device, probe its readiness, and queue ingest of its contents into the repository.

  • GET /api/v1/airgap/block-devices — enumerate candidate import drives
  • PUT /api/v1/airgap/import-device — persist the chosen import drive (or clear it)
  • GET /api/v1/airgap/import-device/status — probe device readiness for import
  • POST /api/v1/airgap/repository/ingest-device — queue ingest from the selected drive
  • GET /api/v1/airgap/repository/ingest-runs — list recent ingestion runs

Repository Status

Read-only views of repository state: per-host compliance buckets that classify packages by transfer/apply status, the list of mirrored repositories with their freshness, and a global freshness label for the air-gapped mirror set.

  • GET /api/v1/airgap/repository/host/{host_id}/compliance-buckets — classify packages (not_applied / not_transferred / current)
  • GET /api/v1/airgap/repository/repositories — list air-gap repositories with freshness
  • GET /api/v1/airgap/repository/freshness — global air-gap mirror freshness label

Trusted Keys

Trust between a collector and a repository is established by exchanging public keys. The repository side imports collector public keys into its trusted keyring; signed ISOs are only accepted from trusted collectors.

  • GET /api/v1/airgap/collector-key — get this server's collector public key and fingerprint
  • GET /api/v1/airgap/trusted-collectors — list trusted collector keys
  • POST /api/v1/airgap/trusted-collectors — import a collector public key
  • DELETE /api/v1/airgap/trusted-collectors/{name} — remove a trusted collector key

Repository Mirroring

Local mirrors of upstream package repositories, with snapshot/restore and per-platform configuration. The tick endpoint is the cron driver hook that fires any mirrors due for sync; the setup-status and setup-install endpoints detect and install the mirror tooling on a target host. Endpoints carry the /api prefix directly rather than a versioned path.

  • GET /api/mirror-repositories — list mirrors (optionally by platform_config_id)
  • POST /api/mirror-repositories — create a mirror
  • GET /api/mirror-repositories/{mirror_id} — get a mirror
  • PUT /api/mirror-repositories/{mirror_id} — update a mirror
  • DELETE /api/mirror-repositories/{mirror_id} — delete a mirror
  • POST /api/mirror-repositories/{mirror_id}/sync — fire a sync immediately
  • POST /api/mirror-repositories/{mirror_id}/snapshot — take a snapshot
  • POST /api/mirror-repositories/{mirror_id}/restore/{snapshot_id} — restore from a snapshot
  • GET /api/mirror-repositories/{mirror_id}/snapshots — list snapshots for a mirror
  • POST /api/mirror-repositories/tick — cron driver hook; fire due syncs
  • GET /api/settings/mirror / PUT /api/settings/mirror — singleton mirror settings
  • GET /api/mirror-repositories/setup-status/{host_id} — mirror tool detection status
  • POST /api/mirror-repositories/setup-status/{host_id}/refresh — queue a tool-presence probe
  • POST /api/mirror-repositories/setup-install/{host_id} — queue mirror-tools install
  • GET /api/mirror-platform-configs / POST /api/mirror-platform-configs — platform config list / upsert
  • GET /api/mirror-platform-configs/{cfg_id} / PUT / DELETE — platform config read / update / delete
  • GET /api/mirror-known-versions — list known OS versions (optionally by platform)
  • GET /api/host-defaults/mirrors — list default mirror assignments per (platform, version, os_family)
  • PUT /api/host-defaults/mirrors/{platform}/{version_key}/{os_family} — assign / unassign a default mirror