SimpleVirt API Reference

This is the HTTP API of SimpleVirt-Command, the controller. It is the same API the SimpleVirt-Command web console uses: there is no second, richer interface behind it, and nothing the console can do is unavailable here.

It is written for someone integrating a client — a provisioning system, a monitoring collector, a script — against a running controller. For what the product does and how an operator drives it, see the user guide; for how the pieces fit together, the architecture guide.

Every endpoint in this document was read from the controller's route table. Each one names the privilege it requires, because as of this release every route enforces one server-side — a read included. A client that holds a session but not the privilege gets 403, not data.

Contents

• Base URL and transport
• Authentication
• Request and response conventions
• Authorization
• Preview features
• Stability
• Resources: session · inventory · virtual machines · console · folders · hosts · host hardware · host storage · host networking · clusters · CPU compatibility · high availability · datastores · content library · networking · tasks · events and audit · alarms · metrics · access control · settings · lifecycle · backup · previews
• The host agent API
• Coverage of this document

Base URL and transport

All paths are relative to the controller's HTTPS listener:

https://<simplevirt-command-address>/api/v1/...

TLS is always on. A fresh controller serves a self-signed certificate; an operator can install their own (see controller settings). A client must either trust the installed certificate or pin it — do not disable verification in production code.

Two paths sit outside /api/v1:

Authentication

SimpleVirt-Command uses a session cookie plus a CSRF double-submit token. This is stated once here and is not repeated per endpoint, because it applies to all of them.

1. Sign in.

POST /api/v1/auth/login
Content-Type: application/json

{"username": "alice", "password": "..."}

{"username": "alice", "csrf_token": "…"}

The response also sets the session cookie:

Set-Cookie: simplevirt_command_session=…; Path=/; HttpOnly; Secure; SameSite=Strict

2. Send the cookie on every request. Any client that keeps a cookie jar does this for you.

3. Send the CSRF token on every mutating request. Every POST, PUT, PATCH and DELETE must carry the token from sign-in in a header:

X-CSRF-Token: <csrf_token>

A missing or wrong token is 403 {"error":"invalid or missing CSRF token"}. GET requests carry no CSRF token.

4. Recover the token without re-authenticating — a client that restarted but still holds a valid cookie can re-read its identity, its token and its privilege set from GET /api/v1/auth/me.

Accounts and directories. Sign-in checks the controller's local accounts first, then LDAP/Active Directory when one is configured. Local accounts are the break-glass path and are always admitted; a directory account is admitted only if it, or a group it belongs to, maps to a role. Repeated failures are rate-limited per source address and answer 429.

Sessions expire. An expired or unknown cookie is 401; sign in again. There is no refresh endpoint and no bearer-token or API-key mechanism in this release — a client integrating against SimpleVirt-Command signs in with an account like any other principal. Give it its own account with a role scoped to what it actually needs.

Request and response conventions

• JSON in, JSON out. Send Content-Type: application/json on request bodies. The exceptions are the streaming endpoints, marked where they occur.

• Request bodies are strict. Unknown fields are rejected with 400 {"error":"invalid JSON request body"}. A client must not send fields this version does not define — including ones it saw in a newer release.

• Response objects are not strict. New fields are added over time; ignore what you do not recognise rather than failing on it.

• Errors are always the same shape:

  {"error": "a sentence describing what went wrong"}

  The message is written for a human to read. Do not match on its text.

• Status codes carry the meaning: 400 malformed request, 401 no or expired session, 403 missing privilege, missing or wrong CSRF token, or a disabled preview, 404 unknown object, 409 a conflicting state (already exists, wrong power state, admission control refused), 413 body too large, 429 rate-limited (sign-in), 500 controller fault, 502 the host behind a proxied call could not be reached, 503 a subsystem is not wired on this controller.

• A proxied host's own refusal reaches you intact. Many endpoints under /api/v1/hosts/{id}/... are forwarded to that host. When the host refuses — a datastore is in use, a VM is in the wrong state, a lease fence is held — its status code and its own sentence are what you receive, not a generic controller error. 502 means the controller could not reach the host at all, which is a different problem.

• Timestamps are RFC 3339 strings in UTC unless a field name says otherwise.

• Sizes are bytes, and the field name says so (memory_total_bytes). Memory on VM-shaped objects is mebibytes (memory_mib).

• Identifiers: hosts and clusters carry opaque string ids. Virtual machines are addressed by their libvirt uuid. Datastores are addressed by a stable key (see datastores) — never by name.

• Paging. List endpoints that can grow take ?limit=. Each states its default and cap. There is no cursor paging in this release.

• Treat a missing or null array as empty. Collections are normally serialized as [], but a client that also accepts null will never break on one.

Authorization

Every route is bound to one privilege. Roles are sets of privileges; users and directory groups are bound to roles. A principal whose role does not include the privilege gets:

{"error": "you do not have permission to do this (vm.delete)"}

with status 403. The denial is recorded in the audit log.

The full privilege set:

GET /api/v1/authz/catalog serves this catalog from the controller, so a client never has to hard-code it.

Two endpoints carry no privilege by design, and both are scoped so they can reveal nothing about the fleet: GET /api/v1/auth/me (the caller's own identity — gating it would refuse the very call a zero-privilege principal makes to discover it has no privileges) and GET /api/v1/settings/features (which previews this build offers, which the console must know before its first render).

Preview features

Eight capabilities ship as previews: built, in the binary, and off by default. An endpoint belonging to a disabled preview answers:

{"error": "…", "experimental": "cluster_services"}

with status 403 — distinguishable from a privilege denial by the experimental key. GET /api/v1/settings/features reports which are enabled on this controller. Full detail is in the preview features guide.

Preview endpoints are marked (preview: flag) throughout this reference and are collected in preview feature endpoints. Do not build a client that depends on one without reading that guide first.

Stability

The rule for a client is simple: talk to SimpleVirt-Command, over /api/v1, and nothing else. If an operation appears to need a host directly, it is available on the controller — every host-backed capability is proxied under /api/v1/hosts/{id}/....

Resources

Session and discovery

Inventory and dashboard

Aggregated inventory is read from the controller's poll cache, not from the hosts. A read never blocks on an unreachable host, and objects on a host that has stopped answering are still returned — carried forward from the last successful poll and flagged. This is deliberate: a VM must not appear to vanish because its host went quiet. Two fields tell you what you are looking at:

• stale: true — this reading is a memory, not a measurement.
• host_reachable / host_last_seen — whose memory, and how old.

Treat a stale object as present-but-unconfirmed, and say so to your user.

Virtual machines

GET /api/v1/vms returns one object per VM, deduplicated to exactly one row per UUID even mid-failover:

[
  {
    "uuid": "c0ffee…", "name": "web-01", "state": "running",
    "vcpus": 4, "memory_mib": 8192,
    "persistent": true, "is_template": false, "os_variant": "debian",
    "usage": {"cpu_mhz": 412, "memory_bytes": 5100273664, "storage_bytes": 21474836480},
    "lease_guarded": true,
    "host_id": "h-1", "host_name": "simplevirt-01", "cluster_id": "c-1",
    "folder_id": "f-2",
    "host_reachable": true, "host_liveness": "online"
  }
]

state is one of running, stopped, paused, shutting_down, crashed, suspended, unknown. usage is a live sample and is absent when there is no current reading (a stopped VM, or before the first sample) — absent means unknown, and a client must render it as unknown rather than as zero.

Individual VMs are addressed through their host. {id} is the host id, {uuid} the VM's UUID.

Two guest-side facts on a VM's detail, easily confused. guest_agent is the QEMU guest agent: connected, disconnected, or absent when the VM is stopped or has no agent channel — absent means unknown, not no. It is the single fact that decides what a graceful shutdown can actually do, because without it libvirt presses the virtual ACPI power button and a guest that ignores ACPI (no OS installed yet, a minimal image, a Windows lock screen) simply keeps running. guest_tools is the separate first-party SimpleVirt Guest Tools view: whether simplevirt-guestd is running and, when it is, the guest's own report of its OS, hostname, uptime, capabilities and IP addresses. It is best-effort and absent for a stopped VM. The two coexist and neither implies the other.

configured_vcpus and configured_memory_mib appear only when the persistent config differs from what the guest is currently running — CPU and memory can be changed while a VM runs, and the change takes effect on the next boot. Without these, a just-saved change would look as though it had been silently discarded.

Power actions — the action field takes exactly one of:

Anything else is 400 with the accepted list in the message.

Creating a VM — POST /api/v1/hosts/{id}/vms. The commonly used fields:

{
  "name": "web-01",
  "vcpus": 4, "memory_mib": 8192, "disk_gib": 80,
  "datastore": "shared-nfs", "disk_type": "thin",
  "network": "vm-network",
  "os_variant": "debian",
  "start": true, "autostart": false
}

Install media is attached either as iso (a basename from the host's ISO library) or as iso_datastore + iso_path (a path inside a datastore) — the two are mutually exclusive. A VM can instead be cloned from an existing volume with source_datastore + source_volume, which is how a prepared cloud image is used as a base. cloud_init_user_data and cloud_init_network attach a NoCloud seed for a cloud-init-capable guest. mac fixes the NIC's hardware address when something outside the VM already knows it — a DHCP reservation, a MAC-bound licence — and SimpleVirt does not check it is unique on the network, because it cannot see the network. boot_order takes an ordered list of hd, cdrom, network; cpu_sockets × cpu_cores × cpu_threads must equal vcpus when all three are given; cpu_set pins vCPUs to a host CPU range.

Create is refused with 409 when cluster admission control cannot reserve the capacity — the HA failover reserve is enforced at create and at power-on.

Disks, NICs, media and snapshots

Snapshots are a rollback convenience, not a backup — see backup responsibility.

Migration

All four run as tracked tasks with progress. The call returns once the operation is accepted; watch the task for completion.

Virtual machine console

The console is a two-step, ticketed WebSocket proxy: the controller mints a short-lived ticket bound to your session, the VM and the host, and the browser (or client) then opens the WebSocket with it.

Tickets are single-use and expire in seconds. Both sockets carry a keepalive ping on each leg, so a half-open client tab cannot leak a connection to the host.

Folders

Folders are a controller-side organizational grouping for virtual machines: a flat set of named buckets, not a hierarchy — a folder has no parent and cannot contain another folder. They exist only in the controller and change nothing on any host. Membership is keyed by the VM's UUID, so it survives the VM migrating between hosts.

Hosts

GET /api/v1/hosts returns one object per registered host:

[
  {
    "id": "h-1", "name": "simplevirt-01", "address": "10.0.0.11:8443",
    "cluster_id": "c-1", "cluster_name": "production",
    "status": "online", "liveness": "online", "reachable": true,
    "last_seen": "2026-09-17T09:14:22Z", "info_at": "2026-09-17T09:14:22Z",
    "vms": 12, "vms_running": 9,
    "cpu_cores": 48, "cpu_percent": 18.4,
    "memory_total_bytes": 412316860416, "memory_free_bytes": 180388626432,
    "version": "1.0.0+…", "cpu_model": "…", "domain_type": "kvm",
    "maintenance_mode": false
  }
]

status is connecting, online, degraded or unreachable. While connecting, connect_phase narrates progress (contacting, waiting-agent, cert) without leaking a raw error the operator cannot act on; once a host escalates to unreachable, fail_class, error and terminal say what is wrong and whether it will clear on its own. Capacity fields carry omitempty, so absent means never read — gate them on info_at, not on the value.

Host certificates and identity

The controller pins each host's certificate on first contact and refuses to talk to a changed one. That is the intended behaviour after a certificate is reissued: read the new fingerprint, verify it against the host, then re-pin.

Host hardware, services and time

The subscription is a commercial entitlement, not a software licence, and it gates nothing in the product — see licensing.

Host-local storage and media

These act on one host's view. Fleet-wide and cluster storage is under datastores.

Host networking

Host updates

An image is the only upgrade artifact. Stage first, apply second: applying verifies the staged image before it touches the running system.

Clusters

A cluster object carries pooled cpu_cores, memory_total_bytes, memory_free_bytes, a member-average cpu_percent, and vcpus_provisioned / memory_provisioned_bytes — the configured resources of running VMs on reachable members. Provisioned figures may exceed physical capacity; that excess is the overcommit ratio. A member that could not be read contributes nothing, which makes these a floor rather than a total.

datastores on a cluster object is desired state — what every member is supposed to mount. It says nothing about what any host has actually mounted; that costs a live call per host and lives at GET /api/v1/clusters/{id}/datastores. Do not render the desired list as "the cluster has these datastores".

Cluster storage

Cluster networking

CPU compatibility

A cluster can be given a CPU compatibility profile so a VM started on one member can migrate to any other — the guest is presented a common feature baseline instead of whatever its current host happens to have.

High availability

HA restarts a dead host's VMs on surviving members. It fires only on real host death, never on a planned reboot, and it is gated on a readiness check plus a storage fence — see the operations guide.

These four /api/v1/ha/... endpoints are observability only. Reading them drives no recovery decision; they report transitions the backend has already committed.

Datastores and files

GET /api/v1/datastores returns the fleet's datastores, merged across the hosts that mount them:

{
  "datastores": [
    {
      "key": "ds-a1b2", "id": "a1b2…", "grouped": true,
      "name": "shared-nfs", "type": "nfs", "source": "10.0.0.5:/export/vm",
      "shared": true, "host_count": 3,
      "capacity_bytes": 10995116277760,
      "allocated_bytes": 4398046511104,
      "available_bytes": 6597069766656
    }
  ],
  "hosts": [{"host_id": "h-1", "host_name": "simplevirt-01", "…": "…"}]
}

Two things matter for a client:

• key is the join field. It is the datastore's stable address — the storage-stamped id when the hosts could report one, otherwise a host-private key. Other feeds, notably GET /api/v1/placement, join on key. Never join on name: a datastore can be renamed, and two hosts sharing one datastore can call it different things (names_differ).
• Capacity is one host's report, never a sum. Summing a shared filesystem across the hosts that mount it would multiply one datastore's size by its popularity. grouped: false means the entry describes exactly one host's pool and was not merged with anything.

One HCI datastore

SimpleVirt HCI provisioning creates two storage pools per cluster: an RBD pool that holds VM disks (libvirt name hci-<ceph pool>, for example hci-simplevirt-hci) and a CephFS pool that holds ISOs and other files (hci-fs). Operators see one datastore, named after the Ceph pool (simplevirt-hci). The merge is presentation only, performed by the controller at the very end of GET /api/v1/datastores: no pool, mount path, Ceph object or libvirt name is renamed or moved, and every host's own list (GET /api/v1/hosts/{id}/datastores) stays raw.

A merged row is the RBD member's row plus these additive fields (a row that is not merged carries none of them):

{
  "key": "ceph-rbd:…", "id": "ceph-rbd:…", "name": "hci-simplevirt-hci", "type": "rbd",
  "shared": true, "host_count": 3,
  "capacity_bytes": 161061273600, "allocated_bytes": 32212254720, "available_bytes": 128849018880,
  "composite": true,
  "display_name": "simplevirt-hci",
  "has_disks": true, "has_files": true,
  "disks_name": "hci-simplevirt-hci",
  "files_key": "ceph-fs:…", "files_name": "hci-fs", "files_state": "ok",
  "member_keys": ["ceph-rbd:…", "ceph-fs:…"],
  "members": [
    {"role": "disks", "key": "ceph-rbd:…", "id": "ceph-rbd:…", "name": "hci-simplevirt-hci", "type": "rbd",
     "keys": ["ceph-rbd:…"], "hosts_present": 3, "hosts_active": 3, "hosts_expected": 3, "state": "ok"},
    {"role": "files", "key": "ceph-fs:…", "id": "ceph-fs:…", "name": "hci-fs", "type": "cephfs",
     "keys": ["ceph-fs:…"], "hosts_present": 3, "hosts_active": 3, "hosts_expected": 3, "state": "ok"}
  ],
  "hosts": [
    {"host_id": "…", "host_name": "…", "name": "hci-simplevirt-hci", "role": "disks", "active": true, "…": "…"},
    {"host_id": "…", "host_name": "…", "name": "hci-fs", "role": "files", "active": true, "target_path": "/var/lib/simplevirt-hcifs", "…": "…"}
  ]
}

• key, id and type are the RBD member's, so every existing join (the placement feed, a VM disk's recorded datastore, HA, deep links, #/storage/datastore/<key> bookmarks) keeps working. name stays the RBD libvirt pool name; show display_name when present. member_keys lists every key that resolves to this datastore (the RBD key, the CephFS key, and the host-private local: keys of inactive member pools), so a link made against any of them still resolves.
• hosts carries one entry per (host, member), and host_count counts distinct hosts. Each entry has role ("disks" for the RBD pool, "files" for the CephFS pool; the field exists only on a composite's entries), the pool's own libvirt name on that host, and its own active flag, so a console can say which host lacks WHICH pool. An inactive member pool has no identity; its host is folded in as an entry with active: false (and counted in members[].hosts_present versus hosts_active), never shown as a third row and never counted in host_count: a host that has only inactive pools is listed, not counted.
• members[].keys is every key a VM disk of that member may be recorded under: the member's own key plus the host-private local: keys of its absorbed inactive pools. It is always an array, never null; the members' keys together are exactly member_keys.
• Capacity is the RBD member's usable figure only (ceph df), never a sum with — and never a fallback to — the CephFS filesystem figures, which an unmounted host fills with a bare local directory's.
• All file operations use files_key, not key: browse, upload, mkdir, download and delete go to /api/v1/datastores/{files_key}/…. VM disks are created on key. The value an ISO picker sends as the datastore is files_name (hci-fs).
• files_state is ok (the files pool is active on every member host), partial (not active everywhere, including a pool that is defined but down on every host), absent (no file member at all) or unknown (a host of the cluster could not be read, so neither "ok" nor "absent" can be claimed). members[].state is ok, partial, inactive, absent or unknown on the same terms.
• When rows are NOT merged. Rows fold only within one registry cluster, only when the cluster has exactly one RBD identity (one Ceph pool name) and at most one CephFS identity, only when the CephFS pool is mounted at the fixed HCI path (an operator's own CephFS pool elsewhere is never swallowed), and never when the two report different Ceph cluster ids. Any ambiguity leaves today's separate rows. A cluster with only an RBD pool is a composite with has_files: false; one with only a CephFS pool is a single row named after the file member with has_disks: false. When the RBD pool is inactive on every host it has no identity, so nothing is merged: the rows stay exactly as before the merge existed (never a files-only composite beside phantom block rows).
• ?flat=1 returns the unmerged list (one row per storage identity, as before). The response's hosts[] status entries additionally carry cluster_id.

On GET /api/v1/hosts/{id}/datastores, the entries that belong to an HCI pair are annotated additively with hci_role ("disks" for the RBD pool, "files" for the CephFS pool) and hci_name (the logical name). Both fields are omitted for every other entry, and no entry is merged, renamed or dropped.

DELETE /api/v1/hosts/{id}/datastores/{name} is refused with 409 ("This is SimpleVirt HCI storage. Manage or remove it from the SimpleVirt HCI tab.") for the RBD pool and the CephFS files pool, by both the controller and the host. NFS, local-directory and default-pool rules are unchanged. The host's datastore in-use check now also counts a VM whose disk is an RBD network disk in the pool's Ceph pool.

Content library

The content library is the catalog of base images, ISOs and templates that VM creation and provisioning deploy from. It is backed by a shared datastore so items stay reachable cluster-wide.

The "ISO (install media)" item type is behind the library_iso_items preview: no code in this release can mount a library ISO into a VM, so importing one produces a catalog row and nothing more. See preview features.

Fleet networking

Per-host and per-cluster network mutation is under host networking and cluster networking.

Tasks

Every mutating operation the controller performs runs as a task with a durable record, so the list survives a page reload and shows work started by other operators and by the controller itself.

A task record:

{
  "id": "t-9", "task": "Migrate virtual machine", "target": "web-01",
  "target_kind": "vm", "host_id": "h-1", "initiator": "alice",
  "started": "2026-09-17T09:14:22Z", "finished": null,
  "status": "running", "progress": 42, "detail": "42% · 1.2 GiB left"
}

progress is absent for work with no measurable progress. target_kind is vm, host, cluster, datastore and so on. Prefer the stream: a long migration's real percent ticks at the host's cadence rather than aliasing to your poll interval, and a client that cannot hold the stream open still has GET /api/v1/tasks.

Events and audit

Three distinct feeds, easily confused:

Alarms

Alarms are computed conditions — capacity thresholds, unreachable hosts, degraded storage, network-health rollups — that persist until the condition clears.

Acknowledging does not clear an alarm — only the condition going away does that, so an acknowledgement can never be mistaken for a fix. The notifications block reports whether a webhook receiver is configured and whether deliveries are being dropped; it never carries the endpoint URL or its secret.

Utilization metrics

Retained server-side history, so a client gets a series rather than a single live sample.

The live per-VM sample also rides the inventory poll, as usage on each object in GET /api/v1/vms — no extra request needed for a current reading.

Access control

Access control is default-deny: a principal with no binding has no privileges. The controller keeps at least one administrator binding at all times, so it cannot be locked out of itself. Local accounts remain the break-glass path — a directory outage never strands the controller.

Controller settings

Lifecycle and updates

Host-side staging and apply are under host updates.

Backup, restore and support

This backs up the controller, not your virtual machines. What SimpleVirt protects and what you must protect yourself is set out in backup responsibility.

SimpleVirt HCI storage endpoints

SimpleVirt HCI is a supported, always-on storage tier — these endpoints are not gated by a preview flag and never answer 403 {"experimental": …}. (The …-preview paths are dry-run cost previews of a destructive operation, not experimental features.)

HCI status envelope

Everything below is additive: an older controller simply omits it, and clients must tolerate its absence. GET /api/v1/clusters/{id}/hci/status is served from the background-sampled cache, never a live storage call.

Virtual Objects

GET /api/v1/clusters/{id}/hci/objects answers from a cache (collecting: true on the very first read, while the reading is taken in the background). It carries as_of, age_seconds, stale, source_host, objects_supported (false, with unsupported_hosts, when members run a SimpleVirt without the read), partial (sub-reads that failed), refresh_error, and:

• owners {complete, reason}: an image is reported unattached only when every cluster host is reachable and every VM's state is known; otherwise its owner_state is unknown.
• datastores[] {kind, label, pools, compliance, reason, copies, min_copies, failure_domain, host_separated, below_recommended}: host_separated is the LIVE fact "enough healthy hosts right now", not the pool's policy (failure_domain is).
• objects[] {id, kind (disk|files), name, pool, image, size_bytes, owner {vm_uuid, vm_name, host_id, host_name, state}|null, owner_state (known|unattached|unknown), datastore, compliance (compliant|reconciling|reduced|inaccessible|unknown), reason, expected, expected_why}. An image is striped over about every placement group of its pool, so its compliance is its pool's. expected is true only while the whole picture is planned maintenance.
• pools[], hosts[] {host, state (online|maintenance|down), kind, since, osds} and separation.

GET /api/v1/clusters/{id}/hci/objects/placement?pool=&image= returns one disk's sampled placement (hosts, sites, copies, min_copies, health, pool_compliance); 409 while the inventory is still being collected, 404 for a disk not in it. POST /api/v1/clusters/{id}/hci/retest returns {tested_at, took_ms, throttled?, objects_error?}.

HCI safety refusals and previews

A destructive storage change is refused, with a plain reason, while a member is in a fresh planned window (operator Maintenance Mode or an armed planned reboot/update): raising protection (protection/remediate, and any provisioning step that changes an existing pool's replication) answers 409; removing a disk or decommissioning a host answers 409 (and the preview shows a blocking Maintenance check). A member that no longer explains anything — in maintenance over 24 hours, silent longer than the anti-strand window, or whose restart did not finish cleanly — does not block; the previews list it as a warn Maintenance check instead, and the operation's own target host never blocks itself. Raising protection is also refused whenever the LIVE status shows a disk down, any group not active and clean, or no health reading, whatever an older placement reading says.

GET /api/v1/hosts/{id}/maintenance/preview gains, inside storage, source (snapshot | live | estimate; an estimate never says ok), label (plain provenance such as "as of 12s ago"), blockers (the gate's reasons), and affected_disks / affected_vms (what would stop serving I/O). The host's own gate now also refuses (overridable with force, like every other refusal) when the cluster's disk layout could not be read.

Preview feature endpoints

Each group below answers 403 with {"experimental": "<flag>"} unless its flag is enabled on the controller. Read preview features before integrating against any of them.

Kubernetes (preview: kubernetes)

The last two hand back credentials, which is why they require admin.users and not vm.view — a read privilege that lets a viewer see a cluster must not also hand them its administrative key.

Stretched cluster

These endpoints need no experimental flag — the stretched cluster has graduated out of the preview gate. Safety is unchanged: enable runs a fail-closed readiness gate and refuses on any cluster that is not a genuine two-site topology with a witness. Full two-datacenter hardware validation is pending — see SIMPLEVIRT_STRETCHED_CLUSTER.md.

Workload distributor

Graduated out of preview — these routes need no flag. The distributor defaults to recommend-only, and every move it applies passes the same fail-closed migration precheck a manual live-migration does.

File services (preview: file_services)

Cluster services (preview: cluster_services)

Block datastores (preview: block_datastores)

This preview gates a type, not a path. POST /api/v1/hosts/{id}/datastores refuses an iSCSI or Fibre Channel datastore unless the flag is on; every other datastore type is unaffected.

The host agent API

Each SimpleVirt host runs simplevirtd, which serves its own HTTP API on three surfaces. None of them is a client integration surface. They are documented here so that a reader who finds them on the wire knows what they are and why not to call them.

Everything a client legitimately needs from a host is already proxied by the controller under /api/v1/hosts/{id}/..., with the controller's privilege model applied and the action recorded in the audit log. Calling a host directly bypasses both. Use the controller.

Coverage of this document

Every route registered by SimpleVirt-Command appears in exactly one section above: 216 paths under /api/v1, plus /healthz and the console catch-all — 218 registrations in total. There is no separate flat index, deliberately: a second copy of the route table is a second thing to keep true.

Two things are stated once rather than per endpoint, and apply everywhere:

1. Authentication — session cookie on everything, X-CSRF-Token on every mutating request. See authentication.
2. Errors — {"error": "…"} with a meaningful status code. See conventions.

Where an endpoint's request or response shape is not obvious from its name, it is described in its section. Where it is obvious — a list endpoint returning the objects it lists — it is not padded out.