diff --git a/api-ref/source/os-volume-attachments.inc b/api-ref/source/os-volume-attachments.inc
index 5ca5432b71ed..0ebc0cb75ef1 100644
--- a/api-ref/source/os-volume-attachments.inc
+++ b/api-ref/source/os-volume-attachments.inc
@@ -70,6 +70,10 @@ Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNo
           to actually support a multiattach volume depends on the volume type
           and compute hosting the instance.
 
+.. note:: This is an asynchronous API, callers should poll the status and list
+          of attachments of the volume within the volume API to determine when
+          the attachment has completed successfully.
+
 Request
 -------
 
@@ -247,6 +251,11 @@ Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNo
 .. note:: From v2.20 detach a volume from an instance in SHELVED or SHELVED_OFFLOADED
           state is allowed.
 
+.. note:: This is an asynchronous API, callers should poll the list
+          of volume attachments provided by ``GET
+          /servers/{server_id}/os-volume_attachments`` to determine when the
+          detachment of the volume has completed successfully.
+
 Request
 -------