diff --git a/api-ref/source/os-volume-attachments.inc b/api-ref/source/os-volume-attachments.inc
index 3c2983ac8e..47d9a41a47 100644
--- a/api-ref/source/os-volume-attachments.inc
+++ b/api-ref/source/os-volume-attachments.inc
@@ -53,6 +53,9 @@ Normal response codes: 200
 
 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404), conflict(409)
 
+.. note:: From v2.20 attach a volume to an instance in SHELVED or SHELVED_OFFLOADED
+          state is allowed.
+
 Request
 -------
 
@@ -161,6 +164,9 @@ Normal response codes: 202
 
 Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404), conflict(409)
 
+.. note:: From v2.20 detach a volume from an instance in SHELVED or SHELVED_OFFLOADED
+          state is allowed.
+
 Request
 -------