diff --git a/api-ref/source/v3/parameters.yaml b/api-ref/source/v3/parameters.yaml
index 40465764cd0..30f14ed8492 100644
--- a/api-ref/source/v3/parameters.yaml
+++ b/api-ref/source/v3/parameters.yaml
@@ -2059,6 +2059,13 @@ os-unset_image_metadata:
   in: body
   required: true
   type: object
+os-update_readonly_flag:
+  description: |
+    The ``os-update_readonly_flag`` action. This action
+    enables or disables update of volume to read-only access mode.
+  in: body
+  required: true
+  type: object
 os-update_snapshot_status:
   description: |
     The ``os-update_snapshot_status`` action.
@@ -2237,6 +2244,13 @@ rate:
   in: body
   required: true
   type: array
+readonly:
+  description: |
+    Enables or disables read-only access mode.
+    This value can be True, true, False, false.
+  in: body
+  required: true
+  type: boolean
 reason_not_safe:
   description: |
     The reason why the resource can't be managed.
diff --git a/api-ref/source/v3/samples/volume-readonly-update-request.json b/api-ref/source/v3/samples/volume-readonly-update-request.json
new file mode 100644
index 00000000000..5ae3218532b
--- /dev/null
+++ b/api-ref/source/v3/samples/volume-readonly-update-request.json
@@ -0,0 +1,5 @@
+{
+    "os-update_readonly_flag": {
+        "readonly": true
+    }
+}
diff --git a/api-ref/source/v3/volumes-v3-volumes-actions.inc b/api-ref/source/v3/volumes-v3-volumes-actions.inc
index 41f0ffe6cd8..cedc66bb5a7 100644
--- a/api-ref/source/v3/volumes-v3-volumes-actions.inc
+++ b/api-ref/source/v3/volumes-v3-volumes-actions.inc
@@ -796,3 +796,35 @@ Request Example
 .. literalinclude:: ./samples/volume-initialize-connection-request.json
    :language: javascript
 
+
+Updates volume read-only access-mode flag
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. rest_method::  POST /v3/{project_id}/volumes/{volume_id}/action
+
+Enables or disables update of volume to read-only access mode.
+Specify the ``os-update_readonly_flag`` action in the request body.
+
+Response codes
+--------------
+
+.. rest_status_code:: success ../status.yaml
+
+   - 202
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - project_id: project_id_path
+   - volume_id: volume_id_path
+   - os-update_readonly_flag: os-update_readonly_flag
+   - readonly: readonly
+
+Request Example
+---------------
+
+.. literalinclude:: ./samples/volume-readonly-update-request.json
+   :language: javascript