Add section to CC API doc on updating resources for Advanced clusters (#19541)

* Add section to API doc on updating resources Advanced clusters

* Chris F feedback

---------

Co-authored-by: Joe Lodin <[email protected]>

Author: mikeCRL

src/current/cockroachcloud/cloud-api.md

@@ -585,6 +585,50 @@ If the request was successful, the API returns the updated cluster details.
 
 For details about returned fields, refer to the [response example and schema](https://www.cockroachlabs.com/docs/api/cloud/v1.html#patch-/api/v1/clusters/-cluster_id-) in the API reference.
 
+## Change the resources for a CockroachDB Advanced cluster
+
+To change the hardware specifications (e.g., number of vCPUs or number of nodes) for a CockroachDB Advanced cluster, use the `/v1/clusters/{cluster_id}` endpoint with the `PATCH` method. The API endpoint spawns a job to handle the change in resources. The duration of this job can vary depending on the amount of storage and the cloud provider.
+
+For example, to change the number of vCPUs per node to 8:
+
+{% include_cached copy-clipboard.html %}
+~~~ shell
+curl --request PATCH \
+  --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id} \
+  --header 'Authorization: Bearer {secret_key}' \
+  --json '{
+    "spec": {
+      "dedicated": {
+        "hardware": {
+          "machine_spec": {
+            "num_virtual_cpus": 8
+          }
+        }
+      }
+    }
+  }'
+~~~
+
+To change the number of nodes in a region:
+
+{% include_cached copy-clipboard.html %}
+~~~ shell
+curl --request PATCH \
+  --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id} \
+  --header 'Authorization: Bearer {secret_key}' \
+  --json '{
+    "spec": {
+      "dedicated": {
+        "region_nodes": {
+          "us-east-1": 5
+        }
+      }
+    }
+  }'
+~~~
+
+Where `{cluster_id}` is the ID of your cluster and `{secret_key}` is your API key.
+
 ## Change a cluster's plan
 
 This section shows how to change a cluster's plan using the CockroachDB {{ site.data.products.cloud }} API. To use Terraform instead, refer to [Provision a cluster with Terraform]({% link cockroachcloud/provision-a-cluster-with-terraform.md %}#change-a-clusters-plan).