API reference

Give operators and AI a normalized view of the fleet

Read capacity, failures and event feedback, then request a placement plan without silently scheduling a machine.

Normalized host state

GET /v1/host/state

Describes memory tiers such as DRAM, zram-compressed memory and KSM, along with storage pools, disks and GPUs.

Fleet snapshot

GET /v1/fleet/state

Returns this computer and its known computers in one snapshot. An unavailable computer is marked down rather than removed, preventing absence from being mistaken for deletion.

Event feedback loop

GET /v1/host/events?since=<seq> reads a typed audit stream forward from a cursor. GET /v1/fleet/events?since=<cursor> merges fleet events by time while retaining per-host cursors. Both require audit permission.

Placement is a plan

GET /v1/fleet/placements?mem_mb=&vcpu=&disk_gb=&gpu=

The pool-first scheduler returns its preferred computer and pool, its reasoning and why candidates were ruled out. It does not create or move a machine.

Reason over a changing world

Fleet snapshots carry a monotonic generation. An automation client should refresh before acting, state its expected machine state and treat a stale plan as evidence to reconsider—not as authority to force a change.