From eb37a7891e52361d83a5113a9a1b5c0c7d5dc16d Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Tue, 20 Aug 2024 11:32:29 +0200
Subject: [PATCH 1/3] chore: move hub API to /reference

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
---
 .htmltest.yml                                  |  2 +-
 content/docker-hub/_index.md                   |  2 +-
 content/docker-hub/release-notes.md            |  2 +-
 content/reference/_index.md                    |  4 ++--
 .../api/docker-hub}/deprecated.md              | 18 ++++++++++--------
 .../api => reference/api/docker-hub}/dvp.md    |  0
 .../api => reference/api/docker-hub}/dvp.yaml  |  2 +-
 .../api => reference/api/docker-hub}/latest.md |  0
 .../api/docker-hub}/latest.yaml                |  0
 .../security/faqs/single-sign-on/users-faqs.md |  2 +-
 .../security/for-admins/provisioning/scim.md   |  2 +-
 content/trusted-content/insights-analytics.md  |  4 ++--
 data/redirects.yml                             |  4 ++++
 data/toc.yaml                                  |  6 +++---
 layouts/_default/hub-api-baseof.html           |  4 ++--
 15 files changed, 29 insertions(+), 23 deletions(-)
 rename content/{docker-hub/api => reference/api/docker-hub}/deprecated.md (65%)
 rename content/{docker-hub/api => reference/api/docker-hub}/dvp.md (100%)
 rename content/{docker-hub/api => reference/api/docker-hub}/dvp.yaml (99%)
 rename content/{docker-hub/api => reference/api/docker-hub}/latest.md (100%)
 rename content/{docker-hub/api => reference/api/docker-hub}/latest.yaml (100%)

diff --git a/.htmltest.yml b/.htmltest.yml
index 2af58c68c0fc..cfb602d51383 100644
--- a/.htmltest.yml
+++ b/.htmltest.yml
@@ -7,7 +7,7 @@ IgnoreAltEmpty: true
 IgnoreEmptyHref: true
 IgnoreDirectoryMissingTrailingSlash: true
 IgnoreURLs:
-- "^/docker-hub/api/latest/.*$"
+- "^/reference/api/docker-hub/.*$"
 - "^/engine/api/v.+/#.*$"
 - "^/glossary/.*$"
 IgnoreDirs:
diff --git a/content/docker-hub/_index.md b/content/docker-hub/_index.md
index 210300b3e07a..ce411f4062c4 100644
--- a/content/docker-hub/_index.md
+++ b/content/docker-hub/_index.md
@@ -40,7 +40,7 @@ GitHub and Bitbucket and push them to Docker Hub.
 * [Webhooks](webhooks.md): Trigger actions after a successful push
   to a repository to integrate Docker Hub with other services.
 * [Docker Hub CLI](https://github.com/docker/hub-tool#readme) tool (currently experimental) and an API that allows you to interact with Docker Hub.
-  * Browse through the [Docker Hub API](/docker-hub/api/latest/) documentation to explore the supported endpoints.
+  * Browse through the [Docker Hub API](/reference/api/docker-hub/latest/) documentation to explore the supported endpoints.
 {{< /tab >}}
 {{< tab name="What administrative tasks can I perform in Docker Hub?" >}}
 * [Create and manage teams and organizations](orgs.md)
diff --git a/content/docker-hub/release-notes.md b/content/docker-hub/release-notes.md
index 27b5fd6757f6..d45adb116f89 100644
--- a/content/docker-hub/release-notes.md
+++ b/content/docker-hub/release-notes.md
@@ -139,7 +139,7 @@ The updated [Docker Subscription Service Agreement](https://www.docker.com/legal
 
 When managing the content of your repositories, you can now filter the results based on the currentness of the tags and more easily identify your untagged images.
 
-For Docker Hub API documentation, see [Docker Hub API Reference](api/latest.md#operation/GetNamespacesRepositoriesImages).
+For Docker Hub API documentation, see [Docker Hub API Reference](/reference/api/docker-hub/latest.md#operation/GetNamespacesRepositoriesImages).
 
 ## 2021-04-13
 
diff --git a/content/reference/_index.md b/content/reference/_index.md
index dc8d1d007e8e..f18009fcc71a 100644
--- a/content/reference/_index.md
+++ b/content/reference/_index.md
@@ -37,11 +37,11 @@ grid_apis:
 - title: Docker Hub API
   description: API to interact with Docker Hub.
   icon: communities
-  link: /docker-hub/api/latest/
+  link: /reference/api/docker-hub/latest/
 - title: DVP Data API
   description: API for Docker Verified Publishers to fetch analytics data.
   icon: area_chart
-  link: /docker-hub/api/dvp/
+  link: /reference/api/docker-hub/dvp/
 ---
 
 This section includes the reference documentation for the Docker platform's
diff --git a/content/docker-hub/api/deprecated.md b/content/reference/api/docker-hub/deprecated.md
similarity index 65%
rename from content/docker-hub/api/deprecated.md
rename to content/reference/api/docker-hub/deprecated.md
index 26cde3fe7969..218aaf82ee93 100644
--- a/content/docker-hub/api/deprecated.md
+++ b/content/reference/api/docker-hub/deprecated.md
@@ -2,6 +2,8 @@
 description: Docker Hub API v1 (deprecated)
 keywords: kitematic, deprecated
 title: Docker Hub API v1 (deprecated)
+aliases:
+  - /docker-hub/api/deprecated/
 ---
 
 > **Deprecated**
@@ -18,11 +20,11 @@ The following API routes within the v1 path will no longer work and will return
 
 If you want to continue using the Docker Hub API in your current applications, update your clients to use v2 endpoints.
 
-| **OLD**                                                                                                                                                              | **NEW**                                                                                                                                                                                                         |
-|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| [/v1/repositories/{name}/images](https://github.com/moby/moby/blob/v1.3.0/docs/sources/reference/api/docker-io_api.md#list-user-repository-images)                   | [/v2/namespaces/{namespace}/repositories/{repository}/images](../../docker-hub/api/latest.md#tag/images/operation/GetNamespacesRepositoriesImages)                                                              |
-| [/v1/repositories/{namespace}/{name}/images](https://github.com/moby/moby/blob/v1.3.0/docs/sources/reference/api/docker-io_api.md#list-user-repository-images)       | [/v2/namespaces/{namespace}/repositories/{repository}/images](../../docker-hub/api/latest.md#tag/images/operation/GetNamespacesRepositoriesImages)                                                              |
-| [/v1/repositories/{name}/tags](https://github.com/moby/moby/blob/v1.8.3/docs/reference/api/registry_api.md#list-repository-tags)                                     | [/v2/namespaces/{namespace}/repositories/{repository}/tags](../../docker-hub/api/latest.md#tag/repositories/paths/~1v2~1namespaces~1%7Bnamespace%7D~1repositories~1%7Brepository%7D~1tags/get)                  |
-| [/v1/repositories/{namespace}/{name}/tags](https://github.com/moby/moby/blob/v1.8.3/docs/reference/api/registry_api.md#list-repository-tags)                         | [/v2/namespaces/{namespace}/repositories/{repository}/tags](../../docker-hub/api/latest.md#tag/repositories/paths/~1v2~1namespaces~1%7Bnamespace%7D~1repositories~1%7Brepository%7D~1tags/get)                  |
-| [/v1/repositories/{namespace}/{name}/tags](https://github.com/moby/moby/blob/v1.8.3/docs/reference/api/registry_api.md#get-image-id-for-a-particular-tag)            | [/v2/namespaces/{namespace}/repositories/{repository}/tags/{tag}](../../docker-hub/api/latest.md#tag/repositories/paths/~1v2~1namespaces~1%7Bnamespace%7D~1repositories~1%7Brepository%7D~1tags~1%7Btag%7D/get) |
-| [/v1/repositories/{namespace}/{name}/tags/{tag_name}](https://github.com/moby/moby/blob/v1.8.3/docs/reference/api/registry_api.md#get-image-id-for-a-particular-tag) | [/v2/namespaces/{namespace}/repositories/{repository}/tags/{tag}](../../docker-hub/api/latest.md#tag/repositories/paths/~1v2~1namespaces~1%7Bnamespace%7D~1repositories~1%7Brepository%7D~1tags~1%7Btag%7D/get) |
+| **OLD**                                                                                                                                                              | **NEW**                                                                                                                                                                                                              |
+|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [/v1/repositories/{name}/images](https://github.com/moby/moby/blob/v1.3.0/docs/sources/reference/api/docker-io_api.md#list-user-repository-images)                   | [/v2/namespaces/{namespace}/repositories/{repository}/images](/reference/api/docker-hub/latest.md#tag/images/operation/GetNamespacesRepositoriesImages)                                                              |
+| [/v1/repositories/{namespace}/{name}/images](https://github.com/moby/moby/blob/v1.3.0/docs/sources/reference/api/docker-io_api.md#list-user-repository-images)       | [/v2/namespaces/{namespace}/repositories/{repository}/images](/reference/api/docker-hub/latest.md#tag/images/operation/GetNamespacesRepositoriesImages)                                                              |
+| [/v1/repositories/{name}/tags](https://github.com/moby/moby/blob/v1.8.3/docs/reference/api/registry_api.md#list-repository-tags)                                     | [/v2/namespaces/{namespace}/repositories/{repository}/tags](/reference/api/docker-hub/latest.md#tag/repositories/paths/~1v2~1namespaces~1%7Bnamespace%7D~1repositories~1%7Brepository%7D~1tags/get)                  |
+| [/v1/repositories/{namespace}/{name}/tags](https://github.com/moby/moby/blob/v1.8.3/docs/reference/api/registry_api.md#list-repository-tags)                         | [/v2/namespaces/{namespace}/repositories/{repository}/tags](/reference/api/docker-hub/latest.md#tag/repositories/paths/~1v2~1namespaces~1%7Bnamespace%7D~1repositories~1%7Brepository%7D~1tags/get)                  |
+| [/v1/repositories/{namespace}/{name}/tags](https://github.com/moby/moby/blob/v1.8.3/docs/reference/api/registry_api.md#get-image-id-for-a-particular-tag)            | [/v2/namespaces/{namespace}/repositories/{repository}/tags/{tag}](/reference/api/docker-hub/latest.md#tag/repositories/paths/~1v2~1namespaces~1%7Bnamespace%7D~1repositories~1%7Brepository%7D~1tags~1%7Btag%7D/get) |
+| [/v1/repositories/{namespace}/{name}/tags/{tag_name}](https://github.com/moby/moby/blob/v1.8.3/docs/reference/api/registry_api.md#get-image-id-for-a-particular-tag) | [/v2/namespaces/{namespace}/repositories/{repository}/tags/{tag}](/reference/api/docker-hub/latest.md#tag/repositories/paths/~1v2~1namespaces~1%7Bnamespace%7D~1repositories~1%7Brepository%7D~1tags~1%7Btag%7D/get) |
diff --git a/content/docker-hub/api/dvp.md b/content/reference/api/docker-hub/dvp.md
similarity index 100%
rename from content/docker-hub/api/dvp.md
rename to content/reference/api/docker-hub/dvp.md
diff --git a/content/docker-hub/api/dvp.yaml b/content/reference/api/docker-hub/dvp.yaml
similarity index 99%
rename from content/docker-hub/api/dvp.yaml
rename to content/reference/api/docker-hub/dvp.yaml
index e30353aded6d..671396822b1b 100644
--- a/content/docker-hub/api/dvp.yaml
+++ b/content/reference/api/docker-hub/dvp.yaml
@@ -690,5 +690,5 @@ components:
       description: |
         JWT Bearer Authentication is required to access the Docker DVP Data API.  
           
-        This authentication documentation is duplicated from the [Hub API Authentication docs](https://docs.docker.com/docker-hub/api/latest/#tag/authentication)
+        This authentication documentation is duplicated from the [Hub API Authentication docs](https://docs.docker.com/reference/api/docker-hub/#tag/authentication)
       x-displayName: Docker Hub Authentication
diff --git a/content/docker-hub/api/latest.md b/content/reference/api/docker-hub/latest.md
similarity index 100%
rename from content/docker-hub/api/latest.md
rename to content/reference/api/docker-hub/latest.md
diff --git a/content/docker-hub/api/latest.yaml b/content/reference/api/docker-hub/latest.yaml
similarity index 100%
rename from content/docker-hub/api/latest.yaml
rename to content/reference/api/docker-hub/latest.yaml
diff --git a/content/security/faqs/single-sign-on/users-faqs.md b/content/security/faqs/single-sign-on/users-faqs.md
index e698b448597b..177d98da6b53 100644
--- a/content/security/faqs/single-sign-on/users-faqs.md
+++ b/content/security/faqs/single-sign-on/users-faqs.md
@@ -63,7 +63,7 @@ Docker SSO provides Just-in-Time (JIT) provisioning by default, with an option t
 
 [SCIM](../../../security/for-admins/provisioning/scim/) is available to provide full synchronization with users and groups. When you auto-provision users with SCIM, the recommended configuration is to disable JIT so that all auto-provisioning is handled by SCIM.
 
-Additionally, you can use the [Docker Hub API](/docker-hub/api/latest/) to complete this process.
+Additionally, you can use the [Docker Hub API](/reference/api/docker-hub/latest/) to complete this process.
 
 ### How does disabling Just-in-Time provisioning impact user sign-in?
 
diff --git a/content/security/for-admins/provisioning/scim.md b/content/security/for-admins/provisioning/scim.md
index 49e1ace72925..93b4cdf213ae 100644
--- a/content/security/for-admins/provisioning/scim.md
+++ b/content/security/for-admins/provisioning/scim.md
@@ -31,7 +31,7 @@ The following table lists the supported attributes. Note that your attribute map
 | name.familyName | User’s surname |
 | active | Indicates if a user is enabled or disabled. Can be set to false to de-provision the user. |
 
-For additional details about supported attributes and SCIM, see [Docker Hub API SCIM reference](/docker-hub/api/latest/#tag/scim).
+For additional details about supported attributes and SCIM, see [Docker Hub API SCIM reference](/reference/api/docker-hub/latest/#tag/scim).
 
 > [!IMPORTANT]
 >
diff --git a/content/trusted-content/insights-analytics.md b/content/trusted-content/insights-analytics.md
index c54651e028e3..9dea519b193c 100644
--- a/content/trusted-content/insights-analytics.md
+++ b/content/trusted-content/insights-analytics.md
@@ -60,7 +60,7 @@ You can download extension CSV reports from the **Insights and analytics** dashb
 ## Exporting analytics data
 
 You can export the analytics data either from the web dashboard, or using the
-[DVP Data API](/docker-hub/api/dvp/). All members of an organization have access to the analytics data.
+[DVP Data API](/reference/api/docker-hub/dvp.md). All members of an organization have access to the analytics data.
 
 The data is available as a downloadable CSV file, in a weekly (Monday through
 Sunday) or monthly format. Monthly data is available from the first day of the
@@ -88,7 +88,7 @@ Export usage data for your organization's images using the Docker Hub website by
 
 The HTTP API endpoints are available at:
 `https://hub.docker.com/api/publisher/analytics/v1`. Learn how to export data
-using the API in the [DVP Data API documentation](/docker-hub/api/dvp/).
+using the API in the [DVP Data API documentation](/reference/api/docker-hub/dvp.md).
 
 ## Data points
 
diff --git a/data/redirects.yml b/data/redirects.yml
index f6f2b3769df6..074261fdbc58 100644
--- a/data/redirects.yml
+++ b/data/redirects.yml
@@ -101,6 +101,10 @@
 "/desktop/windows/wsl/":
   # Link used by Docker Desktop to refer users on how to activate WSL 2
   - /go/wsl2/
+"/reference/api/docker-hub/latest/":
+  - /docker-hub/api/latest/
+"/reference/api/docker-hub/dvp/":
+  - /docker-hub/api/dvp/
 
 # feedback
 "https://docs.google.com/forms/d/e/1FAIpQLSenjK8KiBiOrwCpq06u_iVEZGv4tfTEpfmY_cQDmsqJrHL9Gw/viewform":
diff --git a/data/toc.yaml b/data/toc.yaml
index b74db109e8d5..23d99de1d002 100644
--- a/data/toc.yaml
+++ b/data/toc.yaml
@@ -980,11 +980,11 @@ Reference:
   - sectiontitle: Docker Hub API
     section:
       - title: Docker Hub API
-        path: /docker-hub/api/latest/
+        path: /reference/api/docker-hub/latest/
       - title: DVP Data API
-        path: /docker-hub/api/dvp/
+        path: /reference/api/docker-hub/dvp/
       - title: Deprecated API
-        path: /docker-hub/api/deprecated/
+        path: /reference/api/docker-hub/deprecated/
   - sectiontitle: Docker Extension SDK API
     section:
       - path: /extensions/extensions-sdk/dev/api/reference/interfaces/DesktopUI/
diff --git a/layouts/_default/hub-api-baseof.html b/layouts/_default/hub-api-baseof.html
index b2c71ed47393..ef30b5d8c6fe 100644
--- a/layouts/_default/hub-api-baseof.html
+++ b/layouts/_default/hub-api-baseof.html
@@ -11,7 +11,7 @@
   <!-- favicon -->
   {{ partialCached "favicon.html" "favicon" }}
   <!-- make the latest API version the canonical page as that's what we want users to be using mostly -->
-  <link rel="canonical" href="{{ "/docker-hub/api/latest/" | relURL }}" />
+  <link rel="canonical" href="{{ "/reference/api/docker-hub/latest/" | relURL }}" />
   <style>
     body {
       margin: 0;
@@ -26,7 +26,7 @@
 </head>
 
 <body>
-  <redoc spec-url="/docker-hub/api/{{ .File.BaseFileName }}.yaml" class="hub-api"></redoc>
+  <redoc spec-url="/reference/api/docker-hub/{{ .File.BaseFileName }}.yaml" class="hub-api"></redoc>
   <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>
 </body>
 

From d969391357a31a71c98d4c4c29b97b24767b078b Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Tue, 20 Aug 2024 11:47:42 +0200
Subject: [PATCH 2/3] chore: move glossary to /reference

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
---
 .htmltest.yml                                        |  3 +--
 content/docker-hub/_index.md                         |  2 +-
 content/docker-hub/release-notes.md                  |  2 +-
 content/reference/_index.md                          |  4 ++--
 .../reference/api/{docker-hub => hub}/deprecated.md  | 12 ++++++------
 content/reference/api/{docker-hub => hub}/dvp.md     |  0
 content/reference/api/{docker-hub => hub}/dvp.yaml   |  2 +-
 content/reference/api/{docker-hub => hub}/latest.md  |  0
 .../reference/api/{docker-hub => hub}/latest.yaml    |  0
 content/{ => reference}/glossary.md                  |  2 +-
 content/security/faqs/single-sign-on/users-faqs.md   |  2 +-
 content/security/for-admins/provisioning/scim.md     |  2 +-
 content/trusted-content/insights-analytics.md        |  4 ++--
 data/redirects.yml                                   |  4 ++--
 data/toc.yaml                                        |  8 ++++----
 layouts/_default/hub-api-baseof.html                 |  4 ++--
 layouts/shortcodes/admin-org-onboarding.md           |  2 +-
 17 files changed, 26 insertions(+), 27 deletions(-)
 rename content/reference/api/{docker-hub => hub}/deprecated.md (69%)
 rename content/reference/api/{docker-hub => hub}/dvp.md (100%)
 rename content/reference/api/{docker-hub => hub}/dvp.yaml (99%)
 rename content/reference/api/{docker-hub => hub}/latest.md (100%)
 rename content/reference/api/{docker-hub => hub}/latest.yaml (100%)
 rename content/{ => reference}/glossary.md (93%)

diff --git a/.htmltest.yml b/.htmltest.yml
index cfb602d51383..c47bf6e48ad6 100644
--- a/.htmltest.yml
+++ b/.htmltest.yml
@@ -7,9 +7,8 @@ IgnoreAltEmpty: true
 IgnoreEmptyHref: true
 IgnoreDirectoryMissingTrailingSlash: true
 IgnoreURLs:
-- "^/reference/api/docker-hub/.*$"
+- "^/reference/api/hub/.*$"
 - "^/engine/api/v.+/#.*$"
-- "^/glossary/.*$"
 IgnoreDirs:
 - "engine/api"
 - "registry/configuration"
diff --git a/content/docker-hub/_index.md b/content/docker-hub/_index.md
index ce411f4062c4..4307e5e2a805 100644
--- a/content/docker-hub/_index.md
+++ b/content/docker-hub/_index.md
@@ -40,7 +40,7 @@ GitHub and Bitbucket and push them to Docker Hub.
 * [Webhooks](webhooks.md): Trigger actions after a successful push
   to a repository to integrate Docker Hub with other services.
 * [Docker Hub CLI](https://github.com/docker/hub-tool#readme) tool (currently experimental) and an API that allows you to interact with Docker Hub.
-  * Browse through the [Docker Hub API](/reference/api/docker-hub/latest/) documentation to explore the supported endpoints.
+  * Browse through the [Docker Hub API](/reference/api/hub/latest/) documentation to explore the supported endpoints.
 {{< /tab >}}
 {{< tab name="What administrative tasks can I perform in Docker Hub?" >}}
 * [Create and manage teams and organizations](orgs.md)
diff --git a/content/docker-hub/release-notes.md b/content/docker-hub/release-notes.md
index d45adb116f89..1f699aa51ead 100644
--- a/content/docker-hub/release-notes.md
+++ b/content/docker-hub/release-notes.md
@@ -139,7 +139,7 @@ The updated [Docker Subscription Service Agreement](https://www.docker.com/legal
 
 When managing the content of your repositories, you can now filter the results based on the currentness of the tags and more easily identify your untagged images.
 
-For Docker Hub API documentation, see [Docker Hub API Reference](/reference/api/docker-hub/latest.md#operation/GetNamespacesRepositoriesImages).
+For Docker Hub API documentation, see [Docker Hub API Reference](/reference/api/hub/latest.md#operation/GetNamespacesRepositoriesImages).
 
 ## 2021-04-13
 
diff --git a/content/reference/_index.md b/content/reference/_index.md
index f18009fcc71a..d03daffad753 100644
--- a/content/reference/_index.md
+++ b/content/reference/_index.md
@@ -37,11 +37,11 @@ grid_apis:
 - title: Docker Hub API
   description: API to interact with Docker Hub.
   icon: communities
-  link: /reference/api/docker-hub/latest/
+  link: /reference/api/hub/latest/
 - title: DVP Data API
   description: API for Docker Verified Publishers to fetch analytics data.
   icon: area_chart
-  link: /reference/api/docker-hub/dvp/
+  link: /reference/api/hub/dvp/
 ---
 
 This section includes the reference documentation for the Docker platform's
diff --git a/content/reference/api/docker-hub/deprecated.md b/content/reference/api/hub/deprecated.md
similarity index 69%
rename from content/reference/api/docker-hub/deprecated.md
rename to content/reference/api/hub/deprecated.md
index 218aaf82ee93..97adcf67ae08 100644
--- a/content/reference/api/docker-hub/deprecated.md
+++ b/content/reference/api/hub/deprecated.md
@@ -22,9 +22,9 @@ If you want to continue using the Docker Hub API in your current applications, u
 
 | **OLD**                                                                                                                                                              | **NEW**                                                                                                                                                                                                              |
 |----------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [/v1/repositories/{name}/images](https://github.com/moby/moby/blob/v1.3.0/docs/sources/reference/api/docker-io_api.md#list-user-repository-images)                   | [/v2/namespaces/{namespace}/repositories/{repository}/images](/reference/api/docker-hub/latest.md#tag/images/operation/GetNamespacesRepositoriesImages)                                                              |
-| [/v1/repositories/{namespace}/{name}/images](https://github.com/moby/moby/blob/v1.3.0/docs/sources/reference/api/docker-io_api.md#list-user-repository-images)       | [/v2/namespaces/{namespace}/repositories/{repository}/images](/reference/api/docker-hub/latest.md#tag/images/operation/GetNamespacesRepositoriesImages)                                                              |
-| [/v1/repositories/{name}/tags](https://github.com/moby/moby/blob/v1.8.3/docs/reference/api/registry_api.md#list-repository-tags)                                     | [/v2/namespaces/{namespace}/repositories/{repository}/tags](/reference/api/docker-hub/latest.md#tag/repositories/paths/~1v2~1namespaces~1%7Bnamespace%7D~1repositories~1%7Brepository%7D~1tags/get)                  |
-| [/v1/repositories/{namespace}/{name}/tags](https://github.com/moby/moby/blob/v1.8.3/docs/reference/api/registry_api.md#list-repository-tags)                         | [/v2/namespaces/{namespace}/repositories/{repository}/tags](/reference/api/docker-hub/latest.md#tag/repositories/paths/~1v2~1namespaces~1%7Bnamespace%7D~1repositories~1%7Brepository%7D~1tags/get)                  |
-| [/v1/repositories/{namespace}/{name}/tags](https://github.com/moby/moby/blob/v1.8.3/docs/reference/api/registry_api.md#get-image-id-for-a-particular-tag)            | [/v2/namespaces/{namespace}/repositories/{repository}/tags/{tag}](/reference/api/docker-hub/latest.md#tag/repositories/paths/~1v2~1namespaces~1%7Bnamespace%7D~1repositories~1%7Brepository%7D~1tags~1%7Btag%7D/get) |
-| [/v1/repositories/{namespace}/{name}/tags/{tag_name}](https://github.com/moby/moby/blob/v1.8.3/docs/reference/api/registry_api.md#get-image-id-for-a-particular-tag) | [/v2/namespaces/{namespace}/repositories/{repository}/tags/{tag}](/reference/api/docker-hub/latest.md#tag/repositories/paths/~1v2~1namespaces~1%7Bnamespace%7D~1repositories~1%7Brepository%7D~1tags~1%7Btag%7D/get) |
+| [/v1/repositories/{name}/images](https://github.com/moby/moby/blob/v1.3.0/docs/sources/reference/api/docker-io_api.md#list-user-repository-images)                   | [/v2/namespaces/{namespace}/repositories/{repository}/images](/reference/api/hub/latest.md#tag/images/operation/GetNamespacesRepositoriesImages)                                                              |
+| [/v1/repositories/{namespace}/{name}/images](https://github.com/moby/moby/blob/v1.3.0/docs/sources/reference/api/docker-io_api.md#list-user-repository-images)       | [/v2/namespaces/{namespace}/repositories/{repository}/images](/reference/api/hub/latest.md#tag/images/operation/GetNamespacesRepositoriesImages)                                                              |
+| [/v1/repositories/{name}/tags](https://github.com/moby/moby/blob/v1.8.3/docs/reference/api/registry_api.md#list-repository-tags)                                     | [/v2/namespaces/{namespace}/repositories/{repository}/tags](/reference/api/hub/latest.md#tag/repositories/paths/~1v2~1namespaces~1%7Bnamespace%7D~1repositories~1%7Brepository%7D~1tags/get)                  |
+| [/v1/repositories/{namespace}/{name}/tags](https://github.com/moby/moby/blob/v1.8.3/docs/reference/api/registry_api.md#list-repository-tags)                         | [/v2/namespaces/{namespace}/repositories/{repository}/tags](/reference/api/hub/latest.md#tag/repositories/paths/~1v2~1namespaces~1%7Bnamespace%7D~1repositories~1%7Brepository%7D~1tags/get)                  |
+| [/v1/repositories/{namespace}/{name}/tags](https://github.com/moby/moby/blob/v1.8.3/docs/reference/api/registry_api.md#get-image-id-for-a-particular-tag)            | [/v2/namespaces/{namespace}/repositories/{repository}/tags/{tag}](/reference/api/hub/latest.md#tag/repositories/paths/~1v2~1namespaces~1%7Bnamespace%7D~1repositories~1%7Brepository%7D~1tags~1%7Btag%7D/get) |
+| [/v1/repositories/{namespace}/{name}/tags/{tag_name}](https://github.com/moby/moby/blob/v1.8.3/docs/reference/api/registry_api.md#get-image-id-for-a-particular-tag) | [/v2/namespaces/{namespace}/repositories/{repository}/tags/{tag}](/reference/api/hub/latest.md#tag/repositories/paths/~1v2~1namespaces~1%7Bnamespace%7D~1repositories~1%7Brepository%7D~1tags~1%7Btag%7D/get) |
diff --git a/content/reference/api/docker-hub/dvp.md b/content/reference/api/hub/dvp.md
similarity index 100%
rename from content/reference/api/docker-hub/dvp.md
rename to content/reference/api/hub/dvp.md
diff --git a/content/reference/api/docker-hub/dvp.yaml b/content/reference/api/hub/dvp.yaml
similarity index 99%
rename from content/reference/api/docker-hub/dvp.yaml
rename to content/reference/api/hub/dvp.yaml
index 671396822b1b..3b9becb0418b 100644
--- a/content/reference/api/docker-hub/dvp.yaml
+++ b/content/reference/api/hub/dvp.yaml
@@ -690,5 +690,5 @@ components:
       description: |
         JWT Bearer Authentication is required to access the Docker DVP Data API.  
           
-        This authentication documentation is duplicated from the [Hub API Authentication docs](https://docs.docker.com/reference/api/docker-hub/#tag/authentication)
+        This authentication documentation is duplicated from the [Hub API Authentication docs](https://docs.docker.com/reference/api/hub/#tag/authentication)
       x-displayName: Docker Hub Authentication
diff --git a/content/reference/api/docker-hub/latest.md b/content/reference/api/hub/latest.md
similarity index 100%
rename from content/reference/api/docker-hub/latest.md
rename to content/reference/api/hub/latest.md
diff --git a/content/reference/api/docker-hub/latest.yaml b/content/reference/api/hub/latest.yaml
similarity index 100%
rename from content/reference/api/docker-hub/latest.yaml
rename to content/reference/api/hub/latest.yaml
diff --git a/content/glossary.md b/content/reference/glossary.md
similarity index 93%
rename from content/glossary.md
rename to content/reference/glossary.md
index 5b51b274c8a4..5f26de459e81 100644
--- a/content/glossary.md
+++ b/content/reference/glossary.md
@@ -6,7 +6,7 @@ layout: glossary
 notoc: true
 aliases:
 - /engine/reference/glossary/
-- /reference/glossary/
+- /glossary/
 ---
 
 <!--
diff --git a/content/security/faqs/single-sign-on/users-faqs.md b/content/security/faqs/single-sign-on/users-faqs.md
index 177d98da6b53..ba720c937166 100644
--- a/content/security/faqs/single-sign-on/users-faqs.md
+++ b/content/security/faqs/single-sign-on/users-faqs.md
@@ -63,7 +63,7 @@ Docker SSO provides Just-in-Time (JIT) provisioning by default, with an option t
 
 [SCIM](../../../security/for-admins/provisioning/scim/) is available to provide full synchronization with users and groups. When you auto-provision users with SCIM, the recommended configuration is to disable JIT so that all auto-provisioning is handled by SCIM.
 
-Additionally, you can use the [Docker Hub API](/reference/api/docker-hub/latest/) to complete this process.
+Additionally, you can use the [Docker Hub API](/reference/api/hub/latest/) to complete this process.
 
 ### How does disabling Just-in-Time provisioning impact user sign-in?
 
diff --git a/content/security/for-admins/provisioning/scim.md b/content/security/for-admins/provisioning/scim.md
index 93b4cdf213ae..0685c0eb827d 100644
--- a/content/security/for-admins/provisioning/scim.md
+++ b/content/security/for-admins/provisioning/scim.md
@@ -31,7 +31,7 @@ The following table lists the supported attributes. Note that your attribute map
 | name.familyName | User’s surname |
 | active | Indicates if a user is enabled or disabled. Can be set to false to de-provision the user. |
 
-For additional details about supported attributes and SCIM, see [Docker Hub API SCIM reference](/reference/api/docker-hub/latest/#tag/scim).
+For additional details about supported attributes and SCIM, see [Docker Hub API SCIM reference](/reference/api/hub/latest/#tag/scim).
 
 > [!IMPORTANT]
 >
diff --git a/content/trusted-content/insights-analytics.md b/content/trusted-content/insights-analytics.md
index 9dea519b193c..c2dead2bbdc9 100644
--- a/content/trusted-content/insights-analytics.md
+++ b/content/trusted-content/insights-analytics.md
@@ -60,7 +60,7 @@ You can download extension CSV reports from the **Insights and analytics** dashb
 ## Exporting analytics data
 
 You can export the analytics data either from the web dashboard, or using the
-[DVP Data API](/reference/api/docker-hub/dvp.md). All members of an organization have access to the analytics data.
+[DVP Data API](/reference/api/hub/dvp.md). All members of an organization have access to the analytics data.
 
 The data is available as a downloadable CSV file, in a weekly (Monday through
 Sunday) or monthly format. Monthly data is available from the first day of the
@@ -88,7 +88,7 @@ Export usage data for your organization's images using the Docker Hub website by
 
 The HTTP API endpoints are available at:
 `https://hub.docker.com/api/publisher/analytics/v1`. Learn how to export data
-using the API in the [DVP Data API documentation](/reference/api/docker-hub/dvp.md).
+using the API in the [DVP Data API documentation](/reference/api/hub/dvp.md).
 
 ## Data points
 
diff --git a/data/redirects.yml b/data/redirects.yml
index 074261fdbc58..a78306b9a765 100644
--- a/data/redirects.yml
+++ b/data/redirects.yml
@@ -101,9 +101,9 @@
 "/desktop/windows/wsl/":
   # Link used by Docker Desktop to refer users on how to activate WSL 2
   - /go/wsl2/
-"/reference/api/docker-hub/latest/":
+"/reference/api/hub/latest/":
   - /docker-hub/api/latest/
-"/reference/api/docker-hub/dvp/":
+"/reference/api/hub/dvp/":
   - /docker-hub/api/dvp/
 
 # feedback
diff --git a/data/toc.yaml b/data/toc.yaml
index 23d99de1d002..0489d6f29ab3 100644
--- a/data/toc.yaml
+++ b/data/toc.yaml
@@ -980,11 +980,11 @@ Reference:
   - sectiontitle: Docker Hub API
     section:
       - title: Docker Hub API
-        path: /reference/api/docker-hub/latest/
+        path: /reference/api/hub/latest/
       - title: DVP Data API
-        path: /reference/api/docker-hub/dvp/
+        path: /reference/api/hub/dvp/
       - title: Deprecated API
-        path: /reference/api/docker-hub/deprecated/
+        path: /reference/api/hub/deprecated/
   - sectiontitle: Docker Extension SDK API
     section:
       - path: /extensions/extensions-sdk/dev/api/reference/interfaces/DesktopUI/
@@ -1075,7 +1075,7 @@ Reference:
       title: Compose Develop Specification
     - path: /reference/compose-file/legacy-versions/
       title: Legacy versions
-- path: /glossary/
+- path: /reference/glossary/
   title: Glossary
 - sectiontitle: Samples
   section:
diff --git a/layouts/_default/hub-api-baseof.html b/layouts/_default/hub-api-baseof.html
index ef30b5d8c6fe..316da6f0f10d 100644
--- a/layouts/_default/hub-api-baseof.html
+++ b/layouts/_default/hub-api-baseof.html
@@ -11,7 +11,7 @@
   <!-- favicon -->
   {{ partialCached "favicon.html" "favicon" }}
   <!-- make the latest API version the canonical page as that's what we want users to be using mostly -->
-  <link rel="canonical" href="{{ "/reference/api/docker-hub/latest/" | relURL }}" />
+  <link rel="canonical" href="{{ "/reference/api/hub/latest/" | relURL }}" />
   <style>
     body {
       margin: 0;
@@ -26,7 +26,7 @@
 </head>
 
 <body>
-  <redoc spec-url="/reference/api/docker-hub/{{ .File.BaseFileName }}.yaml" class="hub-api"></redoc>
+  <redoc spec-url="/reference/api/hub/{{ .File.BaseFileName }}.yaml" class="hub-api"></redoc>
   <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>
 </body>
 
diff --git a/layouts/shortcodes/admin-org-onboarding.md b/layouts/shortcodes/admin-org-onboarding.md
index e8ee89f17f76..bfa7d734d599 100644
--- a/layouts/shortcodes/admin-org-onboarding.md
+++ b/layouts/shortcodes/admin-org-onboarding.md
@@ -16,7 +16,7 @@ Before you start to onboard your organization, ensure that you:
   >
   > When purchasing a self-serve subscription, the on-screen instructions guide you through creating an organization. If you have purchased a subscription through Docker Sales and you have not yet created an organization, see [Create an organization](/admin/organization/orgs).
 
-- Familiarize yourself with Docker concepts and terminology in the [glossary](/glossary/) and [FAQs](/faq/admin/general-faqs/).
+- Familiarize yourself with Docker concepts and terminology in the [glossary](/reference/glossary/) and [FAQs](/faq/admin/general-faqs/).
 
 ## Step 1: Identify your Docker users and their Docker accounts
 

From 2018844f1e388268878e68903f6caf67d9cba33b Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Tue, 20 Aug 2024 12:16:13 +0200
Subject: [PATCH 3/3] chore: move engine API to /reference

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
---
 .htmltest.yml                                 |   3 +-
 content/desktop/faqs/general.md               |   2 +-
 content/engine/_index.md                      |   2 +-
 content/engine/api/_index.md                  | 166 ------------------
 content/engine/api/latest/index.html          |   6 -
 content/engine/api/v1.25.md                   |   5 -
 content/engine/api/v1.26.md                   |   5 -
 content/engine/api/v1.27.md                   |   5 -
 content/engine/api/v1.28.md                   |   5 -
 content/engine/api/v1.29.md                   |   3 -
 content/engine/api/v1.30.md                   |   3 -
 content/engine/api/v1.31.md                   |   3 -
 content/engine/api/v1.32.md                   |   3 -
 content/engine/api/v1.33.md                   |   3 -
 content/engine/api/v1.34.md                   |   3 -
 content/engine/api/v1.35.md                   |   3 -
 content/engine/api/v1.36.md                   |   3 -
 content/engine/api/v1.37.md                   |   3 -
 content/engine/api/v1.38.md                   |   3 -
 content/engine/api/v1.39.md                   |   3 -
 content/engine/api/v1.40.md                   |   3 -
 content/engine/api/v1.41.md                   |   3 -
 content/engine/api/v1.42.md                   |   3 -
 content/engine/api/v1.43.md                   |   3 -
 content/engine/api/v1.44.md                   |   3 -
 content/engine/api/v1.45.md                   |   3 -
 content/engine/api/v1.46.md                   |   3 -
 content/engine/release-notes/23.0.md          |   2 +-
 content/engine/release-notes/24.0.md          |   2 +-
 content/engine/release-notes/25.0.md          |   2 +-
 content/engine/release-notes/26.0.md          |   2 +-
 content/engine/release-notes/26.1.md          |   2 +-
 content/engine/release-notes/27.0.md          |   2 +-
 content/engine/release-notes/27.1.md          |   2 +-
 content/engine/swarm/admin_guide.md           |   2 +-
 .../swarm/how-swarm-mode-works/nodes.md       |   2 +-
 content/engine/swarm/manage-nodes.md          |   2 +-
 content/reference/_index.md                   |   2 +-
 content/reference/api/engine/_index.md        | 166 ++++++++++++++++++
 .../reference/api/engine/latest/index.html    |   6 +
 .../api/engine}/sdk/_index.md                 |  13 +-
 .../api/engine}/sdk/examples.md               |  13 +-
 content/reference/api/engine/v1.25.md         |   5 +
 content/reference/api/engine/v1.26.md         |   5 +
 content/reference/api/engine/v1.27.md         |   5 +
 content/reference/api/engine/v1.28.md         |   5 +
 content/reference/api/engine/v1.29.md         |   5 +
 content/reference/api/engine/v1.30.md         |   5 +
 content/reference/api/engine/v1.31.md         |   5 +
 content/reference/api/engine/v1.32.md         |   5 +
 content/reference/api/engine/v1.33.md         |   5 +
 content/reference/api/engine/v1.34.md         |   5 +
 content/reference/api/engine/v1.35.md         |   5 +
 content/reference/api/engine/v1.36.md         |   5 +
 content/reference/api/engine/v1.37.md         |   5 +
 content/reference/api/engine/v1.38.md         |   5 +
 content/reference/api/engine/v1.39.md         |   5 +
 content/reference/api/engine/v1.40.md         |   5 +
 content/reference/api/engine/v1.41.md         |   5 +
 content/reference/api/engine/v1.42.md         |   5 +
 content/reference/api/engine/v1.43.md         |   5 +
 content/reference/api/engine/v1.44.md         |   5 +
 content/reference/api/engine/v1.45.md         |   5 +
 content/reference/api/engine/v1.46.md         |   5 +
 data/engine-cli/docker_version.yaml           |   2 +-
 data/redirects.yml                            |   2 +-
 data/toc.yaml                                 |  56 +++---
 hugo.yaml                                     |   4 +-
 layouts/_default/engine-api-baseof.html       |   4 +-
 69 files changed, 344 insertions(+), 307 deletions(-)
 delete mode 100644 content/engine/api/_index.md
 delete mode 100644 content/engine/api/latest/index.html
 delete mode 100644 content/engine/api/v1.25.md
 delete mode 100644 content/engine/api/v1.26.md
 delete mode 100644 content/engine/api/v1.27.md
 delete mode 100644 content/engine/api/v1.28.md
 delete mode 100644 content/engine/api/v1.29.md
 delete mode 100644 content/engine/api/v1.30.md
 delete mode 100644 content/engine/api/v1.31.md
 delete mode 100644 content/engine/api/v1.32.md
 delete mode 100644 content/engine/api/v1.33.md
 delete mode 100644 content/engine/api/v1.34.md
 delete mode 100644 content/engine/api/v1.35.md
 delete mode 100644 content/engine/api/v1.36.md
 delete mode 100644 content/engine/api/v1.37.md
 delete mode 100644 content/engine/api/v1.38.md
 delete mode 100644 content/engine/api/v1.39.md
 delete mode 100644 content/engine/api/v1.40.md
 delete mode 100644 content/engine/api/v1.41.md
 delete mode 100644 content/engine/api/v1.42.md
 delete mode 100644 content/engine/api/v1.43.md
 delete mode 100644 content/engine/api/v1.44.md
 delete mode 100644 content/engine/api/v1.45.md
 delete mode 100644 content/engine/api/v1.46.md
 create mode 100644 content/reference/api/engine/_index.md
 create mode 100644 content/reference/api/engine/latest/index.html
 rename content/{engine/api => reference/api/engine}/sdk/_index.md (95%)
 rename content/{engine/api => reference/api/engine}/sdk/examples.md (98%)
 create mode 100644 content/reference/api/engine/v1.25.md
 create mode 100644 content/reference/api/engine/v1.26.md
 create mode 100644 content/reference/api/engine/v1.27.md
 create mode 100644 content/reference/api/engine/v1.28.md
 create mode 100644 content/reference/api/engine/v1.29.md
 create mode 100644 content/reference/api/engine/v1.30.md
 create mode 100644 content/reference/api/engine/v1.31.md
 create mode 100644 content/reference/api/engine/v1.32.md
 create mode 100644 content/reference/api/engine/v1.33.md
 create mode 100644 content/reference/api/engine/v1.34.md
 create mode 100644 content/reference/api/engine/v1.35.md
 create mode 100644 content/reference/api/engine/v1.36.md
 create mode 100644 content/reference/api/engine/v1.37.md
 create mode 100644 content/reference/api/engine/v1.38.md
 create mode 100644 content/reference/api/engine/v1.39.md
 create mode 100644 content/reference/api/engine/v1.40.md
 create mode 100644 content/reference/api/engine/v1.41.md
 create mode 100644 content/reference/api/engine/v1.42.md
 create mode 100644 content/reference/api/engine/v1.43.md
 create mode 100644 content/reference/api/engine/v1.44.md
 create mode 100644 content/reference/api/engine/v1.45.md
 create mode 100644 content/reference/api/engine/v1.46.md

diff --git a/.htmltest.yml b/.htmltest.yml
index c47bf6e48ad6..e7cb321e1bec 100644
--- a/.htmltest.yml
+++ b/.htmltest.yml
@@ -8,9 +8,8 @@ IgnoreEmptyHref: true
 IgnoreDirectoryMissingTrailingSlash: true
 IgnoreURLs:
 - "^/reference/api/hub/.*$"
-- "^/engine/api/v.+/#.*$"
+- "^/reference/api/engine/v.+/#.*$"
 IgnoreDirs:
-- "engine/api"
 - "registry/configuration"
 - "compose/compose-file" # temporarily ignore until upstream is fixed
 CacheExpires: "6h"
diff --git a/content/desktop/faqs/general.md b/content/desktop/faqs/general.md
index fce2a5a39174..33f2d3f60cde 100644
--- a/content/desktop/faqs/general.md
+++ b/content/desktop/faqs/general.md
@@ -49,7 +49,7 @@ $ export DOCKER_HOST=unix:///var/run/docker.sock
 Docker Desktop Windows users can connect to the Docker Engine through a **named pipe**: `npipe:////./pipe/docker_engine`, or **TCP socket** at this URL:
 `tcp://localhost:2375`.
 
-For details, see [Docker Engine API](../../engine/api/index.md).
+For details, see [Docker Engine API](/reference/api/engine/_index.md).
 
 ### How do I connect from a container to a service on the host?
 
diff --git a/content/engine/_index.md b/content/engine/_index.md
index b65ebff2514f..e5e9a0218b01 100644
--- a/content/engine/_index.md
+++ b/content/engine/_index.md
@@ -58,7 +58,7 @@ application with:
 - A command line interface (CLI) client
   [`docker`](/reference/cli/docker/).
 
-The CLI uses [Docker APIs](api/index.md) to control or interact with the Docker
+The CLI uses [Docker APIs](/reference/api/engine/_index.md) to control or interact with the Docker
 daemon through scripting or direct CLI commands. Many other Docker applications
 use the underlying API and CLI. The daemon creates and manages Docker objects,
 such as images, containers, networks, and volumes.
diff --git a/content/engine/api/_index.md b/content/engine/api/_index.md
deleted file mode 100644
index 4d47ca3fe0a0..000000000000
--- a/content/engine/api/_index.md
+++ /dev/null
@@ -1,166 +0,0 @@
----
-title: Develop with Docker Engine API
-description: Learn how you can use Docker Engine API and SDKs in the language of your choice.
-keywords: developing, api, Docker Engine API, API versions, SDK versions
-aliases:
-- /engine/reference/api/
-- /engine/reference/api/docker_remote_api/
-- /reference/api/
-- /reference/api/docker_remote_api/
-- /reference/api/docker_remote_api_v1.0/
-- /reference/api/docker_remote_api_v1.1/
-- /reference/api/docker_remote_api_v1.2/
-- /reference/api/docker_remote_api_v1.3/
-- /reference/api/docker_remote_api_v1.4/
-- /reference/api/docker_remote_api_v1.5/
-- /reference/api/docker_remote_api_v1.6/
-- /reference/api/docker_remote_api_v1.7/
-- /reference/api/docker_remote_api_v1.8/
-- /reference/api/docker_remote_api_v1.9/
-- /reference/api/docker_remote_api_v1.10/
-- /reference/api/docker_remote_api_v1.11/
-- /reference/api/docker_remote_api_v1.12/
-- /reference/api/docker_remote_api_v1.13/
-- /reference/api/docker_remote_api_v1.14/
-- /reference/api/docker_remote_api_v1.15/
-- /reference/api/docker_remote_api_v1.16/
-- /reference/api/docker_remote_api_v1.17/
----
-
-Docker provides an API for interacting with the Docker daemon (called the Docker
-Engine API), as well as SDKs for Go and Python. The SDKs allow you to efficiently build and
-scale Docker apps and solutions. If Go or Python don't work
-for you, you can use the Docker Engine API directly.
-
-For information about Docker Engine SDKs, see [Develop with Docker Engine SDKs](sdk/index.md).
-
-The Docker Engine API is a RESTful API accessed by an HTTP client such as `wget` or
-`curl`, or the HTTP library which is part of most modern programming languages.
-
-## View the API reference
-
-You can
-[view the reference for the latest version of the API](latest/index.html)
-or [choose a specific version](/engine/api/version-history/).
-
-## Versioned API and SDK
-
-The version of the Docker Engine API you should use depends upon the version of
-your Docker daemon and Docker client.
-
-A given version of the Docker Engine SDK supports a specific version of the
-Docker Engine API, as well as all earlier versions. If breaking changes occur,
-they are documented prominently.
-
-> [!NOTE]
->
-> The Docker daemon and client don't necessarily need to be the same version
-> at all times. However, keep the following in mind.
->
-> - If the daemon is newer than the client, the client doesn't know about new
->   features or deprecated API endpoints in the daemon.
->
-> - If the client is newer than the daemon, the client can request API
->   endpoints that the daemon doesn't know about.
-
-A new version of the API is released when new features are added. The Docker API
-is backward-compatible, so you don't need to update code that uses the API
-unless you need to take advantage of new features.
-
-To see the highest version of the API your Docker daemon and client support, use
-`docker version`:
-
-```console
-$ docker version
-Client: Docker Engine - Community
- Version:           27.1.2
- API version:       1.46
- Go version:        go1.21.13
- Git commit:        d01f264
- Built:             Mon Aug 12 11:51:13 2024
- OS/Arch:           linux/amd64
- Context:           default
-
-Server: Docker Engine - Community
- Engine:
-  Version:          27.1.2
-  API version:      1.46 (minimum version 1.24)
-  Go version:       go1.21.13
-  Git commit:       f9522e5
-  Built:            Mon Aug 12 11:51:13 2024
-  OS/Arch:          linux/amd64
-  Experimental:     false
-  ...
-```
-
-You can specify the API version to use in any of the following ways:
-
-- When using the SDK, use the latest version. At a minimum, use the version
-  that incorporates the API version with the features you need.
-- When using `curl` directly, specify the version as the first part of the URL.
-  For instance, if the endpoint is `/containers/` you can use
-  `/v1.46/containers/`.
-- To force the Docker CLI or the Docker Engine SDKs to use an older version
-  of the API than the version reported by `docker version`, set the
-  environment variable `DOCKER_API_VERSION` to the correct version. This works
-  on Linux, Windows, or macOS clients.
-
-  ```console
-  $ DOCKER_API_VERSION='1.44'
-  ```
-
-  While the environment variable is set, that version of the API is used, even
-  if the Docker daemon supports a newer version. This environment variable
-  disables API version negotiation, so you should only use it if you must
-  use a specific version of the API, or for debugging purposes.
-
-- The Docker Go SDK allows you to enable API version negotiation, automatically
-  selects an API version that's supported by both the client and the Docker Engine
-  that's in use.
-- For the SDKs, you can also specify the API version programmatically as a
-  parameter to the `client` object. See the
-  [Go constructor](https://pkg.go.dev/github.com/docker/docker/client#NewClientWithOpts)
-  or the
-  [Python SDK documentation for `client`](https://docker-py.readthedocs.io/en/stable/client.html).
-
-### API version matrix
-
-| Docker version | Maximum API version        | Change log                                               |
-|:---------------|:---------------------------|:---------------------------------------------------------|
-| 27.1           | [1.46](/engine/api/v1.46/) | [changes](/engine/api/version-history/#v146-api-changes) |
-| 27.0           | [1.46](/engine/api/v1.46/) | [changes](/engine/api/version-history/#v146-api-changes) |
-| 26.1           | [1.45](/engine/api/v1.45/) | [changes](/engine/api/version-history/#v145-api-changes) |
-| 26.0           | [1.45](/engine/api/v1.45/) | [changes](/engine/api/version-history/#v145-api-changes) |
-| 25.0           | [1.44](/engine/api/v1.44/) | [changes](/engine/api/version-history/#v144-api-changes) |
-| 24.0           | [1.43](/engine/api/v1.43/) | [changes](/engine/api/version-history/#v143-api-changes) |
-| 23.0           | [1.42](/engine/api/v1.42/) | [changes](/engine/api/version-history/#v142-api-changes) |
-| 20.10          | [1.41](/engine/api/v1.41/) | [changes](/engine/api/version-history/#v141-api-changes) |
-| 19.03          | [1.40](/engine/api/v1.40/) | [changes](/engine/api/version-history/#v140-api-changes) |
-| 18.09          | [1.39](/engine/api/v1.39/) | [changes](/engine/api/version-history/#v139-api-changes) |
-| 18.06          | [1.38](/engine/api/v1.38/) | [changes](/engine/api/version-history/#v138-api-changes) |
-| 18.05          | [1.37](/engine/api/v1.37/) | [changes](/engine/api/version-history/#v137-api-changes) |
-| 18.04          | [1.37](/engine/api/v1.37/) | [changes](/engine/api/version-history/#v137-api-changes) |
-| 18.03          | [1.37](/engine/api/v1.37/) | [changes](/engine/api/version-history/#v137-api-changes) |
-| 18.02          | [1.36](/engine/api/v1.36/) | [changes](/engine/api/version-history/#v136-api-changes) |
-| 17.12          | [1.35](/engine/api/v1.35/) | [changes](/engine/api/version-history/#v135-api-changes) |
-| 17.11          | [1.34](/engine/api/v1.34/) | [changes](/engine/api/version-history/#v134-api-changes) |
-| 17.10          | [1.33](/engine/api/v1.33/) | [changes](/engine/api/version-history/#v133-api-changes) |
-| 17.09          | [1.32](/engine/api/v1.32/) | [changes](/engine/api/version-history/#v132-api-changes) |
-| 17.07          | [1.31](/engine/api/v1.31/) | [changes](/engine/api/version-history/#v131-api-changes) |
-| 17.06          | [1.30](/engine/api/v1.30/) | [changes](/engine/api/version-history/#v130-api-changes) |
-| 17.05          | [1.29](/engine/api/v1.29/) | [changes](/engine/api/version-history/#v129-api-changes) |
-| 17.04          | [1.28](/engine/api/v1.28/) | [changes](/engine/api/version-history/#v128-api-changes) |
-| 17.03.1        | [1.27](/engine/api/v1.27/) | [changes](/engine/api/version-history/#v127-api-changes) |
-| 17.03          | [1.26](/engine/api/v1.27/) | [changes](/engine/api/version-history/#v126-api-changes) |
-| 1.13.1         | [1.26](/engine/api/v1.26/) | [changes](/engine/api/version-history/#v126-api-changes) |
-| 1.13           | [1.25](/engine/api/v1.26/) | [changes](/engine/api/version-history/#v125-api-changes) |
-| 1.12           | [1.24](/engine/api/v1.24/) | [changes](/engine/api/version-history/#v124-api-changes) |
-
-### Deprecated API versions
-
-API versions before v1.24 are [deprecated](/engine/deprecated/#deprecate-legacy-api-versions).
-You can find archived documentation for deprecated versions of the API in the
-code repository on GitHub:
-
-- [Documentation for API versions 1.23 and before](https://github.com/moby/moby/tree/v25.0.0/docs/api).
-- [Documentation for API versions 1.17 and before](https://github.com/moby/moby/tree/v1.9.1/docs/reference/api).
diff --git a/content/engine/api/latest/index.html b/content/engine/api/latest/index.html
deleted file mode 100644
index aa527f9c6967..000000000000
--- a/content/engine/api/latest/index.html
+++ /dev/null
@@ -1,6 +0,0 @@
----
----
-<html>
-<head><meta http-equiv="refresh" content="0;url=/engine/api/v{{< param latest_engine_api_version >}}/" /></head>
-<body><p>Redirecting to the latest version of the Docker Engine API reference.</body>
-</html>
diff --git a/content/engine/api/v1.25.md b/content/engine/api/v1.25.md
deleted file mode 100644
index 20fcf69eeda3..000000000000
--- a/content/engine/api/v1.25.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-layout: engine-api
-aliases:
-- /engine/reference/api/docker_remote_api_v1.25/
----
diff --git a/content/engine/api/v1.26.md b/content/engine/api/v1.26.md
deleted file mode 100644
index 870987488303..000000000000
--- a/content/engine/api/v1.26.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-layout: engine-api
-aliases:
-- /engine/reference/api/docker_remote_api_v1.26/
----
diff --git a/content/engine/api/v1.27.md b/content/engine/api/v1.27.md
deleted file mode 100644
index c6465489d6ba..000000000000
--- a/content/engine/api/v1.27.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-layout: engine-api
-aliases:
-- /engine/reference/api/docker_remote_api_v1.27/
----
diff --git a/content/engine/api/v1.28.md b/content/engine/api/v1.28.md
deleted file mode 100644
index 18a35b452615..000000000000
--- a/content/engine/api/v1.28.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-layout: engine-api
-aliases:
-- /engine/reference/api/docker_remote_api_v1.28/
----
diff --git a/content/engine/api/v1.29.md b/content/engine/api/v1.29.md
deleted file mode 100644
index 4b058956a86e..000000000000
--- a/content/engine/api/v1.29.md
+++ /dev/null
@@ -1,3 +0,0 @@
----
-layout: engine-api
----
diff --git a/content/engine/api/v1.30.md b/content/engine/api/v1.30.md
deleted file mode 100644
index 4b058956a86e..000000000000
--- a/content/engine/api/v1.30.md
+++ /dev/null
@@ -1,3 +0,0 @@
----
-layout: engine-api
----
diff --git a/content/engine/api/v1.31.md b/content/engine/api/v1.31.md
deleted file mode 100644
index 4b058956a86e..000000000000
--- a/content/engine/api/v1.31.md
+++ /dev/null
@@ -1,3 +0,0 @@
----
-layout: engine-api
----
diff --git a/content/engine/api/v1.32.md b/content/engine/api/v1.32.md
deleted file mode 100644
index 4b058956a86e..000000000000
--- a/content/engine/api/v1.32.md
+++ /dev/null
@@ -1,3 +0,0 @@
----
-layout: engine-api
----
diff --git a/content/engine/api/v1.33.md b/content/engine/api/v1.33.md
deleted file mode 100644
index 4b058956a86e..000000000000
--- a/content/engine/api/v1.33.md
+++ /dev/null
@@ -1,3 +0,0 @@
----
-layout: engine-api
----
diff --git a/content/engine/api/v1.34.md b/content/engine/api/v1.34.md
deleted file mode 100644
index 4b058956a86e..000000000000
--- a/content/engine/api/v1.34.md
+++ /dev/null
@@ -1,3 +0,0 @@
----
-layout: engine-api
----
diff --git a/content/engine/api/v1.35.md b/content/engine/api/v1.35.md
deleted file mode 100644
index 4b058956a86e..000000000000
--- a/content/engine/api/v1.35.md
+++ /dev/null
@@ -1,3 +0,0 @@
----
-layout: engine-api
----
diff --git a/content/engine/api/v1.36.md b/content/engine/api/v1.36.md
deleted file mode 100644
index 4b058956a86e..000000000000
--- a/content/engine/api/v1.36.md
+++ /dev/null
@@ -1,3 +0,0 @@
----
-layout: engine-api
----
diff --git a/content/engine/api/v1.37.md b/content/engine/api/v1.37.md
deleted file mode 100644
index 4b058956a86e..000000000000
--- a/content/engine/api/v1.37.md
+++ /dev/null
@@ -1,3 +0,0 @@
----
-layout: engine-api
----
diff --git a/content/engine/api/v1.38.md b/content/engine/api/v1.38.md
deleted file mode 100644
index 4b058956a86e..000000000000
--- a/content/engine/api/v1.38.md
+++ /dev/null
@@ -1,3 +0,0 @@
----
-layout: engine-api
----
diff --git a/content/engine/api/v1.39.md b/content/engine/api/v1.39.md
deleted file mode 100644
index 4b058956a86e..000000000000
--- a/content/engine/api/v1.39.md
+++ /dev/null
@@ -1,3 +0,0 @@
----
-layout: engine-api
----
diff --git a/content/engine/api/v1.40.md b/content/engine/api/v1.40.md
deleted file mode 100644
index 4b058956a86e..000000000000
--- a/content/engine/api/v1.40.md
+++ /dev/null
@@ -1,3 +0,0 @@
----
-layout: engine-api
----
diff --git a/content/engine/api/v1.41.md b/content/engine/api/v1.41.md
deleted file mode 100644
index 4b058956a86e..000000000000
--- a/content/engine/api/v1.41.md
+++ /dev/null
@@ -1,3 +0,0 @@
----
-layout: engine-api
----
diff --git a/content/engine/api/v1.42.md b/content/engine/api/v1.42.md
deleted file mode 100644
index 4b058956a86e..000000000000
--- a/content/engine/api/v1.42.md
+++ /dev/null
@@ -1,3 +0,0 @@
----
-layout: engine-api
----
diff --git a/content/engine/api/v1.43.md b/content/engine/api/v1.43.md
deleted file mode 100644
index 4b058956a86e..000000000000
--- a/content/engine/api/v1.43.md
+++ /dev/null
@@ -1,3 +0,0 @@
----
-layout: engine-api
----
diff --git a/content/engine/api/v1.44.md b/content/engine/api/v1.44.md
deleted file mode 100644
index 4b058956a86e..000000000000
--- a/content/engine/api/v1.44.md
+++ /dev/null
@@ -1,3 +0,0 @@
----
-layout: engine-api
----
diff --git a/content/engine/api/v1.45.md b/content/engine/api/v1.45.md
deleted file mode 100644
index 4b058956a86e..000000000000
--- a/content/engine/api/v1.45.md
+++ /dev/null
@@ -1,3 +0,0 @@
----
-layout: engine-api
----
diff --git a/content/engine/api/v1.46.md b/content/engine/api/v1.46.md
deleted file mode 100644
index 4b058956a86e..000000000000
--- a/content/engine/api/v1.46.md
+++ /dev/null
@@ -1,3 +0,0 @@
----
-layout: engine-api
----
diff --git a/content/engine/release-notes/23.0.md b/content/engine/release-notes/23.0.md
index 5570393a724a..4c339e84b22f 100644
--- a/content/engine/release-notes/23.0.md
+++ b/content/engine/release-notes/23.0.md
@@ -28,7 +28,7 @@ This page describes the latest changes, additions, known issues, and fixes for D
 For more information about:
 
 - Deprecated and removed features, see [Deprecated Engine Features](../deprecated.md).
-- Changes to the Engine API, see [Engine API version history](../api/version-history.md).
+- Changes to the Engine API, see [Engine API version history](/reference/api/engine/version-history.md).
 
 Starting with the 23.0.0 release, Docker Engine moves away from using CalVer versioning,
 and starts using the [SemVer versioning format](https://semver.org/).
diff --git a/content/engine/release-notes/24.0.md b/content/engine/release-notes/24.0.md
index 32a2b042876b..2dadaa07dda1 100644
--- a/content/engine/release-notes/24.0.md
+++ b/content/engine/release-notes/24.0.md
@@ -12,7 +12,7 @@ This page describes the latest changes, additions, known issues, and fixes for D
 For more information about:
 
 - Deprecated and removed features, see [Deprecated Engine Features](../deprecated.md).
-- Changes to the Engine API, see [Engine API version history](../api/version-history.md).
+- Changes to the Engine API, see [Engine API version history](/reference/api/engine/version-history.md).
 
 ## 24.0.9
 
diff --git a/content/engine/release-notes/25.0.md b/content/engine/release-notes/25.0.md
index 4dd0d7f80189..1d6a2b8bd16b 100644
--- a/content/engine/release-notes/25.0.md
+++ b/content/engine/release-notes/25.0.md
@@ -11,7 +11,7 @@ This page describes the latest changes, additions, known issues, and fixes for D
 For more information about:
 
 - Deprecated and removed features, see [Deprecated Engine Features](../deprecated.md).
-- Changes to the Engine API, see [Engine API version history](../api/version-history.md).
+- Changes to the Engine API, see [Engine API version history](/reference/api/engine/version-history.md).
 
 ## 25.0.5
 
diff --git a/content/engine/release-notes/26.0.md b/content/engine/release-notes/26.0.md
index 54c9996fa2ff..94ef33a98308 100644
--- a/content/engine/release-notes/26.0.md
+++ b/content/engine/release-notes/26.0.md
@@ -11,7 +11,7 @@ This page describes the latest changes, additions, known issues, and fixes for D
 For more information about:
 
 - Deprecated and removed features, see [Deprecated Engine Features](../deprecated.md).
-- Changes to the Engine API, see [Engine API version history](../api/version-history.md).
+- Changes to the Engine API, see [Engine API version history](/reference/api/engine/version-history.md).
 
 ## 26.0.2
 
diff --git a/content/engine/release-notes/26.1.md b/content/engine/release-notes/26.1.md
index 2ce853b515ea..c7f45962b62b 100644
--- a/content/engine/release-notes/26.1.md
+++ b/content/engine/release-notes/26.1.md
@@ -11,7 +11,7 @@ This page describes the latest changes, additions, known issues, and fixes for D
 For more information about:
 
 - Deprecated and removed features, see [Deprecated Engine Features](../deprecated.md).
-- Changes to the Engine API, see [Engine API version history](../api/version-history.md).
+- Changes to the Engine API, see [Engine API version history](/reference/api/engine/version-history.md).
 
 ## 26.1.4
 
diff --git a/content/engine/release-notes/27.0.md b/content/engine/release-notes/27.0.md
index 39cabba56916..5b648f56451a 100644
--- a/content/engine/release-notes/27.0.md
+++ b/content/engine/release-notes/27.0.md
@@ -11,7 +11,7 @@ This page describes the latest changes, additions, known issues, and fixes for D
 For more information about:
 
 - Deprecated and removed features, see [Deprecated Engine Features](../deprecated.md).
-- Changes to the Engine API, see [Engine API version history](../api/version-history.md).
+- Changes to the Engine API, see [Engine API version history](/reference/api/engine/version-history.md).
 
 ## 27.0.3
 
diff --git a/content/engine/release-notes/27.1.md b/content/engine/release-notes/27.1.md
index cfd3896928cc..6934a88c64d8 100644
--- a/content/engine/release-notes/27.1.md
+++ b/content/engine/release-notes/27.1.md
@@ -18,7 +18,7 @@ This page describes the latest changes, additions, known issues, and fixes for D
 For more information about:
 
 - Deprecated and removed features, see [Deprecated Engine Features](../deprecated.md).
-- Changes to the Engine API, see [Engine API version history](../api/version-history.md).
+- Changes to the Engine API, see [Engine API version history](/reference/api/engine/version-history.md).
 
 ## 27.1.2
 
diff --git a/content/engine/swarm/admin_guide.md b/content/engine/swarm/admin_guide.md
index e28b5de003dd..cec2e725c543 100644
--- a/content/engine/swarm/admin_guide.md
+++ b/content/engine/swarm/admin_guide.md
@@ -154,7 +154,7 @@ worker nodes that do not meet these requirements cannot run these tasks.
 
 You can monitor the health of manager nodes by querying the docker `nodes` API
 in JSON format through the `/nodes` HTTP endpoint. Refer to the
-[nodes API documentation](/engine/api/v1.25/#tag/Node)
+[nodes API documentation](/reference/api/engine/v1.25/#tag/Node)
 for more information.
 
 From the command line, run `docker node inspect <id-node>` to query the nodes.
diff --git a/content/engine/swarm/how-swarm-mode-works/nodes.md b/content/engine/swarm/how-swarm-mode-works/nodes.md
index 294b7b43f939..c7a90868f03f 100644
--- a/content/engine/swarm/how-swarm-mode-works/nodes.md
+++ b/content/engine/swarm/how-swarm-mode-works/nodes.md
@@ -26,7 +26,7 @@ Manager nodes handle cluster management tasks:
 
 * Maintaining cluster state
 * Scheduling services
-* Serving Swarm mode [HTTP API endpoints](../../api/index.md)
+* Serving Swarm mode [HTTP API endpoints](/reference/api/engine/_index.md)
 
 Using a [Raft](https://raft.github.io/raft.pdf) implementation, the managers
 maintain a consistent internal state of the entire swarm and all the services
diff --git a/content/engine/swarm/manage-nodes.md b/content/engine/swarm/manage-nodes.md
index f8ef32518c54..8b819158beb1 100644
--- a/content/engine/swarm/manage-nodes.md
+++ b/content/engine/swarm/manage-nodes.md
@@ -203,7 +203,7 @@ a `PluginSpec` instead of a `ContainerSpec`.
 
 The [`PluginSpec`](/engine/extend/plugin_api/#json-specification)
 is defined by the plugin developer. To add the plugin to all Docker nodes, use
-the [`service/create`](/engine/api/v1.31/#operation/ServiceCreate) API, passing
+the [`service/create`](/reference/api/engine/v1.31/#operation/ServiceCreate) API, passing
 the `PluginSpec` JSON defined in the `TaskTemplate`.
 
 ## Leave the swarm
diff --git a/content/reference/_index.md b/content/reference/_index.md
index d03daffad753..27dc69549ab3 100644
--- a/content/reference/_index.md
+++ b/content/reference/_index.md
@@ -29,7 +29,7 @@ grid_apis:
 - title: Engine API
   description: The main API for Docker, provides programmatic access to a daemon.
   icon: api
-  link: /engine/api/
+  link: /reference/api/engine/
 - title: Registry API
   description: Facilitates distribution of images to the engine.
   icon: storage
diff --git a/content/reference/api/engine/_index.md b/content/reference/api/engine/_index.md
new file mode 100644
index 000000000000..812ad084f0cd
--- /dev/null
+++ b/content/reference/api/engine/_index.md
@@ -0,0 +1,166 @@
+---
+title: Develop with Docker Engine API
+description: Learn how you can use Docker Engine API and SDKs in the language of your choice.
+keywords: developing, api, Docker Engine API, API versions, SDK versions
+aliases:
+  - /reference/api/docker_remote_api/
+  - /reference/api/docker_remote_api_v1.0/
+  - /reference/api/docker_remote_api_v1.1/
+  - /reference/api/docker_remote_api_v1.2/
+  - /reference/api/docker_remote_api_v1.3/
+  - /reference/api/docker_remote_api_v1.4/
+  - /reference/api/docker_remote_api_v1.5/
+  - /reference/api/docker_remote_api_v1.6/
+  - /reference/api/docker_remote_api_v1.7/
+  - /reference/api/docker_remote_api_v1.8/
+  - /reference/api/docker_remote_api_v1.9/
+  - /reference/api/docker_remote_api_v1.10/
+  - /reference/api/docker_remote_api_v1.11/
+  - /reference/api/docker_remote_api_v1.12/
+  - /reference/api/docker_remote_api_v1.13/
+  - /reference/api/docker_remote_api_v1.14/
+  - /reference/api/docker_remote_api_v1.15/
+  - /reference/api/docker_remote_api_v1.16/
+  - /reference/api/docker_remote_api_v1.17/
+  - /engine/reference/api/
+  - /engine/reference/api/docker_remote_api/
+  - /engine/api/
+---
+
+Docker provides an API for interacting with the Docker daemon (called the Docker
+Engine API), as well as SDKs for Go and Python. The SDKs allow you to efficiently build and
+scale Docker apps and solutions. If Go or Python don't work
+for you, you can use the Docker Engine API directly.
+
+For information about Docker Engine SDKs, see [Develop with Docker Engine SDKs](sdk/index.md).
+
+The Docker Engine API is a RESTful API accessed by an HTTP client such as `wget` or
+`curl`, or the HTTP library which is part of most modern programming languages.
+
+## View the API reference
+
+You can
+[view the reference for the latest version of the API](latest/index.html)
+or [choose a specific version](/reference/api/engine/version-history/).
+
+## Versioned API and SDK
+
+The version of the Docker Engine API you should use depends upon the version of
+your Docker daemon and Docker client.
+
+A given version of the Docker Engine SDK supports a specific version of the
+Docker Engine API, as well as all earlier versions. If breaking changes occur,
+they are documented prominently.
+
+> [!NOTE]
+>
+> The Docker daemon and client don't necessarily need to be the same version
+> at all times. However, keep the following in mind.
+>
+> - If the daemon is newer than the client, the client doesn't know about new
+>   features or deprecated API endpoints in the daemon.
+>
+> - If the client is newer than the daemon, the client can request API
+>   endpoints that the daemon doesn't know about.
+
+A new version of the API is released when new features are added. The Docker API
+is backward-compatible, so you don't need to update code that uses the API
+unless you need to take advantage of new features.
+
+To see the highest version of the API your Docker daemon and client support, use
+`docker version`:
+
+```console
+$ docker version
+Client: Docker Engine - Community
+ Version:           27.1.2
+ API version:       1.46
+ Go version:        go1.21.13
+ Git commit:        d01f264
+ Built:             Mon Aug 12 11:51:13 2024
+ OS/Arch:           linux/amd64
+ Context:           default
+
+Server: Docker Engine - Community
+ Engine:
+  Version:          27.1.2
+  API version:      1.46 (minimum version 1.24)
+  Go version:       go1.21.13
+  Git commit:       f9522e5
+  Built:            Mon Aug 12 11:51:13 2024
+  OS/Arch:          linux/amd64
+  Experimental:     false
+  ...
+```
+
+You can specify the API version to use in any of the following ways:
+
+- When using the SDK, use the latest version. At a minimum, use the version
+  that incorporates the API version with the features you need.
+- When using `curl` directly, specify the version as the first part of the URL.
+  For instance, if the endpoint is `/containers/` you can use
+  `/v1.46/containers/`.
+- To force the Docker CLI or the Docker Engine SDKs to use an older version
+  of the API than the version reported by `docker version`, set the
+  environment variable `DOCKER_API_VERSION` to the correct version. This works
+  on Linux, Windows, or macOS clients.
+
+  ```console
+  $ DOCKER_API_VERSION='1.44'
+  ```
+
+  While the environment variable is set, that version of the API is used, even
+  if the Docker daemon supports a newer version. This environment variable
+  disables API version negotiation, so you should only use it if you must
+  use a specific version of the API, or for debugging purposes.
+
+- The Docker Go SDK allows you to enable API version negotiation, automatically
+  selects an API version that's supported by both the client and the Docker Engine
+  that's in use.
+- For the SDKs, you can also specify the API version programmatically as a
+  parameter to the `client` object. See the
+  [Go constructor](https://pkg.go.dev/github.com/docker/docker/client#NewClientWithOpts)
+  or the
+  [Python SDK documentation for `client`](https://docker-py.readthedocs.io/en/stable/client.html).
+
+### API version matrix
+
+| Docker version | Maximum API version        | Change log                                                                   |
+|:---------------|:---------------------------|:-----------------------------------------------------------------------------|
+| 27.1           | [1.46](/reference/api/engine/v1.46/) | [changes](/reference/api/engine/version-history/#v146-api-changes) |
+| 27.0           | [1.46](/reference/api/engine/v1.46/) | [changes](/reference/api/engine/version-history/#v146-api-changes) |
+| 26.1           | [1.45](/reference/api/engine/v1.45/) | [changes](/reference/api/engine/version-history/#v145-api-changes) |
+| 26.0           | [1.45](/reference/api/engine/v1.45/) | [changes](/reference/api/engine/version-history/#v145-api-changes) |
+| 25.0           | [1.44](/reference/api/engine/v1.44/) | [changes](/reference/api/engine/version-history/#v144-api-changes) |
+| 24.0           | [1.43](/reference/api/engine/v1.43/) | [changes](/reference/api/engine/version-history/#v143-api-changes) |
+| 23.0           | [1.42](/reference/api/engine/v1.42/) | [changes](/reference/api/engine/version-history/#v142-api-changes) |
+| 20.10          | [1.41](/reference/api/engine/v1.41/) | [changes](/reference/api/engine/version-history/#v141-api-changes) |
+| 19.03          | [1.40](/reference/api/engine/v1.40/) | [changes](/reference/api/engine/version-history/#v140-api-changes) |
+| 18.09          | [1.39](/reference/api/engine/v1.39/) | [changes](/reference/api/engine/version-history/#v139-api-changes) |
+| 18.06          | [1.38](/reference/api/engine/v1.38/) | [changes](/reference/api/engine/version-history/#v138-api-changes) |
+| 18.05          | [1.37](/reference/api/engine/v1.37/) | [changes](/reference/api/engine/version-history/#v137-api-changes) |
+| 18.04          | [1.37](/reference/api/engine/v1.37/) | [changes](/reference/api/engine/version-history/#v137-api-changes) |
+| 18.03          | [1.37](/reference/api/engine/v1.37/) | [changes](/reference/api/engine/version-history/#v137-api-changes) |
+| 18.02          | [1.36](/reference/api/engine/v1.36/) | [changes](/reference/api/engine/version-history/#v136-api-changes) |
+| 17.12          | [1.35](/reference/api/engine/v1.35/) | [changes](/reference/api/engine/version-history/#v135-api-changes) |
+| 17.11          | [1.34](/reference/api/engine/v1.34/) | [changes](/reference/api/engine/version-history/#v134-api-changes) |
+| 17.10          | [1.33](/reference/api/engine/v1.33/) | [changes](/reference/api/engine/version-history/#v133-api-changes) |
+| 17.09          | [1.32](/reference/api/engine/v1.32/) | [changes](/reference/api/engine/version-history/#v132-api-changes) |
+| 17.07          | [1.31](/reference/api/engine/v1.31/) | [changes](/reference/api/engine/version-history/#v131-api-changes) |
+| 17.06          | [1.30](/reference/api/engine/v1.30/) | [changes](/reference/api/engine/version-history/#v130-api-changes) |
+| 17.05          | [1.29](/reference/api/engine/v1.29/) | [changes](/reference/api/engine/version-history/#v129-api-changes) |
+| 17.04          | [1.28](/reference/api/engine/v1.28/) | [changes](/reference/api/engine/version-history/#v128-api-changes) |
+| 17.03.1        | [1.27](/reference/api/engine/v1.27/) | [changes](/reference/api/engine/version-history/#v127-api-changes) |
+| 17.03          | [1.26](/reference/api/engine/v1.27/) | [changes](/reference/api/engine/version-history/#v126-api-changes) |
+| 1.13.1         | [1.26](/reference/api/engine/v1.26/) | [changes](/reference/api/engine/version-history/#v126-api-changes) |
+| 1.13           | [1.25](/reference/api/engine/v1.26/) | [changes](/reference/api/engine/version-history/#v125-api-changes) |
+| 1.12           | [1.24](/reference/api/engine/v1.24/) | [changes](/reference/api/engine/version-history/#v124-api-changes) |
+
+### Deprecated API versions
+
+API versions before v1.24 are [deprecated](/engine/deprecated/#deprecate-legacy-api-versions).
+You can find archived documentation for deprecated versions of the API in the
+code repository on GitHub:
+
+- [Documentation for API versions 1.23 and before](https://github.com/moby/moby/tree/v25.0.0/docs/api).
+- [Documentation for API versions 1.17 and before](https://github.com/moby/moby/tree/v1.9.1/docs/reference/api).
diff --git a/content/reference/api/engine/latest/index.html b/content/reference/api/engine/latest/index.html
new file mode 100644
index 000000000000..497ebfefc5a3
--- /dev/null
+++ b/content/reference/api/engine/latest/index.html
@@ -0,0 +1,6 @@
+---
+---
+<html>
+<head><meta http-equiv="refresh" content="0;url=/reference/api/engine/v{{< param latest_engine_api_version >}}/" /></head>
+<body><p>Redirecting to the latest version of the Docker Engine API reference.</body>
+</html>
diff --git a/content/engine/api/sdk/_index.md b/content/reference/api/engine/sdk/_index.md
similarity index 95%
rename from content/engine/api/sdk/_index.md
rename to content/reference/api/engine/sdk/_index.md
index 9828c25378d6..bfa83bc0a278 100644
--- a/content/engine/api/sdk/_index.md
+++ b/content/reference/api/engine/sdk/_index.md
@@ -3,8 +3,9 @@ title: Develop with Docker Engine SDKs
 description: Learn how to use Docker Engine SDKs to automate Docker tasks in your language of choice
 keywords: developing, sdk, Docker Engine SDKs, install SDKs, SDK versions
 aliases:
-- /engine/api/sdks/
-- /develop/sdk/
+  - /develop/sdk/
+  - /engine/api/sdks/
+  - /engine/api/sdk/
 ---
 
 Docker provides an API for interacting with the Docker daemon (called the Docker
@@ -46,13 +47,13 @@ For more information, see [Docker Engine Python SDK reference](https://docker-py
 ## View the API reference
 
 You can
-[view the reference for the latest version of the API](/engine/api/latest/)
-or [choose a specific version](/engine/api/version-history/).
+[view the reference for the latest version of the API](/reference/api/engine/latest/)
+or [choose a specific version](/reference/api/engine/version-history/).
 
 ## Versioned API and SDK
 
 The version of the Docker Engine API you should use depends on the version of
-your Docker daemon and Docker client. See the [versioned API and SDK](/engine/api/#versioned-api-and-sdk)
+your Docker daemon and Docker client. See the [versioned API and SDK](/reference/api/engine/#versioned-api-and-sdk)
 section in the API documentation for details.
 
 ## SDK and API quickstart
@@ -60,7 +61,7 @@ section in the API documentation for details.
 Use the following guidelines to choose the SDK or API version to use in your
 code:
 
-- If you're starting a new project, use the [latest version](/engine/api/latest/),
+- If you're starting a new project, use the [latest version](/reference/api/engine/latest/),
   but use API version negotiation or specify the version you are using. This
   helps prevent surprises.
 - If you need a new feature, update your code to use at least the minimum version
diff --git a/content/engine/api/sdk/examples.md b/content/reference/api/engine/sdk/examples.md
similarity index 98%
rename from content/engine/api/sdk/examples.md
rename to content/reference/api/engine/sdk/examples.md
index 76f802c9125c..e62782396ee3 100644
--- a/content/engine/api/sdk/examples.md
+++ b/content/reference/api/engine/sdk/examples.md
@@ -4,11 +4,12 @@ description: Examples on how to perform a given Docker operation using the Go an
   Python SDKs and the HTTP API using curl.
 keywords: developing, api, sdk, developers, rest, curl, python, go
 aliases:
-- /engine/api/getting-started/
-- /engine/api/client-libraries/
-- /engine/reference/api/remote_api_client_libraries/
-- /reference/api/remote_api_client_libraries/
-- /develop/sdk/examples/
+  - /engine/api/getting-started/
+  - /engine/api/client-libraries/
+  - /engine/reference/api/remote_api_client_libraries/
+  - /reference/api/remote_api_client_libraries/
+  - /develop/sdk/examples/
+  - /engine/api/sdk/examples/
 ---
 
 After you
@@ -607,7 +608,7 @@ func main() {
 {{< tab name="Python" >}}
 
 The Python SDK retrieves authentication information from the [credentials
-store](/reference/cli/docker/login/#credentials-store) file and
+store](/reference/cli/docker/login/#credential-stores) file and
 integrates with [credential
 helpers](https://github.com/docker/docker-credential-helpers). It's possible to override these credentials, but that's out of
 scope for this example guide. After using `docker login`, the Python SDK
diff --git a/content/reference/api/engine/v1.25.md b/content/reference/api/engine/v1.25.md
new file mode 100644
index 000000000000..672286468a87
--- /dev/null
+++ b/content/reference/api/engine/v1.25.md
@@ -0,0 +1,5 @@
+---
+layout: engine-api
+aliases:
+- /engine/api/v1.25/
+---
diff --git a/content/reference/api/engine/v1.26.md b/content/reference/api/engine/v1.26.md
new file mode 100644
index 000000000000..393b97341c6c
--- /dev/null
+++ b/content/reference/api/engine/v1.26.md
@@ -0,0 +1,5 @@
+---
+layout: engine-api
+aliases:
+- /engine/api/v1.26/
+---
diff --git a/content/reference/api/engine/v1.27.md b/content/reference/api/engine/v1.27.md
new file mode 100644
index 000000000000..1c5196888c7c
--- /dev/null
+++ b/content/reference/api/engine/v1.27.md
@@ -0,0 +1,5 @@
+---
+layout: engine-api
+aliases:
+- /engine/api/v1.27/
+---
diff --git a/content/reference/api/engine/v1.28.md b/content/reference/api/engine/v1.28.md
new file mode 100644
index 000000000000..808c3e007b17
--- /dev/null
+++ b/content/reference/api/engine/v1.28.md
@@ -0,0 +1,5 @@
+---
+layout: engine-api
+aliases:
+- /engine/api/v1.28/
+---
diff --git a/content/reference/api/engine/v1.29.md b/content/reference/api/engine/v1.29.md
new file mode 100644
index 000000000000..c1ba7de56ece
--- /dev/null
+++ b/content/reference/api/engine/v1.29.md
@@ -0,0 +1,5 @@
+---
+layout: engine-api
+aliases:
+  - /engine/api/v1.29/
+---
diff --git a/content/reference/api/engine/v1.30.md b/content/reference/api/engine/v1.30.md
new file mode 100644
index 000000000000..8a7ed3f018ab
--- /dev/null
+++ b/content/reference/api/engine/v1.30.md
@@ -0,0 +1,5 @@
+---
+layout: engine-api
+aliases:
+  - /engine/api/v1.30/
+---
diff --git a/content/reference/api/engine/v1.31.md b/content/reference/api/engine/v1.31.md
new file mode 100644
index 000000000000..54dd7e1cf07b
--- /dev/null
+++ b/content/reference/api/engine/v1.31.md
@@ -0,0 +1,5 @@
+---
+layout: engine-api
+aliases:
+  - /engine/api/v1.31/
+---
diff --git a/content/reference/api/engine/v1.32.md b/content/reference/api/engine/v1.32.md
new file mode 100644
index 000000000000..6bde83d91437
--- /dev/null
+++ b/content/reference/api/engine/v1.32.md
@@ -0,0 +1,5 @@
+---
+layout: engine-api
+aliases:
+  - /engine/api/v1.32/
+---
diff --git a/content/reference/api/engine/v1.33.md b/content/reference/api/engine/v1.33.md
new file mode 100644
index 000000000000..a112ca94c597
--- /dev/null
+++ b/content/reference/api/engine/v1.33.md
@@ -0,0 +1,5 @@
+---
+layout: engine-api
+aliases:
+  - /engine/api/v1.33/
+---
diff --git a/content/reference/api/engine/v1.34.md b/content/reference/api/engine/v1.34.md
new file mode 100644
index 000000000000..80fa86dee45e
--- /dev/null
+++ b/content/reference/api/engine/v1.34.md
@@ -0,0 +1,5 @@
+---
+layout: engine-api
+aliases:
+  - /engine/api/v1.34/
+---
diff --git a/content/reference/api/engine/v1.35.md b/content/reference/api/engine/v1.35.md
new file mode 100644
index 000000000000..3cb20d1a23e5
--- /dev/null
+++ b/content/reference/api/engine/v1.35.md
@@ -0,0 +1,5 @@
+---
+layout: engine-api
+aliases:
+  - /engine/api/v1.35/
+---
diff --git a/content/reference/api/engine/v1.36.md b/content/reference/api/engine/v1.36.md
new file mode 100644
index 000000000000..f5f0aa074acc
--- /dev/null
+++ b/content/reference/api/engine/v1.36.md
@@ -0,0 +1,5 @@
+---
+layout: engine-api
+aliases:
+  - /engine/api/v1.36/
+---
diff --git a/content/reference/api/engine/v1.37.md b/content/reference/api/engine/v1.37.md
new file mode 100644
index 000000000000..5f886a6989c5
--- /dev/null
+++ b/content/reference/api/engine/v1.37.md
@@ -0,0 +1,5 @@
+---
+layout: engine-api
+aliases:
+  - /engine/api/v1.37/
+---
diff --git a/content/reference/api/engine/v1.38.md b/content/reference/api/engine/v1.38.md
new file mode 100644
index 000000000000..d63b33271063
--- /dev/null
+++ b/content/reference/api/engine/v1.38.md
@@ -0,0 +1,5 @@
+---
+layout: engine-api
+aliases:
+  - /engine/api/v1.38/
+---
diff --git a/content/reference/api/engine/v1.39.md b/content/reference/api/engine/v1.39.md
new file mode 100644
index 000000000000..92100eeaeed3
--- /dev/null
+++ b/content/reference/api/engine/v1.39.md
@@ -0,0 +1,5 @@
+---
+layout: engine-api
+aliases:
+  - /engine/api/v1.39/
+---
diff --git a/content/reference/api/engine/v1.40.md b/content/reference/api/engine/v1.40.md
new file mode 100644
index 000000000000..b29d668dc2ce
--- /dev/null
+++ b/content/reference/api/engine/v1.40.md
@@ -0,0 +1,5 @@
+---
+layout: engine-api
+aliases:
+  - /engine/api/v1.40/
+---
diff --git a/content/reference/api/engine/v1.41.md b/content/reference/api/engine/v1.41.md
new file mode 100644
index 000000000000..a08e1a4263cb
--- /dev/null
+++ b/content/reference/api/engine/v1.41.md
@@ -0,0 +1,5 @@
+---
+layout: engine-api
+aliases:
+  - /engine/api/v1.41/
+---
diff --git a/content/reference/api/engine/v1.42.md b/content/reference/api/engine/v1.42.md
new file mode 100644
index 000000000000..81a12d0a72af
--- /dev/null
+++ b/content/reference/api/engine/v1.42.md
@@ -0,0 +1,5 @@
+---
+layout: engine-api
+aliases:
+  - /engine/api/v1.42/
+---
diff --git a/content/reference/api/engine/v1.43.md b/content/reference/api/engine/v1.43.md
new file mode 100644
index 000000000000..d03bb2f04072
--- /dev/null
+++ b/content/reference/api/engine/v1.43.md
@@ -0,0 +1,5 @@
+---
+layout: engine-api
+aliases:
+  - /engine/api/v1.43/
+---
diff --git a/content/reference/api/engine/v1.44.md b/content/reference/api/engine/v1.44.md
new file mode 100644
index 000000000000..67a7e8398d16
--- /dev/null
+++ b/content/reference/api/engine/v1.44.md
@@ -0,0 +1,5 @@
+---
+layout: engine-api
+aliases:
+  - /engine/api/v1.44/
+---
diff --git a/content/reference/api/engine/v1.45.md b/content/reference/api/engine/v1.45.md
new file mode 100644
index 000000000000..10581b8dfb80
--- /dev/null
+++ b/content/reference/api/engine/v1.45.md
@@ -0,0 +1,5 @@
+---
+layout: engine-api
+aliases:
+  - /engine/api/v1.45/
+---
diff --git a/content/reference/api/engine/v1.46.md b/content/reference/api/engine/v1.46.md
new file mode 100644
index 000000000000..53cf04be7063
--- /dev/null
+++ b/content/reference/api/engine/v1.46.md
@@ -0,0 +1,5 @@
+---
+layout: engine-api
+aliases:
+  - /engine/api/v1.46/
+---
diff --git a/data/engine-cli/docker_version.yaml b/data/engine-cli/docker_version.yaml
index cb555d56f25b..88e35e84ee83 100644
--- a/data/engine-cli/docker_version.yaml
+++ b/data/engine-cli/docker_version.yaml
@@ -105,7 +105,7 @@ long: |-
     version that is supported by both the Docker CLI and the Docker Engine.
 
     For example, if the CLI is connecting with Docker Engine version 19.03, it downgrades
-    to API version 1.40 (refer to the [API version matrix](/engine/api/#api-version-matrix)
+    to API version 1.40 (refer to the [API version matrix](/reference/api/engine/#api-version-matrix)
     to learn about the supported API versions for Docker Engine):
 
     ```console
diff --git a/data/redirects.yml b/data/redirects.yml
index a78306b9a765..5fa1f5be2f16 100644
--- a/data/redirects.yml
+++ b/data/redirects.yml
@@ -12,7 +12,7 @@
   - /go/access-tokens/
 "/desktop/mac/apple-silicon/":
   - /go/apple-silicon/
-"/engine/api/#deprecated-api-versions":
+"/reference/api/engine/#deprecated-api-versions":
   - /engine/api/v1.18/
   - /engine/api/v1.19/
   - /engine/api/v1.20/
diff --git a/data/toc.yaml b/data/toc.yaml
index 0489d6f29ab3..765e69c8cc9d 100644
--- a/data/toc.yaml
+++ b/data/toc.yaml
@@ -919,63 +919,63 @@ Reference:
   section:
   - sectiontitle: Docker Engine API
     section:
-    - path: /engine/api/
+    - path: /reference/api/engine/
       title: Overview
-    - path: /engine/api/sdk/
+    - path: /reference/api/engine/sdk/
       title: SDKs
-    - path: /engine/api/sdk/examples/
+    - path: /reference/api/engine/sdk/examples/
       title: SDK examples
-    - path: /engine/api/latest/
+    - path: /reference/api/engine/latest/
       title: v{{< param latest_engine_api_version >}} reference (latest)
     - sectiontitle: API reference by version
       section:
-      - path: /engine/api/version-history/
+      - path: /reference/api/engine/version-history/
         title: Version history overview
-      - path: /engine/api/v1.46/
+      - path: /reference/api/engine/v1.46/
         title: v1.46 reference
-      - path: /engine/api/v1.45/
+      - path: /reference/api/engine/v1.45/
         title: v1.45 reference
-      - path: /engine/api/v1.44/
+      - path: /reference/api/engine/v1.44/
         title: v1.44 reference
-      - path: /engine/api/v1.43/
+      - path: /reference/api/engine/v1.43/
         title: v1.43 reference
-      - path: /engine/api/v1.42/
+      - path: /reference/api/engine/v1.42/
         title: v1.42 reference
-      - path: /engine/api/v1.41/
+      - path: /reference/api/engine/v1.41/
         title: v1.41 reference
-      - path: /engine/api/v1.40/
+      - path: /reference/api/engine/v1.40/
         title: v1.40 reference
-      - path: /engine/api/v1.39/
+      - path: /reference/api/engine/v1.39/
         title: v1.39 reference
-      - path: /engine/api/v1.38/
+      - path: /reference/api/engine/v1.38/
         title: v1.38 reference
-      - path: /engine/api/v1.37/
+      - path: /reference/api/engine/v1.37/
         title: v1.37 reference
-      - path: /engine/api/v1.36/
+      - path: /reference/api/engine/v1.36/
         title: v1.36 reference
-      - path: /engine/api/v1.35/
+      - path: /reference/api/engine/v1.35/
         title: v1.35 reference
-      - path: /engine/api/v1.34/
+      - path: /reference/api/engine/v1.34/
         title: v1.34 reference
-      - path: /engine/api/v1.33/
+      - path: /reference/api/engine/v1.33/
         title: v1.33 reference
-      - path: /engine/api/v1.32/
+      - path: /reference/api/engine/v1.32/
         title: v1.32 Reference
-      - path: /engine/api/v1.31/
+      - path: /reference/api/engine/v1.31/
         title: v1.31 Reference
-      - path: /engine/api/v1.30/
+      - path: /reference/api/engine/v1.30/
         title: v1.30 Reference
-      - path: /engine/api/v1.29/
+      - path: /reference/api/engine/v1.29/
         title: v1.29 Reference
-      - path: /engine/api/v1.28/
+      - path: /reference/api/engine/v1.28/
         title: v1.28 reference
-      - path: /engine/api/v1.27/
+      - path: /reference/api/engine/v1.27/
         title: v1.27 reference
-      - path: /engine/api/v1.26/
+      - path: /reference/api/engine/v1.26/
         title: v1.26 reference
-      - path: /engine/api/v1.25/
+      - path: /reference/api/engine/v1.25/
         title: v1.25 reference
-      - path: /engine/api/v1.24/
+      - path: /reference/api/engine/v1.24/
         title: v1.24 reference
   - sectiontitle: Docker Hub API
     section:
diff --git a/hugo.yaml b/hugo.yaml
index 60d5cbb9027b..7ebc61822ea3 100644
--- a/hugo.yaml
+++ b/hugo.yaml
@@ -250,10 +250,10 @@ module:
     - path: github.com/moby/moby
       mounts:
         - source: docs/api
-          target: content/engine/api
+          target: content/reference/api/engine
           includeFiles: "*.md"
         - source: docs/api
-          target: static/reference/engine
+          target: static/reference/api/engine
           includeFiles: "*.yaml"
 
     - path: github.com/moby/buildkit
diff --git a/layouts/_default/engine-api-baseof.html b/layouts/_default/engine-api-baseof.html
index c9888202e399..90aa674fd303 100644
--- a/layouts/_default/engine-api-baseof.html
+++ b/layouts/_default/engine-api-baseof.html
@@ -11,7 +11,7 @@
     <!-- favicon -->
     {{ partialCached "favicon.html" "favicon" }}
     <!-- make the latest API version the canonical page as that's what we want users to be using mostly -->
-    <link rel="canonical" href="{{ site.BaseURL }}/engine/api/v{{ site.Params.latest_engine_api_version }}/" />
+    <link rel="canonical" href="{{ site.BaseURL }}/reference/api/engine/v{{ site.Params.latest_engine_api_version }}/" />
     <style>
         body {
             margin: 0;
@@ -26,7 +26,7 @@
 </head>
 
 <body>
-    <redoc spec-url="/reference/engine/{{ .File.BaseFileName }}.yaml" hide-hostname="true" suppress-warnings="true"
+    <redoc spec-url="/reference/api/engine/{{ .File.BaseFileName }}.yaml" hide-hostname="true" suppress-warnings="true"
         lazy-rendering></redoc>
     <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>
 </body>