From b32841743f9918449a04627827c0269f6092fae5 Mon Sep 17 00:00:00 2001
From: iliana etaoin <iliana@oxide.computer>
Date: Wed, 6 Aug 2025 17:59:01 +0000
Subject: [PATCH 01/12] openapi-manager: explain the warnings a bit more

---
 .../openapi-manager/src/spec_files_generic.rs | 37 ++++++++++++-------
 1 file changed, 23 insertions(+), 14 deletions(-)

diff --git a/dev-tools/openapi-manager/src/spec_files_generic.rs b/dev-tools/openapi-manager/src/spec_files_generic.rs
index f3f616d07bf..d9b227450b4 100644
--- a/dev-tools/openapi-manager/src/spec_files_generic.rs
+++ b/dev-tools/openapi-manager/src/spec_files_generic.rs
@@ -400,23 +400,32 @@ impl<'a, T: ApiLoad + AsRawFiles> ApiSpecFilesBuilder<'a, T> {
         basename: &str,
     ) -> Option<ApiSpecFileName> {
         match ApiSpecFileName::parse_lockstep(&self.apis, basename) {
-            Err(
-                warning @ (BadLockstepFileName::NoSuchApi
-                | BadLockstepFileName::NotLockstep),
-            ) if T::MISCONFIGURATIONS_ALLOWED => {
-                // When we're looking at the blessed files, the caller provides
-                // `misconfigurations_okay: true` and we treat these as
-                // warnings because the configuration for an API may have
-                // changed between the blessed files and the local changes.
-                //
-                // - NoSuchApi: somebody is deleting an API locally
-                // - NotLockstep: somebody is converting a lockstep API to a
-                //   versioned one
-                let warning = anyhow!(warning)
-                    .context(format!("skipping file {:?}", basename));
+            // When we're looking at the blessed files, the caller provides
+            // `misconfigurations_okay: true` and we treat these as
+            // warnings because the configuration for an API may have
+            // changed between the blessed files and the local changes.
+            Err(warning @ BadLockstepFileName::NoSuchApi)
+                if T::MISCONFIGURATIONS_ALLOWED =>
+            {
+                let warning = anyhow!(
+                    "skipping file {basename:?}: {warning} \
+                    (this is expected if you are deleting an API)"
+                );
                 self.load_warning(warning);
                 None
             }
+            Err(warning @ BadLockstepFileName::NotLockstep)
+                if T::MISCONFIGURATIONS_ALLOWED =>
+            {
+                let warning = anyhow!(
+                    "skipping file {basename:?}: {warning} \
+                    (this is expected if you are converting \
+                    a lockstep API to a versioned one)"
+                );
+                self.load_warning(warning);
+                None
+            }
+
             Err(warning @ BadLockstepFileName::MissingJsonSuffix) => {
                 // Even if the caller didn't provide `problems_okay: true`, it's
                 // not a big deal to have an extra file here.  This could be an

From 44eb1e6dffa7412c749353c051da9f8acfa8598b Mon Sep 17 00:00:00 2001
From: iliana etaoin <iliana@oxide.computer>
Date: Wed, 6 Aug 2025 18:09:55 +0000
Subject: [PATCH 02/12] cockroach-admin: versionify

---
 Cargo.lock                                    |  2 ++
 clients/cockroach-admin-client/src/lib.rs     |  2 +-
 cockroach-admin/api/Cargo.toml                |  2 ++
 cockroach-admin/api/src/lib.rs                | 30 +++++++++++++++++++
 dev-tools/openapi-manager/src/omicron.rs      |  4 ++-
 .../cockroach-admin-1.0.0-dc9acb.json}        |  2 +-
 .../cockroach-admin-latest.json               |  1 +
 7 files changed, 40 insertions(+), 3 deletions(-)
 rename openapi/{cockroach-admin.json => cockroach-admin/cockroach-admin-1.0.0-dc9acb.json} (99%)
 create mode 120000 openapi/cockroach-admin/cockroach-admin-latest.json

diff --git a/Cargo.lock b/Cargo.lock
index 4ba1e607d32..a70beddd1c6 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -1607,7 +1607,9 @@ dependencies = [
  "omicron-common",
  "omicron-uuid-kinds",
  "omicron-workspace-hack",
+ "openapi-manager-types",
  "schemars",
+ "semver 1.0.26",
  "serde",
 ]
 
diff --git a/clients/cockroach-admin-client/src/lib.rs b/clients/cockroach-admin-client/src/lib.rs
index bf007b5f146..02edf2e6248 100644
--- a/clients/cockroach-admin-client/src/lib.rs
+++ b/clients/cockroach-admin-client/src/lib.rs
@@ -5,7 +5,7 @@
 //! Interface for making API requests to an Omicron CockroachDB admin server
 
 progenitor::generate_api!(
-    spec = "../../openapi/cockroach-admin.json",
+    spec = "../../openapi/cockroach-admin/cockroach-admin-latest.json",
     interface = Positional,
     inner_type = slog::Logger,
     pre_hook = (|log: &slog::Logger, request: &reqwest::Request| {
diff --git a/cockroach-admin/api/Cargo.toml b/cockroach-admin/api/Cargo.toml
index da2b9404082..09852b45ef4 100644
--- a/cockroach-admin/api/Cargo.toml
+++ b/cockroach-admin/api/Cargo.toml
@@ -14,5 +14,7 @@ http.workspace = true
 omicron-common.workspace = true
 omicron-uuid-kinds.workspace = true
 omicron-workspace-hack.workspace = true
+openapi-manager-types.workspace = true
 schemars.workspace = true
+semver.workspace = true
 serde.workspace = true
diff --git a/cockroach-admin/api/src/lib.rs b/cockroach-admin/api/src/lib.rs
index 18b51ac183c..942bb39aa3c 100644
--- a/cockroach-admin/api/src/lib.rs
+++ b/cockroach-admin/api/src/lib.rs
@@ -8,9 +8,39 @@ use dropshot::{
     TypedBody,
 };
 use omicron_uuid_kinds::OmicronZoneUuid;
+use openapi_manager_types::{
+    SupportedVersion, SupportedVersions, api_versions,
+};
 use schemars::JsonSchema;
 use serde::{Deserialize, Serialize};
 
+api_versions!([
+    // WHEN CHANGING THE API (part 1 of 2):
+    //
+    // +- Pick a new semver and define it in the list below.  The list MUST
+    // |  remain sorted, which generally means that your version should go at
+    // |  the very top.
+    // |
+    // |  Duplicate this line, uncomment the *second* copy, update that copy for
+    // |  your new API version, and leave the first copy commented out as an
+    // |  example for the next person.
+    // v
+    // (next_int, IDENT),
+    (1, INITIAL),
+]);
+
+// WHEN CHANGING THE API (part 2 of 2):
+//
+// The call to `api_versions!` above defines constants of type
+// `semver::Version` that you can use in your Dropshot API definition to specify
+// the version when a particular endpoint was added or removed.  For example, if
+// you used:
+//
+//     (2, ADD_FOOBAR)
+//
+// Then you could use `VERSION_ADD_FOOBAR` as the version in which endpoints
+// were added or removed.
+
 #[dropshot::api_description]
 pub trait CockroachAdminApi {
     type Context;
diff --git a/dev-tools/openapi-manager/src/omicron.rs b/dev-tools/openapi-manager/src/omicron.rs
index 8b446099b71..6135cc3600f 100644
--- a/dev-tools/openapi-manager/src/omicron.rs
+++ b/dev-tools/openapi-manager/src/omicron.rs
@@ -69,7 +69,9 @@ pub fn all_apis() -> Vec<ManagedApiConfig> {
         },
         ManagedApiConfig {
             title: "CockroachDB Cluster Admin API",
-            versions: Versions::new_lockstep(semver::Version::new(0, 0, 1)),
+            versions: Versions::new_versioned(
+                cockroach_admin_api::supported_versions(),
+            ),
             description: "API for interacting with the Oxide \
                 control plane's CockroachDB cluster",
             boundary: ApiBoundary::Internal,
diff --git a/openapi/cockroach-admin.json b/openapi/cockroach-admin/cockroach-admin-1.0.0-dc9acb.json
similarity index 99%
rename from openapi/cockroach-admin.json
rename to openapi/cockroach-admin/cockroach-admin-1.0.0-dc9acb.json
index 80c50db0f1f..6b2fab93abc 100644
--- a/openapi/cockroach-admin.json
+++ b/openapi/cockroach-admin/cockroach-admin-1.0.0-dc9acb.json
@@ -7,7 +7,7 @@
       "url": "https://oxide.computer",
       "email": "api@oxide.computer"
     },
-    "version": "0.0.1"
+    "version": "1.0.0"
   },
   "paths": {
     "/cluster/init": {
diff --git a/openapi/cockroach-admin/cockroach-admin-latest.json b/openapi/cockroach-admin/cockroach-admin-latest.json
new file mode 120000
index 00000000000..4a81b27dac9
--- /dev/null
+++ b/openapi/cockroach-admin/cockroach-admin-latest.json
@@ -0,0 +1 @@
+cockroach-admin-1.0.0-dc9acb.json
\ No newline at end of file

From a994f1fa7400b867d8c0cce8216bd315cab47754 Mon Sep 17 00:00:00 2001
From: iliana etaoin <iliana@oxide.computer>
Date: Wed, 6 Aug 2025 18:21:45 +0000
Subject: [PATCH 03/12] gateway: versionify

---
 Cargo.lock                                    |  2 ++
 clients/gateway-client/src/lib.rs             |  2 +-
 dev-tools/openapi-manager/src/omicron.rs      |  2 +-
 gateway-api/Cargo.toml                        |  2 ++
 gateway-api/src/lib.rs                        | 30 +++++++++++++++++++
 .../gateway-1.0.0-48d3de.json}                |  2 +-
 openapi/gateway/gateway-latest.json           |  1 +
 7 files changed, 38 insertions(+), 3 deletions(-)
 rename openapi/{gateway.json => gateway/gateway-1.0.0-48d3de.json} (99%)
 create mode 120000 openapi/gateway/gateway-latest.json

diff --git a/Cargo.lock b/Cargo.lock
index a70beddd1c6..215cb922402 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -3620,7 +3620,9 @@ dependencies = [
  "omicron-common",
  "omicron-uuid-kinds",
  "omicron-workspace-hack",
+ "openapi-manager-types",
  "schemars",
+ "semver 1.0.26",
  "serde",
  "uuid",
 ]
diff --git a/clients/gateway-client/src/lib.rs b/clients/gateway-client/src/lib.rs
index 4de1d84a22b..179e4b6a554 100644
--- a/clients/gateway-client/src/lib.rs
+++ b/clients/gateway-client/src/lib.rs
@@ -48,7 +48,7 @@ use types::ComponentFirmwareHashStatus;
 // call into each other. Since `gateway` is a lower-level service and never
 // calls into Nexus, the current scheme is okay.)
 progenitor::generate_api!(
-    spec = "../../openapi/gateway.json",
+    spec = "../../openapi/gateway/gateway-latest.json",
     interface = Positional,
     inner_type = slog::Logger,
     pre_hook = (|log: &slog::Logger, request: &reqwest::Request| {
diff --git a/dev-tools/openapi-manager/src/omicron.rs b/dev-tools/openapi-manager/src/omicron.rs
index 6135cc3600f..d2c5268dd4b 100644
--- a/dev-tools/openapi-manager/src/omicron.rs
+++ b/dev-tools/openapi-manager/src/omicron.rs
@@ -92,7 +92,7 @@ pub fn all_apis() -> Vec<ManagedApiConfig> {
         },
         ManagedApiConfig {
             title: "Oxide Management Gateway Service API",
-            versions: Versions::new_lockstep(semver::Version::new(0, 0, 1)),
+            versions: Versions::new_versioned(gateway_api::supported_versions()),
             description: "API for interacting with the Oxide \
                 control plane's gateway service",
             boundary: ApiBoundary::Internal,
diff --git a/gateway-api/Cargo.toml b/gateway-api/Cargo.toml
index 45aa8d4fa83..b5a10dd6907 100644
--- a/gateway-api/Cargo.toml
+++ b/gateway-api/Cargo.toml
@@ -14,6 +14,8 @@ gateway-types.workspace = true
 omicron-common.workspace = true
 omicron-uuid-kinds.workspace = true
 omicron-workspace-hack.workspace = true
+openapi-manager-types.workspace = true
 schemars.workspace = true
+semver.workspace = true
 serde.workspace = true
 uuid.workspace = true
diff --git a/gateway-api/src/lib.rs b/gateway-api/src/lib.rs
index 18d068cfb7f..a7db666b932 100644
--- a/gateway-api/src/lib.rs
+++ b/gateway-api/src/lib.rs
@@ -26,10 +26,40 @@ use gateway_types::{
         SpUpdateStatus,
     },
 };
+use openapi_manager_types::{
+    SupportedVersion, SupportedVersions, api_versions,
+};
 use schemars::JsonSchema;
 use serde::Deserialize;
 use uuid::Uuid;
 
+api_versions!([
+    // WHEN CHANGING THE API (part 1 of 2):
+    //
+    // +- Pick a new semver and define it in the list below.  The list MUST
+    // |  remain sorted, which generally means that your version should go at
+    // |  the very top.
+    // |
+    // |  Duplicate this line, uncomment the *second* copy, update that copy for
+    // |  your new API version, and leave the first copy commented out as an
+    // |  example for the next person.
+    // v
+    // (next_int, IDENT),
+    (1, INITIAL),
+]);
+
+// WHEN CHANGING THE API (part 2 of 2):
+//
+// The call to `api_versions!` above defines constants of type
+// `semver::Version` that you can use in your Dropshot API definition to specify
+// the version when a particular endpoint was added or removed.  For example, if
+// you used:
+//
+//     (2, ADD_FOOBAR)
+//
+// Then you could use `VERSION_ADD_FOOBAR` as the version in which endpoints
+// were added or removed.
+
 /// This endpoint is used to upload SP and ROT Hubris archives as well as phase 1 host OS
 /// images. The phase 1 image is 32 MiB, driven by the QSPI flash on hardware.
 const SP_COMPONENT_UPDATE_MAX_BYTES: usize = 64 * 1024 * 1024;
diff --git a/openapi/gateway.json b/openapi/gateway/gateway-1.0.0-48d3de.json
similarity index 99%
rename from openapi/gateway.json
rename to openapi/gateway/gateway-1.0.0-48d3de.json
index 23b216037bd..50e9a073e95 100644
--- a/openapi/gateway.json
+++ b/openapi/gateway/gateway-1.0.0-48d3de.json
@@ -7,7 +7,7 @@
       "url": "https://oxide.computer",
       "email": "api@oxide.computer"
     },
-    "version": "0.0.1"
+    "version": "1.0.0"
   },
   "paths": {
     "/ignition": {
diff --git a/openapi/gateway/gateway-latest.json b/openapi/gateway/gateway-latest.json
new file mode 120000
index 00000000000..e76448258a4
--- /dev/null
+++ b/openapi/gateway/gateway-latest.json
@@ -0,0 +1 @@
+gateway-1.0.0-48d3de.json
\ No newline at end of file

From db0cd8c25aa9dc81d9638199a7aa9ecc2a243bd5 Mon Sep 17 00:00:00 2001
From: iliana etaoin <iliana@oxide.computer>
Date: Wed, 6 Aug 2025 21:12:29 +0000
Subject: [PATCH 04/12] clickhouse-admin-api: versionify

---
 Cargo.lock                                    |  2 ++
 clickhouse-admin/api/Cargo.toml               |  2 ++
 clickhouse-admin/api/src/lib.rs               | 35 +++++++++++++++++++
 .../clickhouse-admin-keeper-client/src/lib.rs |  2 +-
 .../clickhouse-admin-server-client/src/lib.rs |  2 +-
 .../clickhouse-admin-single-client/src/lib.rs |  2 +-
 dev-tools/openapi-manager/src/omicron.rs      | 12 +++++--
 ...clickhouse-admin-keeper-1.0.0-169173.json} |  2 +-
 .../clickhouse-admin-keeper-latest.json       |  1 +
 ...clickhouse-admin-server-1.0.0-dcea9c.json} |  2 +-
 .../clickhouse-admin-server-latest.json       |  1 +
 ...clickhouse-admin-single-1.0.0-712a53.json} |  2 +-
 .../clickhouse-admin-single-latest.json       |  1 +
 13 files changed, 57 insertions(+), 9 deletions(-)
 rename openapi/{clickhouse-admin-keeper.json => clickhouse-admin-keeper/clickhouse-admin-keeper-1.0.0-169173.json} (99%)
 create mode 120000 openapi/clickhouse-admin-keeper/clickhouse-admin-keeper-latest.json
 rename openapi/{clickhouse-admin-server.json => clickhouse-admin-server/clickhouse-admin-server-1.0.0-dcea9c.json} (99%)
 create mode 120000 openapi/clickhouse-admin-server/clickhouse-admin-server-latest.json
 rename openapi/{clickhouse-admin-single.json => clickhouse-admin-single/clickhouse-admin-single-1.0.0-712a53.json} (99%)
 create mode 120000 openapi/clickhouse-admin-single/clickhouse-admin-single-latest.json

diff --git a/Cargo.lock b/Cargo.lock
index 215cb922402..d442a2b670b 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -1458,7 +1458,9 @@ dependencies = [
  "omicron-common",
  "omicron-uuid-kinds",
  "omicron-workspace-hack",
+ "openapi-manager-types",
  "schemars",
+ "semver 1.0.26",
  "serde",
 ]
 
diff --git a/clickhouse-admin/api/Cargo.toml b/clickhouse-admin/api/Cargo.toml
index a5d1dca2024..f3b7dd83a18 100644
--- a/clickhouse-admin/api/Cargo.toml
+++ b/clickhouse-admin/api/Cargo.toml
@@ -13,5 +13,7 @@ dropshot.workspace = true
 omicron-common.workspace = true
 omicron-uuid-kinds.workspace = true
 omicron-workspace-hack.workspace = true
+openapi-manager-types.workspace = true
 schemars.workspace = true
+semver.workspace = true
 serde.workspace = true
diff --git a/clickhouse-admin/api/src/lib.rs b/clickhouse-admin/api/src/lib.rs
index fbd8a78a0a5..baefdb497fc 100644
--- a/clickhouse-admin/api/src/lib.rs
+++ b/clickhouse-admin/api/src/lib.rs
@@ -13,6 +13,41 @@ use dropshot::{
     HttpResponseUpdatedNoContent, Path, Query, RequestContext, TypedBody,
 };
 use omicron_common::api::external::Generation;
+use openapi_manager_types::{
+    SupportedVersion, SupportedVersions, api_versions,
+};
+
+api_versions!([
+    // NOTE: These versions will be used across **all three** APIs defined in
+    // this file. When we need to add the next version, consider carefully if
+    // these APIs should be split into separate modules or crates with their
+    // own versions.
+
+    // WHEN CHANGING THE API (part 1 of 2):
+    //
+    // +- Pick a new semver and define it in the list below.  The list MUST
+    // |  remain sorted, which generally means that your version should go at
+    // |  the very top.
+    // |
+    // |  Duplicate this line, uncomment the *second* copy, update that copy for
+    // |  your new API version, and leave the first copy commented out as an
+    // |  example for the next person.
+    // v
+    // (next_int, IDENT), // NOTE: read the note at the start of this macro!
+    (1, INITIAL),
+]);
+
+// WHEN CHANGING THE API (part 2 of 2):
+//
+// The call to `api_versions!` above defines constants of type
+// `semver::Version` that you can use in your Dropshot API definition to specify
+// the version when a particular endpoint was added or removed.  For example, if
+// you used:
+//
+//     (2, ADD_FOOBAR)
+//
+// Then you could use `VERSION_ADD_FOOBAR` as the version in which endpoints
+// were added or removed.
 
 /// API interface for our clickhouse-admin-keeper server
 ///
diff --git a/clients/clickhouse-admin-keeper-client/src/lib.rs b/clients/clickhouse-admin-keeper-client/src/lib.rs
index 5c4d3692fab..68bcbbaa079 100644
--- a/clients/clickhouse-admin-keeper-client/src/lib.rs
+++ b/clients/clickhouse-admin-keeper-client/src/lib.rs
@@ -6,7 +6,7 @@
 //! running in an omicron zone.
 
 progenitor::generate_api!(
-    spec = "../../openapi/clickhouse-admin-keeper.json",
+    spec = "../../openapi/clickhouse-admin-keeper/clickhouse-admin-keeper-latest.json",
     interface = Positional,
     inner_type = slog::Logger,
     pre_hook = (|log: &slog::Logger, request: &reqwest::Request| {
diff --git a/clients/clickhouse-admin-server-client/src/lib.rs b/clients/clickhouse-admin-server-client/src/lib.rs
index af9d5aae988..e8da8d250f6 100644
--- a/clients/clickhouse-admin-server-client/src/lib.rs
+++ b/clients/clickhouse-admin-server-client/src/lib.rs
@@ -6,7 +6,7 @@
 //! running in an omicron zone.
 
 progenitor::generate_api!(
-    spec = "../../openapi/clickhouse-admin-server.json",
+    spec = "../../openapi/clickhouse-admin-server/clickhouse-admin-server-latest.json",
     interface = Positional,
     inner_type = slog::Logger,
     pre_hook = (|log: &slog::Logger, request: &reqwest::Request| {
diff --git a/clients/clickhouse-admin-single-client/src/lib.rs b/clients/clickhouse-admin-single-client/src/lib.rs
index ae0a3850175..396c9d68b2b 100644
--- a/clients/clickhouse-admin-single-client/src/lib.rs
+++ b/clients/clickhouse-admin-single-client/src/lib.rs
@@ -6,7 +6,7 @@
 //! ClickHouse database.
 
 progenitor::generate_api!(
-    spec = "../../openapi/clickhouse-admin-single.json",
+    spec = "../../openapi/clickhouse-admin-single/clickhouse-admin-single-latest.json",
     interface = Positional,
     inner_type = slog::Logger,
     pre_hook = (|log: &slog::Logger, request: &reqwest::Request| {
diff --git a/dev-tools/openapi-manager/src/omicron.rs b/dev-tools/openapi-manager/src/omicron.rs
index d2c5268dd4b..ead968dddf4 100644
--- a/dev-tools/openapi-manager/src/omicron.rs
+++ b/dev-tools/openapi-manager/src/omicron.rs
@@ -36,7 +36,9 @@ pub fn all_apis() -> Vec<ManagedApiConfig> {
         },
         ManagedApiConfig {
             title: "ClickHouse Cluster Admin Keeper API",
-            versions: Versions::new_lockstep(semver::Version::new(0, 0, 1)),
+            versions: Versions::new_versioned(
+                clickhouse_admin_api::supported_versions(),
+            ),
             description: "API for interacting with the Oxide \
                 control plane's ClickHouse cluster keepers",
             boundary: ApiBoundary::Internal,
@@ -47,7 +49,9 @@ pub fn all_apis() -> Vec<ManagedApiConfig> {
         },
         ManagedApiConfig {
             title: "ClickHouse Cluster Admin Server API",
-            versions: Versions::new_lockstep(semver::Version::new(0, 0, 1)),
+            versions: Versions::new_versioned(
+                clickhouse_admin_api::supported_versions(),
+            ),
             description: "API for interacting with the Oxide \
                 control plane's ClickHouse cluster replica servers",
             boundary: ApiBoundary::Internal,
@@ -58,7 +62,9 @@ pub fn all_apis() -> Vec<ManagedApiConfig> {
         },
         ManagedApiConfig {
             title: "ClickHouse Single-Node Admin Server API",
-            versions: Versions::new_lockstep(semver::Version::new(0, 0, 1)),
+            versions: Versions::new_versioned(
+                clickhouse_admin_api::supported_versions(),
+            ),
             description: "API for interacting with the Oxide \
                 control plane's single-node ClickHouse database",
             boundary: ApiBoundary::Internal,
diff --git a/openapi/clickhouse-admin-keeper.json b/openapi/clickhouse-admin-keeper/clickhouse-admin-keeper-1.0.0-169173.json
similarity index 99%
rename from openapi/clickhouse-admin-keeper.json
rename to openapi/clickhouse-admin-keeper/clickhouse-admin-keeper-1.0.0-169173.json
index 5099e2fe595..e3296068963 100644
--- a/openapi/clickhouse-admin-keeper.json
+++ b/openapi/clickhouse-admin-keeper/clickhouse-admin-keeper-1.0.0-169173.json
@@ -7,7 +7,7 @@
       "url": "https://oxide.computer",
       "email": "api@oxide.computer"
     },
-    "version": "0.0.1"
+    "version": "1.0.0"
   },
   "paths": {
     "/4lw-conf": {
diff --git a/openapi/clickhouse-admin-keeper/clickhouse-admin-keeper-latest.json b/openapi/clickhouse-admin-keeper/clickhouse-admin-keeper-latest.json
new file mode 120000
index 00000000000..81e0bb08a07
--- /dev/null
+++ b/openapi/clickhouse-admin-keeper/clickhouse-admin-keeper-latest.json
@@ -0,0 +1 @@
+clickhouse-admin-keeper-1.0.0-169173.json
\ No newline at end of file
diff --git a/openapi/clickhouse-admin-server.json b/openapi/clickhouse-admin-server/clickhouse-admin-server-1.0.0-dcea9c.json
similarity index 99%
rename from openapi/clickhouse-admin-server.json
rename to openapi/clickhouse-admin-server/clickhouse-admin-server-1.0.0-dcea9c.json
index 5b63767bd23..6e61df7820e 100644
--- a/openapi/clickhouse-admin-server.json
+++ b/openapi/clickhouse-admin-server/clickhouse-admin-server-1.0.0-dcea9c.json
@@ -7,7 +7,7 @@
       "url": "https://oxide.computer",
       "email": "api@oxide.computer"
     },
-    "version": "0.0.1"
+    "version": "1.0.0"
   },
   "paths": {
     "/config": {
diff --git a/openapi/clickhouse-admin-server/clickhouse-admin-server-latest.json b/openapi/clickhouse-admin-server/clickhouse-admin-server-latest.json
new file mode 120000
index 00000000000..6e92f6bffbf
--- /dev/null
+++ b/openapi/clickhouse-admin-server/clickhouse-admin-server-latest.json
@@ -0,0 +1 @@
+clickhouse-admin-server-1.0.0-dcea9c.json
\ No newline at end of file
diff --git a/openapi/clickhouse-admin-single.json b/openapi/clickhouse-admin-single/clickhouse-admin-single-1.0.0-712a53.json
similarity index 99%
rename from openapi/clickhouse-admin-single.json
rename to openapi/clickhouse-admin-single/clickhouse-admin-single-1.0.0-712a53.json
index c6b99da245d..118d5af5dbe 100644
--- a/openapi/clickhouse-admin-single.json
+++ b/openapi/clickhouse-admin-single/clickhouse-admin-single-1.0.0-712a53.json
@@ -7,7 +7,7 @@
       "url": "https://oxide.computer",
       "email": "api@oxide.computer"
     },
-    "version": "0.0.1"
+    "version": "1.0.0"
   },
   "paths": {
     "/init": {
diff --git a/openapi/clickhouse-admin-single/clickhouse-admin-single-latest.json b/openapi/clickhouse-admin-single/clickhouse-admin-single-latest.json
new file mode 120000
index 00000000000..e3e28570691
--- /dev/null
+++ b/openapi/clickhouse-admin-single/clickhouse-admin-single-latest.json
@@ -0,0 +1 @@
+clickhouse-admin-single-1.0.0-712a53.json
\ No newline at end of file

From fb70f217c2c7b8979a1aabcb0daab080a4b2cd02 Mon Sep 17 00:00:00 2001
From: iliana etaoin <iliana@oxide.computer>
Date: Wed, 6 Aug 2025 21:15:16 +0000
Subject: [PATCH 05/12] ntp-admin-api: versionify

---
 Cargo.lock                                    |  2 ++
 dev-tools/openapi-manager/src/omicron.rs      |  4 ++-
 ntp-admin/api/Cargo.toml                      |  2 ++
 ntp-admin/api/src/lib.rs                      | 30 +++++++++++++++++++
 .../ntp-admin-1.0.0-aeffc2.json}              |  2 +-
 openapi/ntp-admin/ntp-admin-latest.json       |  1 +
 6 files changed, 39 insertions(+), 2 deletions(-)
 rename openapi/{ntp-admin.json => ntp-admin/ntp-admin-1.0.0-aeffc2.json} (99%)
 create mode 120000 openapi/ntp-admin/ntp-admin-latest.json

diff --git a/Cargo.lock b/Cargo.lock
index d442a2b670b..f2f3fb2b588 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -7187,7 +7187,9 @@ dependencies = [
  "omicron-common",
  "omicron-uuid-kinds",
  "omicron-workspace-hack",
+ "openapi-manager-types",
  "schemars",
+ "semver 1.0.26",
  "serde",
 ]
 
diff --git a/dev-tools/openapi-manager/src/omicron.rs b/dev-tools/openapi-manager/src/omicron.rs
index ead968dddf4..31e74ce3222 100644
--- a/dev-tools/openapi-manager/src/omicron.rs
+++ b/dev-tools/openapi-manager/src/omicron.rs
@@ -138,7 +138,9 @@ pub fn all_apis() -> Vec<ManagedApiConfig> {
         },
         ManagedApiConfig {
             title: "NTP Admin API",
-            versions: Versions::new_lockstep(semver::Version::new(0, 0, 1)),
+            versions: Versions::new_versioned(
+                ntp_admin_api::supported_versions(),
+            ),
             description: "API for interacting with NTP",
             boundary: ApiBoundary::Internal,
             api_description: ntp_admin_api_mod::stub_api_description,
diff --git a/ntp-admin/api/Cargo.toml b/ntp-admin/api/Cargo.toml
index 3ef5615c641..6f7fbe9fe6c 100644
--- a/ntp-admin/api/Cargo.toml
+++ b/ntp-admin/api/Cargo.toml
@@ -14,5 +14,7 @@ ntp-admin-types.workspace = true
 omicron-common.workspace = true
 omicron-uuid-kinds.workspace = true
 omicron-workspace-hack.workspace = true
+openapi-manager-types.workspace = true
 schemars.workspace = true
+semver.workspace = true
 serde.workspace = true
diff --git a/ntp-admin/api/src/lib.rs b/ntp-admin/api/src/lib.rs
index 07c5867339d..aff258b4460 100644
--- a/ntp-admin/api/src/lib.rs
+++ b/ntp-admin/api/src/lib.rs
@@ -3,6 +3,36 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 
 use dropshot::{HttpError, HttpResponseOk, RequestContext};
+use openapi_manager_types::{
+    SupportedVersion, SupportedVersions, api_versions,
+};
+
+api_versions!([
+    // WHEN CHANGING THE API (part 1 of 2):
+    //
+    // +- Pick a new semver and define it in the list below.  The list MUST
+    // |  remain sorted, which generally means that your version should go at
+    // |  the very top.
+    // |
+    // |  Duplicate this line, uncomment the *second* copy, update that copy for
+    // |  your new API version, and leave the first copy commented out as an
+    // |  example for the next person.
+    // v
+    // (next_int, IDENT),
+    (1, INITIAL),
+]);
+
+// WHEN CHANGING THE API (part 2 of 2):
+//
+// The call to `api_versions!` above defines constants of type
+// `semver::Version` that you can use in your Dropshot API definition to specify
+// the version when a particular endpoint was added or removed.  For example, if
+// you used:
+//
+//     (2, ADD_FOOBAR)
+//
+// Then you could use `VERSION_ADD_FOOBAR` as the version in which endpoints
+// were added or removed.
 
 #[dropshot::api_description]
 pub trait NtpAdminApi {
diff --git a/openapi/ntp-admin.json b/openapi/ntp-admin/ntp-admin-1.0.0-aeffc2.json
similarity index 99%
rename from openapi/ntp-admin.json
rename to openapi/ntp-admin/ntp-admin-1.0.0-aeffc2.json
index eae66021e91..97fc34581cc 100644
--- a/openapi/ntp-admin.json
+++ b/openapi/ntp-admin/ntp-admin-1.0.0-aeffc2.json
@@ -7,7 +7,7 @@
       "url": "https://oxide.computer",
       "email": "api@oxide.computer"
     },
-    "version": "0.0.1"
+    "version": "1.0.0"
   },
   "paths": {
     "/timesync": {
diff --git a/openapi/ntp-admin/ntp-admin-latest.json b/openapi/ntp-admin/ntp-admin-latest.json
new file mode 120000
index 00000000000..30138bae0ea
--- /dev/null
+++ b/openapi/ntp-admin/ntp-admin-latest.json
@@ -0,0 +1 @@
+ntp-admin-1.0.0-aeffc2.json
\ No newline at end of file

From 14cc11298c7bd559b3e332749c6956f086889901 Mon Sep 17 00:00:00 2001
From: iliana etaoin <iliana@oxide.computer>
Date: Wed, 6 Aug 2025 21:16:44 +0000
Subject: [PATCH 06/12] oximeter-api: versionify

---
 Cargo.lock                                    |  2 ++
 dev-tools/openapi-manager/src/omicron.rs      |  4 ++-
 .../oximeter-1.0.0-8e3b9c.json}               |  2 +-
 openapi/oximeter/oximeter-latest.json         |  1 +
 oximeter/api/Cargo.toml                       |  2 ++
 oximeter/api/src/lib.rs                       | 30 +++++++++++++++++++
 6 files changed, 39 insertions(+), 2 deletions(-)
 rename openapi/{oximeter.json => oximeter/oximeter-1.0.0-8e3b9c.json} (99%)
 create mode 120000 openapi/oximeter/oximeter-latest.json

diff --git a/Cargo.lock b/Cargo.lock
index f2f3fb2b588..323293d3f1d 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -8941,7 +8941,9 @@ dependencies = [
  "dropshot",
  "omicron-common",
  "omicron-workspace-hack",
+ "openapi-manager-types",
  "schemars",
+ "semver 1.0.26",
  "serde",
  "uuid",
 ]
diff --git a/dev-tools/openapi-manager/src/omicron.rs b/dev-tools/openapi-manager/src/omicron.rs
index 31e74ce3222..e85a9448c1b 100644
--- a/dev-tools/openapi-manager/src/omicron.rs
+++ b/dev-tools/openapi-manager/src/omicron.rs
@@ -149,7 +149,9 @@ pub fn all_apis() -> Vec<ManagedApiConfig> {
         },
         ManagedApiConfig {
             title: "Oxide Oximeter API",
-            versions: Versions::new_lockstep(semver::Version::new(0, 0, 1)),
+            versions: Versions::new_versioned(
+                oximeter_api::supported_versions(),
+            ),
             description: "API for interacting with oximeter",
             boundary: ApiBoundary::Internal,
             api_description: oximeter_api_mod::stub_api_description,
diff --git a/openapi/oximeter.json b/openapi/oximeter/oximeter-1.0.0-8e3b9c.json
similarity index 99%
rename from openapi/oximeter.json
rename to openapi/oximeter/oximeter-1.0.0-8e3b9c.json
index b51c56b667a..e78c47d07f0 100644
--- a/openapi/oximeter.json
+++ b/openapi/oximeter/oximeter-1.0.0-8e3b9c.json
@@ -7,7 +7,7 @@
       "url": "https://oxide.computer",
       "email": "api@oxide.computer"
     },
-    "version": "0.0.1"
+    "version": "1.0.0"
   },
   "paths": {
     "/info": {
diff --git a/openapi/oximeter/oximeter-latest.json b/openapi/oximeter/oximeter-latest.json
new file mode 120000
index 00000000000..e07d9a8f248
--- /dev/null
+++ b/openapi/oximeter/oximeter-latest.json
@@ -0,0 +1 @@
+oximeter-1.0.0-8e3b9c.json
\ No newline at end of file
diff --git a/oximeter/api/Cargo.toml b/oximeter/api/Cargo.toml
index 72189aa6459..6df6bcda2c5 100644
--- a/oximeter/api/Cargo.toml
+++ b/oximeter/api/Cargo.toml
@@ -11,6 +11,8 @@ chrono.workspace = true
 dropshot.workspace = true
 omicron-common.workspace = true
 omicron-workspace-hack.workspace = true
+openapi-manager-types.workspace = true
 schemars.workspace = true
+semver.workspace = true
 serde.workspace = true
 uuid.workspace = true
diff --git a/oximeter/api/src/lib.rs b/oximeter/api/src/lib.rs
index f47a5ba07ee..e0b36007ed7 100644
--- a/oximeter/api/src/lib.rs
+++ b/oximeter/api/src/lib.rs
@@ -8,11 +8,41 @@ use dropshot::{
     PaginationParams, Query, RequestContext, ResultsPage,
 };
 use omicron_common::api::internal::nexus::ProducerEndpoint;
+use openapi_manager_types::{
+    SupportedVersion, SupportedVersions, api_versions,
+};
 use schemars::JsonSchema;
 use serde::{Deserialize, Serialize};
 use std::{net::SocketAddr, time::Duration};
 use uuid::Uuid;
 
+api_versions!([
+    // WHEN CHANGING THE API (part 1 of 2):
+    //
+    // +- Pick a new semver and define it in the list below.  The list MUST
+    // |  remain sorted, which generally means that your version should go at
+    // |  the very top.
+    // |
+    // |  Duplicate this line, uncomment the *second* copy, update that copy for
+    // |  your new API version, and leave the first copy commented out as an
+    // |  example for the next person.
+    // v
+    // (next_int, IDENT),
+    (1, INITIAL),
+]);
+
+// WHEN CHANGING THE API (part 2 of 2):
+//
+// The call to `api_versions!` above defines constants of type
+// `semver::Version` that you can use in your Dropshot API definition to specify
+// the version when a particular endpoint was added or removed.  For example, if
+// you used:
+//
+//     (2, ADD_FOOBAR)
+//
+// Then you could use `VERSION_ADD_FOOBAR` as the version in which endpoints
+// were added or removed.
+
 #[dropshot::api_description]
 pub trait OximeterApi {
     type Context;

From 75a65867f8f4f6135c34799c95d02915640427a8 Mon Sep 17 00:00:00 2001
From: iliana etaoin <iliana@oxide.computer>
Date: Wed, 6 Aug 2025 21:18:27 +0000
Subject: [PATCH 07/12] sled-agent-api: versionify

---
 Cargo.lock                                    |  2 ++
 dev-tools/openapi-manager/src/omicron.rs      |  4 ++-
 .../sled-agent-1.0.0-897f5e.json}             |  2 +-
 openapi/sled-agent/sled-agent-latest.json     |  1 +
 sled-agent/api/Cargo.toml                     |  2 ++
 sled-agent/api/src/lib.rs                     | 30 +++++++++++++++++++
 6 files changed, 39 insertions(+), 2 deletions(-)
 rename openapi/{sled-agent.json => sled-agent/sled-agent-1.0.0-897f5e.json} (99%)
 create mode 120000 openapi/sled-agent/sled-agent-latest.json

diff --git a/Cargo.lock b/Cargo.lock
index 323293d3f1d..e301524e64b 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -12223,7 +12223,9 @@ dependencies = [
  "omicron-common",
  "omicron-uuid-kinds",
  "omicron-workspace-hack",
+ "openapi-manager-types",
  "schemars",
+ "semver 1.0.26",
  "serde",
  "sled-agent-types",
  "sled-diagnostics",
diff --git a/dev-tools/openapi-manager/src/omicron.rs b/dev-tools/openapi-manager/src/omicron.rs
index e85a9448c1b..15857be598f 100644
--- a/dev-tools/openapi-manager/src/omicron.rs
+++ b/dev-tools/openapi-manager/src/omicron.rs
@@ -169,7 +169,9 @@ pub fn all_apis() -> Vec<ManagedApiConfig> {
         },
         ManagedApiConfig {
             title: "Oxide Sled Agent API",
-            versions: Versions::new_lockstep(semver::Version::new(0, 0, 1)),
+            versions: Versions::new_versioned(
+                sled_agent_api::supported_versions(),
+            ),
             description: "API for interacting with individual sleds",
             boundary: ApiBoundary::Internal,
             api_description: sled_agent_api_mod::stub_api_description,
diff --git a/openapi/sled-agent.json b/openapi/sled-agent/sled-agent-1.0.0-897f5e.json
similarity index 99%
rename from openapi/sled-agent.json
rename to openapi/sled-agent/sled-agent-1.0.0-897f5e.json
index f482cf66f92..91b222e2f00 100644
--- a/openapi/sled-agent.json
+++ b/openapi/sled-agent/sled-agent-1.0.0-897f5e.json
@@ -7,7 +7,7 @@
       "url": "https://oxide.computer",
       "email": "api@oxide.computer"
     },
-    "version": "0.0.1"
+    "version": "1.0.0"
   },
   "paths": {
     "/artifacts": {
diff --git a/openapi/sled-agent/sled-agent-latest.json b/openapi/sled-agent/sled-agent-latest.json
new file mode 120000
index 00000000000..8cf0e7f15c1
--- /dev/null
+++ b/openapi/sled-agent/sled-agent-latest.json
@@ -0,0 +1 @@
+sled-agent-1.0.0-897f5e.json
\ No newline at end of file
diff --git a/sled-agent/api/Cargo.toml b/sled-agent/api/Cargo.toml
index 9077419faf3..eb682524e57 100644
--- a/sled-agent/api/Cargo.toml
+++ b/sled-agent/api/Cargo.toml
@@ -22,3 +22,5 @@ sled-hardware-types.workspace = true
 sled-diagnostics.workspace = true
 tufaceous-artifact.workspace = true
 uuid.workspace = true
+openapi-manager-types.workspace = true
+semver.workspace = true
diff --git a/sled-agent/api/src/lib.rs b/sled-agent/api/src/lib.rs
index 650cc04b010..f66b40048c7 100644
--- a/sled-agent/api/src/lib.rs
+++ b/sled-agent/api/src/lib.rs
@@ -30,6 +30,9 @@ use omicron_common::{
 use omicron_uuid_kinds::{
     DatasetUuid, PropolisUuid, SupportBundleUuid, ZpoolUuid,
 };
+use openapi_manager_types::{
+    SupportedVersion, SupportedVersions, api_versions,
+};
 use schemars::JsonSchema;
 use serde::{Deserialize, Serialize};
 use sled_agent_types::{
@@ -51,6 +54,33 @@ use sled_diagnostics::SledDiagnosticsQueryOutput;
 use tufaceous_artifact::ArtifactHash;
 use uuid::Uuid;
 
+api_versions!([
+    // WHEN CHANGING THE API (part 1 of 2):
+    //
+    // +- Pick a new semver and define it in the list below.  The list MUST
+    // |  remain sorted, which generally means that your version should go at
+    // |  the very top.
+    // |
+    // |  Duplicate this line, uncomment the *second* copy, update that copy for
+    // |  your new API version, and leave the first copy commented out as an
+    // |  example for the next person.
+    // v
+    // (next_int, IDENT),
+    (1, INITIAL),
+]);
+
+// WHEN CHANGING THE API (part 2 of 2):
+//
+// The call to `api_versions!` above defines constants of type
+// `semver::Version` that you can use in your Dropshot API definition to specify
+// the version when a particular endpoint was added or removed.  For example, if
+// you used:
+//
+//     (2, ADD_FOOBAR)
+//
+// Then you could use `VERSION_ADD_FOOBAR` as the version in which endpoints
+// were added or removed.
+
 // Host OS images are just over 800 MiB currently; set this to 2 GiB to give
 // some breathing room.
 const HOST_OS_IMAGE_MAX_BYTES: usize = 2 * 1024 * 1024 * 1024;

From f89d6f84bbfa584168b3af13b82e8064d062db32 Mon Sep 17 00:00:00 2001
From: iliana etaoin <iliana@oxide.computer>
Date: Mon, 11 Aug 2025 13:08:02 -0700
Subject: [PATCH 08/12] oops

---
 clients/ntp-admin-client/src/lib.rs  | 2 +-
 clients/oximeter-client/src/lib.rs   | 2 +-
 clients/sled-agent-client/src/lib.rs | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/clients/ntp-admin-client/src/lib.rs b/clients/ntp-admin-client/src/lib.rs
index 9a2c028c514..4cdc70d6d99 100644
--- a/clients/ntp-admin-client/src/lib.rs
+++ b/clients/ntp-admin-client/src/lib.rs
@@ -5,7 +5,7 @@
 //! Interface for making API requests to an Omicron NTP admin server
 
 progenitor::generate_api!(
-    spec = "../../openapi/ntp-admin.json",
+    spec = "../../openapi/ntp-admin/ntp-admin-latest.json",
     interface = Positional,
     inner_type = slog::Logger,
     pre_hook = (|log: &slog::Logger, request: &reqwest::Request| {
diff --git a/clients/oximeter-client/src/lib.rs b/clients/oximeter-client/src/lib.rs
index 3c9df960024..764e2f7d7c5 100644
--- a/clients/oximeter-client/src/lib.rs
+++ b/clients/oximeter-client/src/lib.rs
@@ -7,7 +7,7 @@
 //! Interface for API requests to an Oximeter metric collection server
 
 progenitor::generate_api!(
-    spec = "../../openapi/oximeter.json",
+    spec = "../../openapi/oximeter/oximeter-latest.json",
     interface = Positional,
     inner_type = slog::Logger,
     pre_hook = (|log: &slog::Logger, request: &reqwest::Request| {
diff --git a/clients/sled-agent-client/src/lib.rs b/clients/sled-agent-client/src/lib.rs
index 948d246e734..faa09fbf889 100644
--- a/clients/sled-agent-client/src/lib.rs
+++ b/clients/sled-agent-client/src/lib.rs
@@ -15,7 +15,7 @@ use uuid::Uuid;
 pub use propolis_client::{CrucibleOpts, VolumeConstructionRequest};
 
 progenitor::generate_api!(
-    spec = "../../openapi/sled-agent.json",
+    spec = "../../openapi/sled-agent/sled-agent-latest.json",
     interface = Positional,
     inner_type = slog::Logger,
     pre_hook = (|log: &slog::Logger, request: &reqwest::Request| {

From 2573caa5a7822f4124a14a2f570a2de1963f10ad Mon Sep 17 00:00:00 2001
From: iliana etaoin <iliana@oxide.computer>
Date: Mon, 11 Aug 2025 13:09:54 -0700
Subject: [PATCH 09/12] merge

---
 ...led-agent-1.0.0-897f5e.json => sled-agent-1.0.0-f40ac1.json} | 0
 openapi/sled-agent/sled-agent-latest.json                       | 2 +-
 2 files changed, 1 insertion(+), 1 deletion(-)
 rename openapi/sled-agent/{sled-agent-1.0.0-897f5e.json => sled-agent-1.0.0-f40ac1.json} (100%)

diff --git a/openapi/sled-agent/sled-agent-1.0.0-897f5e.json b/openapi/sled-agent/sled-agent-1.0.0-f40ac1.json
similarity index 100%
rename from openapi/sled-agent/sled-agent-1.0.0-897f5e.json
rename to openapi/sled-agent/sled-agent-1.0.0-f40ac1.json
diff --git a/openapi/sled-agent/sled-agent-latest.json b/openapi/sled-agent/sled-agent-latest.json
index 8cf0e7f15c1..7a6ad60f29f 120000
--- a/openapi/sled-agent/sled-agent-latest.json
+++ b/openapi/sled-agent/sled-agent-latest.json
@@ -1 +1 @@
-sled-agent-1.0.0-897f5e.json
\ No newline at end of file
+sled-agent-1.0.0-f40ac1.json
\ No newline at end of file

From 5de0b6397629117d325e8e763bda694829053039 Mon Sep 17 00:00:00 2001
From: iliana etaoin <iliana@oxide.computer>
Date: Tue, 12 Aug 2025 10:26:11 -0700
Subject: [PATCH 10/12] api-version header wip (not yet all of them)

---
 clickhouse-admin/src/lib.rs           | 18 ++++++++++++++++++
 cockroach-admin/src/lib.rs            |  6 ++++++
 common/src/api/mod.rs                 |  4 ++++
 dns-server/src/lib.rs                 |  4 +---
 internal-dns/resolver/src/resolver.rs |  4 +---
 5 files changed, 30 insertions(+), 6 deletions(-)

diff --git a/clickhouse-admin/src/lib.rs b/clickhouse-admin/src/lib.rs
index 88168911ba3..9f66140efda 100644
--- a/clickhouse-admin/src/lib.rs
+++ b/clickhouse-admin/src/lib.rs
@@ -68,6 +68,12 @@ pub async fn start_server_admin_server(
         log.new(slog::o!("component" => "dropshot")),
     )
     .config(server_config.dropshot)
+    .version_policy(dropshot::VersionPolicy::Dynamic(Box::new(
+        dropshot::ClientSpecifiesVersionInHeader::new(
+            omicron_common::api::VERSION_HEADER,
+            clickhouse_admin_api::VERSION_INITIAL,
+        ),
+    )))
     .start()
     .map_err(StartError::InitializeHttpServer)
 }
@@ -105,6 +111,12 @@ pub async fn start_keeper_admin_server(
         log.new(slog::o!("component" => "dropshot")),
     )
     .config(server_config.dropshot)
+    .version_policy(dropshot::VersionPolicy::Dynamic(Box::new(
+        dropshot::ClientSpecifiesVersionInHeader::new(
+            omicron_common::api::VERSION_HEADER,
+            clickhouse_admin_api::VERSION_INITIAL,
+        ),
+    )))
     .start()
     .map_err(StartError::InitializeHttpServer)
 }
@@ -142,6 +154,12 @@ pub async fn start_single_admin_server(
         log.new(slog::o!("component" => "dropshot")),
     )
     .config(server_config.dropshot)
+    .version_policy(dropshot::VersionPolicy::Dynamic(Box::new(
+        dropshot::ClientSpecifiesVersionInHeader::new(
+            omicron_common::api::VERSION_HEADER,
+            clickhouse_admin_api::VERSION_INITIAL,
+        ),
+    )))
     .start()
     .map_err(StartError::InitializeHttpServer)
 }
diff --git a/cockroach-admin/src/lib.rs b/cockroach-admin/src/lib.rs
index 10cecf56a05..9591e01433b 100644
--- a/cockroach-admin/src/lib.rs
+++ b/cockroach-admin/src/lib.rs
@@ -69,6 +69,12 @@ pub async fn start_server(
         log.new(slog::o!("component" => "dropshot")),
     )
     .config(server_config.dropshot)
+    .version_policy(dropshot::VersionPolicy::Dynamic(Box::new(
+        dropshot::ClientSpecifiesVersionInHeader::new(
+            omicron_common::api::VERSION_HEADER,
+            cockroach_admin_api::VERSION_INITIAL,
+        ),
+    )))
     .start()
     .map_err(StartError::InitializeHttpServer)
 }
diff --git a/common/src/api/mod.rs b/common/src/api/mod.rs
index ee3776e15b9..44ca3671174 100644
--- a/common/src/api/mod.rs
+++ b/common/src/api/mod.rs
@@ -6,3 +6,7 @@
 
 pub mod external;
 pub mod internal;
+
+/// API versioning header name used across Omicron APIs.
+pub const VERSION_HEADER: http::HeaderName =
+    http::HeaderName::from_static("api-version");
diff --git a/dns-server/src/lib.rs b/dns-server/src/lib.rs
index ad5d49c138b..dde10a6387a 100644
--- a/dns-server/src/lib.rs
+++ b/dns-server/src/lib.rs
@@ -97,9 +97,7 @@ pub async fn start_servers(
         .config(dropshot_config.clone())
         .version_policy(dropshot::VersionPolicy::Dynamic(Box::new(
             dropshot::ClientSpecifiesVersionInHeader::new(
-                "api-version"
-                    .parse::<http::header::HeaderName>()
-                    .expect("api-version is a valid header name"),
+                omicron_common::api::VERSION_HEADER,
                 dns_server_api::VERSION_SOA_AND_NS,
             ),
         )))
diff --git a/internal-dns/resolver/src/resolver.rs b/internal-dns/resolver/src/resolver.rs
index 9df83dc4968..86a7eafbad3 100644
--- a/internal-dns/resolver/src/resolver.rs
+++ b/internal-dns/resolver/src/resolver.rs
@@ -875,9 +875,7 @@ mod test {
             .config(config_dropshot)
             .version_policy(dropshot::VersionPolicy::Dynamic(Box::new(
                 dropshot::ClientSpecifiesVersionInHeader::new(
-                    "api-version"
-                        .parse::<reqwest::header::HeaderName>()
-                        .expect("api-version is a valid header name"),
+                    omicron_common::api::VERSION_HEADER,
                     dns_server_api::VERSION_SOA_AND_NS,
                 ),
             )))

From dc3c90ddf0fdc9992db40110260174ac1aa701b1 Mon Sep 17 00:00:00 2001
From: iliana etaoin <iliana@oxide.computer>
Date: Tue, 12 Aug 2025 19:44:35 +0000
Subject: [PATCH 11/12] finish adding api-version header

---
 gateway/src/lib.rs            |  6 ++++++
 ntp-admin/src/lib.rs          |  6 ++++++
 oximeter/collector/src/lib.rs | 12 ++++++++++++
 sled-agent/src/server.rs      |  6 ++++++
 4 files changed, 30 insertions(+)

diff --git a/gateway/src/lib.rs b/gateway/src/lib.rs
index 8d9b280c5a2..a0ddeab7c7b 100644
--- a/gateway/src/lib.rs
+++ b/gateway/src/lib.rs
@@ -102,6 +102,12 @@ fn start_dropshot_server(
                 log.new(o!("component" => "dropshot")),
             )
             .config(dropshot)
+            .version_policy(dropshot::VersionPolicy::Dynamic(Box::new(
+                dropshot::ClientSpecifiesVersionInHeader::new(
+                    omicron_common::api::VERSION_HEADER,
+                    gateway_api::VERSION_INITIAL,
+                ),
+            )))
             .start()
             .map_err(|error| {
                 format!(
diff --git a/ntp-admin/src/lib.rs b/ntp-admin/src/lib.rs
index 5d79987bf6a..ef9fe1b3b65 100644
--- a/ntp-admin/src/lib.rs
+++ b/ntp-admin/src/lib.rs
@@ -58,6 +58,12 @@ pub async fn start_server(server_config: Config) -> Result<Server, StartError> {
         log.new(slog::o!("component" => "dropshot")),
     )
     .config(server_config.dropshot)
+    .version_policy(dropshot::VersionPolicy::Dynamic(Box::new(
+        dropshot::ClientSpecifiesVersionInHeader::new(
+            omicron_common::api::VERSION_HEADER,
+            ntp_admin_api::VERSION_INITIAL,
+        ),
+    )))
     .start()
     .map_err(StartError::InitializeHttpServer)
 }
diff --git a/oximeter/collector/src/lib.rs b/oximeter/collector/src/lib.rs
index 024b0bcd338..73cc220575d 100644
--- a/oximeter/collector/src/lib.rs
+++ b/oximeter/collector/src/lib.rs
@@ -339,6 +339,12 @@ impl Oximeter {
             bind_address: SocketAddr::V6(args.address),
             ..Default::default()
         })
+        .version_policy(dropshot::VersionPolicy::Dynamic(Box::new(
+            dropshot::ClientSpecifiesVersionInHeader::new(
+                omicron_common::api::VERSION_HEADER,
+                oximeter_api::VERSION_INITIAL,
+            ),
+        )))
         .start()
         .map_err(|e| Error::Server(e.to_string()))?;
 
@@ -451,6 +457,12 @@ impl Oximeter {
             bind_address: SocketAddr::V6(args.address),
             ..Default::default()
         })
+        .version_policy(dropshot::VersionPolicy::Dynamic(Box::new(
+            dropshot::ClientSpecifiesVersionInHeader::new(
+                omicron_common::api::VERSION_HEADER,
+                oximeter_api::VERSION_INITIAL,
+            ),
+        )))
         .start()
         .map_err(|e| Error::Server(e.to_string()))?;
         info!(log, "started oximeter standalone server");
diff --git a/sled-agent/src/server.rs b/sled-agent/src/server.rs
index 15a5c2f784d..1ca4ad3f697 100644
--- a/sled-agent/src/server.rs
+++ b/sled-agent/src/server.rs
@@ -76,6 +76,12 @@ impl Server {
         let http_server =
             dropshot::ServerBuilder::new(http_api(), sled_agent, dropshot_log)
                 .config(dropshot_config)
+                .version_policy(dropshot::VersionPolicy::Dynamic(Box::new(
+                    dropshot::ClientSpecifiesVersionInHeader::new(
+                        omicron_common::api::VERSION_HEADER,
+                        sled_agent_api::VERSION_INITIAL,
+                    ),
+                )))
                 .start()
                 .map_err(|error| format!("initializing server: {}", error))?;
 

From 2e7301dc1a25ed6e7e16a2a54d54dd9a6968afa3 Mon Sep 17 00:00:00 2001
From: iliana etaoin <iliana@oxide.computer>
Date: Tue, 19 Aug 2025 02:07:00 +0000
Subject: [PATCH 12/12] Revert "gateway: versionify"

This reverts commit a994f1fa7400b867d8c0cce8216bd315cab47754.
---
 Cargo.lock                                    |  2 --
 clients/gateway-client/src/lib.rs             |  2 +-
 dev-tools/openapi-manager/src/omicron.rs      |  2 +-
 gateway-api/Cargo.toml                        |  2 --
 gateway-api/src/lib.rs                        | 30 -------------------
 gateway/src/lib.rs                            |  6 ----
 ...gateway-1.0.0-12d926.json => gateway.json} |  2 +-
 openapi/gateway/gateway-latest.json           |  1 -
 8 files changed, 3 insertions(+), 44 deletions(-)
 rename openapi/{gateway/gateway-1.0.0-12d926.json => gateway.json} (99%)
 delete mode 120000 openapi/gateway/gateway-latest.json

diff --git a/Cargo.lock b/Cargo.lock
index a47e811973c..fa352d4a6e6 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -3668,9 +3668,7 @@ dependencies = [
  "omicron-common",
  "omicron-uuid-kinds",
  "omicron-workspace-hack",
- "openapi-manager-types",
  "schemars",
- "semver 1.0.26",
  "serde",
  "uuid",
 ]
diff --git a/clients/gateway-client/src/lib.rs b/clients/gateway-client/src/lib.rs
index d22fd2b3acb..4911dcaedfe 100644
--- a/clients/gateway-client/src/lib.rs
+++ b/clients/gateway-client/src/lib.rs
@@ -48,7 +48,7 @@ use types::ComponentFirmwareHashStatus;
 // call into each other. Since `gateway` is a lower-level service and never
 // calls into Nexus, the current scheme is okay.)
 progenitor::generate_api!(
-    spec = "../../openapi/gateway/gateway-latest.json",
+    spec = "../../openapi/gateway.json",
     interface = Positional,
     inner_type = slog::Logger,
     pre_hook = (|log: &slog::Logger, request: &reqwest::Request| {
diff --git a/dev-tools/openapi-manager/src/omicron.rs b/dev-tools/openapi-manager/src/omicron.rs
index 15857be598f..e31956b5e73 100644
--- a/dev-tools/openapi-manager/src/omicron.rs
+++ b/dev-tools/openapi-manager/src/omicron.rs
@@ -98,7 +98,7 @@ pub fn all_apis() -> Vec<ManagedApiConfig> {
         },
         ManagedApiConfig {
             title: "Oxide Management Gateway Service API",
-            versions: Versions::new_versioned(gateway_api::supported_versions()),
+            versions: Versions::new_lockstep(semver::Version::new(0, 0, 1)),
             description: "API for interacting with the Oxide \
                 control plane's gateway service",
             boundary: ApiBoundary::Internal,
diff --git a/gateway-api/Cargo.toml b/gateway-api/Cargo.toml
index b5a10dd6907..45aa8d4fa83 100644
--- a/gateway-api/Cargo.toml
+++ b/gateway-api/Cargo.toml
@@ -14,8 +14,6 @@ gateway-types.workspace = true
 omicron-common.workspace = true
 omicron-uuid-kinds.workspace = true
 omicron-workspace-hack.workspace = true
-openapi-manager-types.workspace = true
 schemars.workspace = true
-semver.workspace = true
 serde.workspace = true
 uuid.workspace = true
diff --git a/gateway-api/src/lib.rs b/gateway-api/src/lib.rs
index 1b502def255..115e50b5d1c 100644
--- a/gateway-api/src/lib.rs
+++ b/gateway-api/src/lib.rs
@@ -26,40 +26,10 @@ use gateway_types::{
         SpComponentResetError, SpUpdateStatus,
     },
 };
-use openapi_manager_types::{
-    SupportedVersion, SupportedVersions, api_versions,
-};
 use schemars::JsonSchema;
 use serde::Deserialize;
 use uuid::Uuid;
 
-api_versions!([
-    // WHEN CHANGING THE API (part 1 of 2):
-    //
-    // +- Pick a new semver and define it in the list below.  The list MUST
-    // |  remain sorted, which generally means that your version should go at
-    // |  the very top.
-    // |
-    // |  Duplicate this line, uncomment the *second* copy, update that copy for
-    // |  your new API version, and leave the first copy commented out as an
-    // |  example for the next person.
-    // v
-    // (next_int, IDENT),
-    (1, INITIAL),
-]);
-
-// WHEN CHANGING THE API (part 2 of 2):
-//
-// The call to `api_versions!` above defines constants of type
-// `semver::Version` that you can use in your Dropshot API definition to specify
-// the version when a particular endpoint was added or removed.  For example, if
-// you used:
-//
-//     (2, ADD_FOOBAR)
-//
-// Then you could use `VERSION_ADD_FOOBAR` as the version in which endpoints
-// were added or removed.
-
 /// This endpoint is used to upload SP and ROT Hubris archives as well as phase 1 host OS
 /// images. The phase 1 image is 32 MiB, driven by the QSPI flash on hardware.
 const SP_COMPONENT_UPDATE_MAX_BYTES: usize = 64 * 1024 * 1024;
diff --git a/gateway/src/lib.rs b/gateway/src/lib.rs
index 1d5eb70d28b..484f33d1899 100644
--- a/gateway/src/lib.rs
+++ b/gateway/src/lib.rs
@@ -103,12 +103,6 @@ fn start_dropshot_server(
                 log.new(o!("component" => "dropshot")),
             )
             .config(dropshot)
-            .version_policy(dropshot::VersionPolicy::Dynamic(Box::new(
-                dropshot::ClientSpecifiesVersionInHeader::new(
-                    omicron_common::api::VERSION_HEADER,
-                    gateway_api::VERSION_INITIAL,
-                ),
-            )))
             .start()
             .map_err(|error| {
                 format!(
diff --git a/openapi/gateway/gateway-1.0.0-12d926.json b/openapi/gateway.json
similarity index 99%
rename from openapi/gateway/gateway-1.0.0-12d926.json
rename to openapi/gateway.json
index 40d06e77146..bfd2b97cefc 100644
--- a/openapi/gateway/gateway-1.0.0-12d926.json
+++ b/openapi/gateway.json
@@ -7,7 +7,7 @@
       "url": "https://oxide.computer",
       "email": "api@oxide.computer"
     },
-    "version": "1.0.0"
+    "version": "0.0.1"
   },
   "paths": {
     "/ignition": {
diff --git a/openapi/gateway/gateway-latest.json b/openapi/gateway/gateway-latest.json
deleted file mode 120000
index 7a5bcae6802..00000000000
--- a/openapi/gateway/gateway-latest.json
+++ /dev/null
@@ -1 +0,0 @@
-gateway-1.0.0-12d926.json
\ No newline at end of file