diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml
index a80a6729fa..11c0364b44 100644
--- a/api-ref/source/parameters.yaml
+++ b/api-ref/source/parameters.yaml
@@ -3626,6 +3626,13 @@ imageRef_rebuild:
   description: |
     The UUID of the image to rebuild for your server instance.
     It must be a valid UUID otherwise API will return 400.
+    If rebuilding a volume-backed server with a new image
+    (an image different from the image used when creating the volume),
+    the API will return 400.
+    For non-volume-backed servers, specifying a new image will result
+    in validating that the image is acceptable for the current compute host
+    on which the server exists. If the new image is not valid,
+    the server will go into ``ERROR`` status.
   in: body
   required: true
   type: string
diff --git a/api-ref/source/servers-actions.inc b/api-ref/source/servers-actions.inc
index e15d3c06cc..530b844724 100644
--- a/api-ref/source/servers-actions.inc
+++ b/api-ref/source/servers-actions.inc
@@ -480,10 +480,19 @@ Rebuilds a server.
 
 Specify the ``rebuild`` action in the request body.
 
+This operation recreates the root disk of the server.
+For a volume-backed server, this operation keeps the contents of the volume.
+
 **Preconditions**
 
 The server status must be ``ACTIVE``, ``SHUTOFF`` or ``ERROR``.
 
+**Asynchronous Postconditions**
+
+If the server was in status ``SHUTOFF`` before the rebuild, it will be stopped
+and in status ``SHUTOFF`` after the rebuild, otherwise it will be ``ACTIVE``
+if the rebuild was successful or ``ERROR`` if the rebuild failed.
+
 .. note:: There is a `known limitation`_ where the root disk is not
    replaced for volume-backed instances during a rebuild.