diff --git a/api-ref/source/os-baremetal-nodes.inc b/api-ref/source/os-baremetal-nodes.inc
index 42d88f197b08..2c0e79edbda4 100644
--- a/api-ref/source/os-baremetal-nodes.inc
+++ b/api-ref/source/os-baremetal-nodes.inc
@@ -1,25 +1,27 @@
 .. -*- rst -*-
-.. needs:parameter_verification
-.. needs:example_verification
-.. needs:body_verification
 
 =======================================
  Bare metal nodes (os-baremetal-nodes)
 =======================================
 
-Bare metal nodes.
+.. warning::
 
+   These APIs are proxy calls to the Ironic service. They exist for
+   legacy compatibility, but no new applications should use them.
+
+Bare metal nodes.
 
 List Bare Metal Nodes
 =====================
 
-.. rest_method:: GET /v2.1/{tenant_id}/servers/{server_id}/os-baremetal-nodes
+.. rest_method:: GET /v2.1/{tenant_id}/os-baremetal-nodes
 
-Lists the bare metal nodes that are associated with a server.
+Lists the bare metal nodes known by the compute environment.
 
 Normal response codes: 202
 
-Error response codes: unauthorized(401), forbidden(403), itemNotFound(404), notImplemented(501)
+Error response codes: unauthorized(401), forbidden(403),
+notImplemented(501)
 
 Request
 -------
@@ -27,12 +29,22 @@ Request
 .. rest_parameters:: parameters.yaml
 
   - tenant_id: tenant_id
-  - server_id: server_id
 
 Response
 --------
 
-**Example List Bare Metal Nodes: JSON response**
+.. rest_parameters:: parameters.yaml
+
+   - nodes: baremetal_nodes
+   - id: baremetal_id
+   - interfaces: baremetal_interfaces
+   - host: baremetal_host
+   - task_state: baremetal_taskstate
+   - cpus: baremetal_cpus
+   - memory_mb: baremetal_mem
+   - disk_gb: baremetal_disk
+
+**Example List Bare Metal Nodes**
 
 .. literalinclude:: ../../doc/api_samples/os-baremetal-nodes/baremetal-node-list-resp.json
    :language: javascript
@@ -40,17 +52,14 @@ Response
 Show Bare Metal Node Details
 ============================
 
-.. rest_method:: GET /v2.1/{tenant_id}/servers/{server_id}/os-baremetal-nodes/{node_id}
+.. rest_method:: GET /v2.1/{tenant_id}/os-baremetal-nodes/{node_id}
 
 Shows details for a bare metal node.
 
-Preconditions
-
-The bare metal node must be associated with the server.
-
 Normal response codes: 202
 
-Error response codes: unauthorized(401), forbidden(403), itemNotFound(404), notImplemented(501)
+Error response codes: unauthorized(401), forbidden(403),
+itemNotFound(404), notImplemented(501)
 
 Request
 -------
@@ -58,13 +67,24 @@ Request
 .. rest_parameters:: parameters.yaml
 
   - tenant_id: tenant_id
-  - server_id: server_id
   - node_id: node_id
 
 Response
 --------
 
-**Example Show Bare Metal Node Details: JSON response**
+.. rest_parameters:: parameters.yaml
+
+   - node: baremetal_node
+   - id: baremetal_id
+   - instance_uuid: baremetal_instance_uuid
+   - interfaces: baremetal_interfaces
+   - host: baremetal_host
+   - task_state: baremetal_taskstate
+   - cpus: baremetal_cpus
+   - memory_mb: baremetal_mem
+   - disk_gb: baremetal_disk
+
+**Example Show Bare Metal Node Details**
 
 .. literalinclude:: ../../doc/api_samples/os-baremetal-nodes/baremetal-node-get-resp.json
    :language: javascript
diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml
index 8a7fbdcd4a8e..016b83baf787 100644
--- a/api-ref/source/parameters.yaml
+++ b/api-ref/source/parameters.yaml
@@ -721,6 +721,71 @@ availability_zone:
   in: body
   required: false
   type: string
+baremetal_cpus:
+  in: body
+  required: true
+  type: string
+  description: |
+    Number of cpus the node has. Note: this is json string, even
+    though it will look like an int value.
+baremetal_disk:
+  in: body
+  required: true
+  type: string
+  description: |
+    Amount of disk in GiB the node has. Note: this is json string,
+    even though it will look like an int value.
+baremetal_host:
+  in: body
+  required: true
+  type: string
+  description: |
+    This will always have the value "IRONIC MANAGED".
+baremetal_id:
+  in: body
+  required: true
+  type: string
+  description: |
+    UUID of baremetal node
+baremetal_instance_uuid:
+  in: body
+  required: true
+  type: string
+  description: |
+    UUID of server instance on this node
+baremetal_interfaces:
+  in: body
+  required: true
+  type: array
+  description: |
+    A list of interface objects for active interfaces on the baremetal
+    node. Each will have an ``address`` field with the address.
+baremetal_mem:
+  in: body
+  required: true
+  type: string
+  description: |
+    Amount of memory in MiB the node has. Note: this is json string,
+    even though it will look like an int value.
+baremetal_node:
+  in: body
+  required: true
+  type: object
+  description: |
+    A baremetal node object
+baremetal_nodes:
+  in: body
+  required: true
+  type: array
+  description: |
+    An array of baremetal node objects
+baremetal_taskstate:
+  in: body
+  required: true
+  type: string
+  description: |
+    The Ironic task state for the node. See Ironic project for more
+    details.
 binary:
   description: |
     The binary name of the service.