Apply suggestions from SKO session (#21)

* Apply suggestions from SKO session * Add links to endpoint for better UX * Apply suggestions from automated review * Force deploy preview * Minor edits --------- Co-authored-by: Kat Batuigas <kbauigas@gmail.com>

Author: kbatuigas

cloud-controlplane/cloud-controlplane.yaml

@@ -3258,7 +3258,7 @@ components:
  x-client-id: dQjapNIAHhF7EQqQToRla3yEII9sUSap
  type: oauth2
 info:
- description: 'Use the Control Plane API to manage resources in your Redpanda Cloud organization such as clusters and networks.'
+ description: Use the Control Plane API to manage resources in your Redpanda Cloud organization such as clusters and networks.
  title: Redpanda Cloud Control Plane API
  version: v1
 openapi: 3.0.3
@@ -5690,7 +5690,7 @@ tags:
  name: Resource Groups
  - description: Manage [Redpanda Serverless](https://docs.redpanda.com/redpanda-cloud/get-started/cloud-overview/#redpanda-cloud-cluster-types) clusters. For detailed steps, see [Use the Control Plane API with Serverless](https://docs.redpanda.com/redpanda-cloud/manage/api/cloud-serverless-controlplane-api/).
  name: Serverless Clusters
- - description: Manage Redpanda Serverless Private Links.
+ - description: Manage Redpanda Serverless private links.
  name: Serverless Private Links
  - description: See available Redpanda Serverless regions.
  name: Serverless Regions

cloud-controlplane/x-topics/quickstart.md

@@ -1,7 +1,7 @@
-The following steps describe how to authenticate with the Control Plane API and create a new Redpanda cluster. For more information on the Control Plane API, see the [Cloud API Overview](#topic-cloud-api-overview).
+The following steps describe how to authenticate with the Control Plane API and create a new Redpanda cluster.
 
 > **Note:** Redpanda Cloud uses a control plane and data plane architecture. 
-To view the available endpoints for managing resources within your clusters, such as topics, users, access control lists (ACLs), and connectors, see the [Data Plane API Reference](/api/doc/cloud-dataplane).
+To view the available endpoints for managing resources within your clusters, such as topics, users, access control lists (ACLs), and connectors, see the [Data Plane API Reference](/api/doc/cloud-dataplane). For more information on the Control Plane API, see the [Cloud API Overview](#topic-cloud-api-overview).
 
 ## Requirements
 
@@ -10,83 +10,122 @@ To use the Control Plane API:
 1. You must be a customer with an existing organization in Redpanda Cloud.
 2. You can only use one organization for authentication.
 
-**BYOC only**: To create a BYOC cluster, [install or update `rpk`](https://docs.redpanda.com/redpanda-cloud/manage/rpk/rpk-install).
+**BYOC only**: BYOC clusters require running the `rpk cloud byoc` command to install and start the Redpanda Cloud agent service. See [Install or Update `rpk`](https://docs.redpanda.com/redpanda-cloud/manage/rpk/rpk-install).
 
 ### Authenticate to the API from API Explorer
 
 The API Explorer lets you interact with the API directly from the documentation. You can quickly explore available endpoints and try requests without setting up your own test environment.
 
 To make Cloud API requests in your browser, you must obtain an access token. You can do so by clicking **Get token** on the API endpoint you want to call.
 
-If you successfully retrieve an access token, it is valid for one hour. You can use the same token in requests to both Control Plane and Data Plane API endpoints, for as long as the token is valid.
+If you successfully retrieve an access token, it is valid for one hour.
 
 > **Warning:** API requests from the API Explorer are executed against your actual environment and data, not a sandbox.
 
 ## Create a new cluster
 
 ### BYOC or Dedicated
 
-1. In the subheader, open **API Explorer**.
+1. In the subheader of this page, open [**API Explorer**](/api/doc/cloud-controlplane/explorer).
 
 1. In the **Choose an operation** dropdown, select **Create resource group**.
 
 1. Click **Get token**. You may be prompted to log in to the Redpanda Cloud UI. After you log in, the browser automatically redirects you back to the Create resource group endpoint in the API Explorer.
 
 1. Prepare your Create resource group request.
 
- 1. Under **Body**, click **+ Add** and provide a name for your resource group. A resource group is a container to organize your Redpanda Cloud resources, such as clusters and networks.
+ 1. Under **Body**, click **Add** and provide a name for your resource group. A resource group is a container to organize your Redpanda Cloud resources, such as clusters and networks.
 
- 1. Click **Send request**. If successful, the response returns a resource group ID. Pass this ID when you make a Create network request. 
+ 1. In the request panel, click **Send request**. If successful, the response returns a resource group ID. Copy the ID and use it later when you make a Create network request.
 
-1. In the dropdown, select **Create network**.
+ ```
+ {
+ "resource_group": {
+ "id": "d61b4c7f-95da-4d62-a237-9fd9f20a0c19",
+ "name": "test-resource-group",
+ ...
+ }
+ }
+ ```
+
+1. In the operation dropdown, select **Create network**.
 
 1. Prepare your Create network request.
 
  1. Include the ID of the resource group you created in the previous step. 
- 1. Click **Send request**. Note that this endpoint returns a long-running operation. The response returns a network ID in `metadata.network_id`. Pass this ID when you call the Create Cluster endpoint. To check the operation state, make a **Get operation** request with the `operation.id`. 
-
-1. When the Create network operation is complete, make a Create cluster request. Use the resource group and network IDs you just created. Note that this endpoint also returns a long-running operation.
-
-1. For BYOC, run `rpk cloud byoc` in the shell, passing the `metadata.cluster_id` from the Create cluster response as a flag:
-
- **AWS:**
- ```bash
- rpk cloud byoc aws apply --redpanda-id=<metadata.cluster_id>
- ```
- **Azure:**
- ```bash
- rpk cloud byoc azure apply --redpanda-id=<metadata.cluster_id> --subscription-id=<redpanda-cluster-azure-subscription-id>
- ```
- **GCP:**
- ```bash
- rpk cloud byoc gcp apply --redpanda-id=<metadata.cluster_id> --project-id=<gcp-project-id>
- ```
+ 
+ 1. Click **Send request**. Note that this endpoint returns a long-running operation. The response returns a network ID in `metadata.network_id`. Copy the ID and pass it later when you call the Create cluster endpoint. To check the operation state, make a [**Get operation**](/api/doc/cloud-controlplane/explorer/operation/operation-operationservice_getoperation) request with the `operation.id`.
+
+
+ ```
+ {
+ "operation": {
+ "id": "d3505t2rmm68sqlgj4u0",
+ "metadata": {
+ "@type": "type.googleapis.com/redpanda.api.controlplane.v1.CreateNetworkMetadata",
+ "network_id": "d3505ta2691o0l3484ng"
+ },
+ "state": "STATE_IN_PROGRESS",
+ ...
+ }
+ }
+ ```
+
+1. When the Create network operation is complete, make a [Create cluster](/api/doc/cloud-controlplane/explorer/operation/operation-clusterservice_createcluster) request. Use the resource group and network IDs you just created. Note that this endpoint also returns a long-running operation.
+
+1. For BYOC, run `rpk cloud byoc <cloud-provider> apply` in the shell, passing the `metadata.cluster_id` from the Create cluster response as a flag:
+
+ **AWS:**
+ ```bash
+ rpk cloud byoc aws apply --redpanda-id=<metadata.cluster_id>
+ ```
+
+ **Azure:**
+ ```bash
+ rpk cloud byoc azure apply --redpanda-id=<metadata.cluster_id> --subscription-id=<redpanda-cluster-azure-subscription-id>
+ ```
+
+ **GCP:**
+ ```bash
+ rpk cloud byoc gcp apply --redpanda-id=<metadata.cluster_id> --project-id=<gcp-project-id>
+ ```
 
 ### Serverless
 
-1. In the subheader, open **API Explorer**.
+1. In the subheader of this page, open [**API Explorer**](/api/doc/cloud-controlplane/explorer).
 
 1. In the **Choose an operation** dropdown, select **Create resource group**.
 
 1. Click **Get token**. You may be prompted to log in to the Redpanda Cloud UI. After you log in, the browser automatically redirects you back to the Create resource group endpoint in the API Explorer.
 
 1. Prepare your Create resource group request.
 
- 1. Under **Body**, click **+ Add** and provide a name for your resource group. A resource group is a container to organize your Redpanda Cloud resources, such as clusters and networks.
- 1. Click **Send request**. If successful, the response returns a resource group ID. Pass this ID later when you make a Create Serverless cluster request.
+ 1. Under **Body**, click **Add** and provide a name for your resource group. A resource group is a container to organize your Redpanda Cloud resources, such as clusters and networks.
+ 
+ 1. In the request panel, click **Send request**. If successful, the response returns a resource group ID. Copy the ID and use it later when you make a Create Serverless cluster request.
 
-1. In the dropdown, select **Create Serverless cluster**.
+ ```
+ {
+ "resource_group": {
+ "id": "d61b4c7f-95da-4d62-a237-9fd9f20a0c19",
+ "name": "test-resource-group",
+ ...
+ }
+ }
+ ```
 
-1. Prepare your Create Serverless cluster request.
+1. In the operation dropdown, scroll to **Serverless Clusters** and select [**Create Serverless cluster**](/api/doc/cloud-controlplane/explorer/operation/operation-serverlessclusterservice_createserverlesscluster).
 
- 1. Make a Get Serverless Regions request to see available regions.
- 1. In the request body, use the resource group ID and desired cloud region.
- 1. Click **Send request**. Note that this endpoint returns a long-running operation. The response returns a Serverless cluster ID in `metadata.cluster_id`. To check the operation state, make a **Get operation** request with the `operation.id`.
+1. Prepare your Create Serverless cluster request.
+ 
+ 1. In the request body, use the resource group ID and enter a [serverless region](https://docs.redpanda.com/redpanda-cloud/reference/tiers/serverless-regions/) (for example, `us-east-1`).
+ 
+ 1. Click **Send request**. Note that this endpoint returns a long-running operation. The response returns a Serverless cluster ID in `metadata.cluster_id`. To check the operation state, make a [**Get operation**](/api/doc/cloud-controlplane/explorer/operation/operation-operationservice_getoperation) request with the `operation.id`.
 
 ## Next steps: try the Data Plane APIs
 
 1. Retrieve your cluster's data plane API URL by making a **Get cluster** (BYOC, Dedicated) or **Get Serverless cluster** (Serverless) request in the API Explorer.
-1. From the value of `dataplane_api.url` in the response body, save the subdomain (the part between ``https://` and `.cloud.redpanda.com`).
+1. From the value of `dataplane_api.url` in the response body, save the subdomain (the part between `https://` and `.cloud.redpanda.com`).
 1. From the **Redpanda APIs** selector, go to **Cloud Data Plane API**.
 1. Select an operation, for example **Create topic** or **List users**. 
 1. In the URL field, add the data plane API URL. You can now make Data Plane API requests to your target cluster.

cloud-dataplane/cloud-dataplane.yaml

@@ -2227,6 +2227,7 @@ components:
 info:
  title: Redpanda Cloud Data Plane API
  version: v1
+ description: Use the Data Plane API to manage topics, ACLs, and connectors within each cluster.
 openapi: 3.0.3
 paths:
  /v1/acls:

cloud-dataplane/x-topics/quickstart.md

@@ -1,6 +1,6 @@
-The following steps describe how to authenticate with the Data Plane APIs and create a new topic. For more information on the Data Plane APIs, see the [Cloud API Overview](#topic-cloud-api-overview).
+The following steps describe how to authenticate with the Data Plane APIs and create a new topic.
 
-> **Note:** Redpanda Cloud uses a control plane and data plane architecture. To view the available endpoints for managing your clusters, networks, and resource groups, see the [Control Plane API Reference](/api/doc/cloud-controlplane).
+> **Note:** Redpanda Cloud uses a control plane and data plane architecture. To view the available endpoints for managing your clusters, networks, and resource groups, see the [Control Plane API Reference](/api/doc/cloud-controlplane). For more information on the Data Plane APIs, see the [Cloud API Overview](#topic-cloud-api-overview).
 
 ## Requirements
 
@@ -22,11 +22,11 @@ If you successfully retrieve an access token, it is valid for one hour. You can
 
 ## Create a topic
 
-1. In the subheader, open **API Explorer**.
+1. In the subheader of this page, open [**API Explorer**](/api/doc/cloud-dataplane/explorer).
 
-1. If you don't already have the data plane API URL for your target cluster, make a Get Cluster (BYOC, Dedicated) or Get Serverless Cluster (Serverless) request with the Control Plane API. The response contains the data plane API URL.
+1. If you don't already have the data plane API URL for your target cluster, make a [Get Cluster](/api/doc/cloud-controlplane/explorer/operation/operation-clusterservice_getcluster) (BYOC, Dedicated) or [Get Serverless Cluster](/api/doc/cloud-controlplane/explorer/operation/operation-serverlessclusterservice_getserverlesscluster) (Serverless) request with the Control Plane API. The response contains the data plane API URL.
 
- From the `dataplane_api.url` value in the response, extract only the subdomain (the part between `https://` and `.cloud.redpanda.com`). Enter this value in the Data Plane API URL field.
+  From the `dataplane_api.url` value in the response, extract only the subdomain (the part between `https://` and `.cloud.redpanda.com`). Enter this value in the Data Plane API URL field.
 
 1. In the **Choose an operation** dropdown, select **Create topic**.