diff --git a/api-ref/source/v2/samples/volume-image-metadata-update-response.json b/api-ref/source/v2/samples/volume-image-metadata-update-response.json
new file mode 100644
index 00000000000..ecaa668c79a
--- /dev/null
+++ b/api-ref/source/v2/samples/volume-image-metadata-update-response.json
@@ -0,0 +1,14 @@
+{
+    "metadata": {
+        "kernel_id": "6ff710d2-942b-4d6b-9168-8c9cc2404ab1",
+        "container_format": "bare",
+        "min_ram": "0",
+        "ramdisk_id": "somedisk",
+        "disk_format": "qcow2",
+        "image_name": "image",
+        "image_id": "5137a025-3c5f-43c1-bc64-5f41270040a5",
+        "checksum": "f8ab98ff5e73ebab884d80c9dc9c7290",
+        "min_disk": "0",
+        "size": "13267968"
+    }
+}
diff --git a/api-ref/source/v2/volumes-v2-volumes-actions.inc b/api-ref/source/v2/volumes-v2-volumes-actions.inc
index c37e448614e..b8f87b37c93 100644
--- a/api-ref/source/v2/volumes-v2-volumes-actions.inc
+++ b/api-ref/source/v2/volumes-v2-volumes-actions.inc
@@ -125,6 +125,21 @@ Request Example
    :language: javascript
 
 
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - metadata: metadata_8
+
+
+Response Example
+----------------
+
+.. literalinclude:: ./samples/volume-image-metadata-update-response.json
+   :language: javascript
+
+
 Remove image metadata from volume
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/api-ref/source/v3/samples/volume-image-metadata-update-response.json b/api-ref/source/v3/samples/volume-image-metadata-update-response.json
new file mode 100644
index 00000000000..ecaa668c79a
--- /dev/null
+++ b/api-ref/source/v3/samples/volume-image-metadata-update-response.json
@@ -0,0 +1,14 @@
+{
+    "metadata": {
+        "kernel_id": "6ff710d2-942b-4d6b-9168-8c9cc2404ab1",
+        "container_format": "bare",
+        "min_ram": "0",
+        "ramdisk_id": "somedisk",
+        "disk_format": "qcow2",
+        "image_name": "image",
+        "image_id": "5137a025-3c5f-43c1-bc64-5f41270040a5",
+        "checksum": "f8ab98ff5e73ebab884d80c9dc9c7290",
+        "min_disk": "0",
+        "size": "13267968"
+    }
+}
diff --git a/api-ref/source/v3/volumes-v3-volumes-actions.inc b/api-ref/source/v3/volumes-v3-volumes-actions.inc
index 09cc39605c7..e87f1634ed2 100644
--- a/api-ref/source/v3/volumes-v3-volumes-actions.inc
+++ b/api-ref/source/v3/volumes-v3-volumes-actions.inc
@@ -185,6 +185,21 @@ Request Example
    :language: javascript
 
 
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - metadata: metadata_image
+
+
+Response Example
+----------------
+
+.. literalinclude:: ./samples/volume-image-metadata-update-response.json
+   :language: javascript
+
+
 Remove image metadata from a volume
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~