diff --git a/api-ref/source/clusters.inc b/api-ref/source/clusters.inc
index f15ae72d6c..1b6883392d 100644
--- a/api-ref/source/clusters.inc
+++ b/api-ref/source/clusters.inc
@@ -318,5 +318,62 @@ Response
 Response Example
 ----------------
 
-.. literalinclude:: samples/cluster-create-resp.json
-   :language: javascript
\ No newline at end of file
+.. literalinclude:: samples/cluster-resize-resp.json
+   :language: javascript
+
+
+Upgrade a cluster
+=================
+
+.. rest_method:: POST /v1/clusters/{cluster_ident}/actions/upgrade
+
+Resize a cluster.
+
+Response Codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 202
+
+.. rest_status_code:: error status.yaml
+
+   - 401
+   - 403
+   - 404
+   - 409
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+  - cluster_ident: cluster_ident
+  - cluster_template: clustertemplate_id
+  - max_batch_size: max_batch_size
+  - nodegroup: nodegroup
+
+.. note::
+
+   The nodegroup is just a placeholder for future. It hasn't been supported
+   in Magnum now.
+
+Request Example
+----------------
+
+.. literalinclude:: samples/cluster-upgrade-req.json
+   :language: javascript
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+  - X-Openstack-Request-Id: request_id
+  - uuid: cluster_id
+
+Response Example
+----------------
+
+.. literalinclude:: samples/cluster-upgrade-resp.json
+   :language: javascript
diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml
index 2daf1689fa..6a726c722d 100644
--- a/api-ref/source/parameters.yaml
+++ b/api-ref/source/parameters.yaml
@@ -386,6 +386,12 @@ master_lb_enabled:
   in: body
   required: true
   type: boolean
+max_batch_size:
+  description: |
+    The max batch size each time when doing upgrade, default value is 1
+  in: body
+  required: false
+  type: int
 mservices:
   description: |
     A list of Magnum services.
diff --git a/api-ref/source/samples/cluster-resize-resp.json b/api-ref/source/samples/cluster-resize-resp.json
new file mode 100644
index 0000000000..99d440d993
--- /dev/null
+++ b/api-ref/source/samples/cluster-resize-resp.json
@@ -0,0 +1,3 @@
+{
+   "uuid":"746e779a-751a-456b-a3e9-c883d734946f"
+}
\ No newline at end of file
diff --git a/api-ref/source/samples/cluster-upgrade-req.json b/api-ref/source/samples/cluster-upgrade-req.json
new file mode 100644
index 0000000000..f5819b199b
--- /dev/null
+++ b/api-ref/source/samples/cluster-upgrade-req.json
@@ -0,0 +1,5 @@
+{
+    "cluster_template": "e74c40e0-d825-11e2-a28f-0800200c9a66",
+    "max_batch_size": 1,
+    "nodegroup":　"production_group"
+}
\ No newline at end of file
diff --git a/api-ref/source/samples/cluster-upgrade-resp.json b/api-ref/source/samples/cluster-upgrade-resp.json
new file mode 100644
index 0000000000..94ec310409
--- /dev/null
+++ b/api-ref/source/samples/cluster-upgrade-resp.json
@@ -0,0 +1,3 @@
+{
+   "uuid":"746e779a-751a-456b-a3e9-c883d734946f"
+}