**Language / Язык:** [English](api-versions.md) | [Русский](ru/api-versions.md)

# API versions (vSphere catalog majors 6–9)

The Web UI and evidence/compatibility reports browse four integer **catalog
majors** that map onto vSphere Automation API label floors:

| Major | vSphere label | Contract version string |
|---|---|---|
| 6 | 7.0 | `7.0.0` |
| 7 | 7.0 U3 | `7.0.3` |
| 8 | 8.0 | `8.0.0` |
| 9 | 8.0 U2 (Automation 9.1 surface) | `8.0.2` |

Definitions live in [`app/vsphere/contracts/matrix.py`](../app/vsphere/contracts/matrix.py)
(`VERSIONS`, `PATH_FLOOR`). Each registered REST path has a **floor** — the
lowest major at which it appears in the catalog — sourced from the same
module. Undated paths default to the highest major (9) until catalogued.

## Runtime vs catalog

This is the most important distinction in the project:

- **Catalog major** — controls what the Web UI endpoint tree, `/ui/api/catalog`,
  and compatibility/evidence reports show for a given major.
- **Runtime surface** — the simulator always serves the **full registered
  route table** with deep handlers or DB-backed stubs, independent of the
  active catalog major. A known path is never returned as HTTP 501 because of
  a version floor.

Hot-swapping the catalog major is therefore a **documentation/browse**
switch, not a compatibility gate on live traffic. See
[`available_for_request()`](../app/vsphere/contracts/matrix.py) for the exact
policy.

## Cold start

`GET /api/appliance/system/version` reports the version string of the
currently selected runtime source (defaults to `8.0.2` / major 9 unless the
process overrides `app.state.runtime_source_version`).

## Hot-swap (catalog browse)

Browse any major in the Web UI catalog, or call:

```http
POST /ui/api/contract/apply?major=7
```

Effects:

- The Web UI catalog, `/ui/api/compatibility`, and evidence reports switch to
  major 7's floor and ledger (`evidence/vsphere-7.0.3.json`).
- The change is **process-local** and **not persisted**; a restart returns to
  the default (major 9).
- REST/SOAP routes already registered continue to answer with their real
  handlers regardless of the applied major.

### Client guidance

- Most clients (pyvmomi, govmomi, Terraform, Pulumi, Ansible `uri`) do not
  need to pin a catalog major — the runtime surface does not change shape
  based on it.
- Use catalog majors when you specifically want the Web UI / evidence view to
  reflect an older vSphere label for documentation or screenshots.
- After apply, re-check `/ui/api/compatibility?major=N` for the active
  catalog state.

## Regenerating catalog artifacts

```bash
make vsphere-bundles     # stub OpenAPI matrices + evidence ledgers
make vsphere-universe    # regenerate universe.json from the Broadcom operations index
make evidence            # regenerate per-major verified surface evidence ledgers
```

See [API surface](api-surface.md) and [Compatibility](compatibility.md).