Redpanda Cloud API: Dedicated Clusters

Dedicated clusters are fully Redpanda-managed, single-tenant Kafka clusters that run in Redpanda's own cloud account (AWS, GCP, or Azure). Redpanda provisions the VPC, Kubernetes, storage, and agent — you provide only the region, availability zones, throughput tier, and connectivity preferences. Enterprise capabilities (Tiered Storage, Remote Read Replicas, RBAC, OIDC, and more) are included by default.

The provisioning workflow has three phases: (1) create a Network resource scoped to clustertype: TYPEDEDICATED, (2) create a Cluster of type: TYPEDEDICATED referencing that network, and (3) poll the returned Operation until state: STATECOMPLETED. After the cluster reaches STATEREADY, call GetCluster to retrieve the per-cluster dataplaneapi.url and connect to topics, ACLs, and users.

All API calls go to https://api.redpanda.com (ConnectRPC/HTTP-JSON gateway) and require a Bearer token from the Auth0 client-credentials flow. The same token and base URL work for Dedicated, BYOC, and Serverless control-plane calls.

Quickstart

# 1. Get an OAuth2 bearer token (client credentials)
TOKEN=$(curl -s -X POST "https://auth.prd.cloud.redpanda.com/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=${CLIENT_ID}" \
  -d "client_secret=${CLIENT_SECRET}" \
  -d "audience=cloudv2-production.redpanda.cloud" \
  | jq -r '.access_token')

BASE="https://api.redpanda.com"

# 2. Create (or reuse) a Resource Group
RG=$(curl -s -X POST "${BASE}/v1/resource-groups" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"resource_group": {"name": "prod-dedicated"}}')
RG_ID=$(echo "${RG}" | jq -r '.resource_group.id')

# 3. List available regions for AWS
curl -s "${BASE}/v1/regions/CLOUD_PROVIDER_AWS" \
  -H "Authorization: Bearer ${TOKEN}" | jq '.regions[].name'

# 4. Create a Dedicated Network (Redpanda manages the VPC)
NET_OP=$(curl -s -X POST "${BASE}/v1/networks" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{
    \"network\": {
      \"name\": \"prod-dedicated-net\",
      \"resource_group_id\": \"${RG_ID}\",
      \"cloud_provider\": \"CLOUD_PROVIDER_AWS\",
      \"region\": \"us-east-1\",
      \"cidr_block\": \"10.0.0.0/20\",
      \"cluster_type\": \"TYPE_DEDICATED\"
    }
  }")
NET_OP_ID=$(echo "${NET_OP}" | jq -r '.operation.id')
echo "Network operation: ${NET_OP_ID}"

# 5. Poll until the network is ready
until [ "$(curl -s "${BASE}/v1/operations/${NET_OP_ID}" \
  -H "Authorization: Bearer ${TOKEN}" \
  | jq -r '.operation.state')" = "STATE_COMPLETED" ]; do
  echo "Waiting for network..."; sleep 15
done
NET_ID=$(curl -s "${BASE}/v1/operations/${NET_OP_ID}" \
  -H "Authorization: Bearer ${TOKEN}" \
  | jq -r '.operation.resource_id')

# 6. Create a TYPE_DEDICATED cluster
CLUSTER_OP=$(curl -s -X POST "${BASE}/v1/clusters" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{
    \"cluster\": {
      \"name\": \"prod-dedicated\",
      \"resource_group_id\": \"${RG_ID}\",
      \"network_id\": \"${NET_ID}\",
      \"type\": \"TYPE_DEDICATED\",
      \"cloud_provider\": \"CLOUD_PROVIDER_AWS\",
      \"region\": \"us-east-1\",
      \"zones\": [\"use1-az1\", \"use1-az2\", \"use1-az4\"],
      \"throughput_tier\": \"tier-1-aws-v2-arm\",
      \"connection_type\": \"CONNECTION_TYPE_PUBLIC\"
    }
  }")
CLUSTER_OP_ID=$(echo "${CLUSTER_OP}" | jq -r '.operation.id')
echo "Cluster operation: ${CLUSTER_OP_ID}"

# 7. Poll until the cluster is ready (can take 20–40 minutes)
until [ "$(curl -s "${BASE}/v1/operations/${CLUSTER_OP_ID}" \
  -H "Authorization: Bearer ${TOKEN}" \
  | jq -r '.operation.state')" = "STATE_COMPLETED" ]; do
  echo "Waiting for cluster..."; sleep 30
done
CLUSTER_ID=$(curl -s "${BASE}/v1/operations/${CLUSTER_OP_ID}" \
  -H "Authorization: Bearer ${TOKEN}" \
  | jq -r '.operation.resource_id')

# 8. Get cluster details including the Data Plane URL
CLUSTER=$(curl -s "${BASE}/v1/clusters/${CLUSTER_ID}" \
  -H "Authorization: Bearer ${TOKEN}")
DP_URL=$(echo "${CLUSTER}" | jq -r '.cluster.dataplane_api.url')
BROKER=$(echo "${CLUSTER}" | jq -r '.cluster.kafka_api.seed_brokers[0]')
echo "Data Plane URL: ${DP_URL}"
echo "Kafka bootstrap: ${BROKER}"

# 9. Create a topic via the Data Plane API
curl -s -X POST "${DP_URL}/v1/topics" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"topic": {"name": "events", "partition_count": 12, "replication_factor": 3}}'

Authentication

The control plane uses OAuth2 client credentials. Obtain a client ID and secret from the Clients tab of the Users section in the Redpanda Cloud console, then:

curl -s -X POST "https://auth.prd.cloud.redpanda.com/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=${CLIENT_ID}&client_secret=${CLIENT_SECRET}&audience=cloudv2-production.redpanda.cloud"

The token goes in Authorization: Bearer <token> on every request. With rpk:

rpk cloud login --client-id "${CLIENT_ID}" --client-secret "${CLIENT_SECRET}" --save
TOKEN=$(rpk cloud auth token)

Dedicated vs BYOC vs Serverless

Key API Endpoints

All paths are under https://api.redpanda.com:

rpk Cloud CLI

# Login (interactive or headless)
rpk cloud login
rpk cloud login --client-id ${CLIENT_ID} --client-secret ${CLIENT_SECRET} --save

# List clusters (shows both Dedicated and BYOC)
rpk cloud cluster select   # interactive cluster picker

# Print the current auth token
rpk cloud auth token

Cluster States

The Operation.state and Cluster.state are distinct state machines that progress concurrently.

Poll GET /v1/operations/{op_id} to track the operation:

• STATEINPROGRESS — the create/update/delete is still running
• STATECOMPLETED — the operation finished successfully; resourceid is the cluster ID
• STATE_FAILED — the operation failed

The cluster's own Cluster.state field progresses during the in-progress operation (not after it completes):

STATE_CREATING_AGENT -> STATE_CREATING -> STATE_READY

The operation reaches STATECOMPLETED roughly when the cluster reaches STATEREADY. Other cluster states: STATEUPGRADING, STATESUSPENDED, STATE_FAILED. See the [Create Cluster reference](references/create-cluster.md) for the full state machine.

Enterprise Features

Redpanda Cloud is a managed deployment of Redpanda Enterprise Edition, so on a Dedicated cluster the enterprise differentiators are part of the subscription — no separate license key is applied. You enable and tune them with topic properties (Data Plane TopicService, rpk topic, or Kafka AlterConfigs) and cluster configuration properties (ClusterCreate.clusterconfiguration.customproperties, PATCH /v1/clusters/{id} with cluster_configuration, or rpk cluster config set). Numeric cluster-config values must be JSON strings; some changes require a restart that runs as a long-running Operation.

See the [Enterprise Features reference](references/enterprise-features.md) for full per-feature key tables, defaults, curl/rpk examples, and license-expiration behavior.

Reference Directory

• [Model and Auth](references/model-and-auth.md): What Dedicated is vs BYOC vs Serverless (infrastructure ownership, tenancy, networking, cost, control); OAuth2 client-credentials auth and the bearer token; the end-to-end provisioning flow; grounded in controlplane.go and publicapi.go.
• [Create Cluster](references/create-cluster.md): Creating a Dedicated cluster via the Cluster service — all ClusterCreate fields: type=TYPEDEDICATED, cloudprovider, region, zones, throughputtier, connectiontype, PrivateLink specs (AWS/GCP/Azure), redpandaversion, cloudprovidertags, clusterconfiguration; get/list/update (PATCH /v1/clusters/{cluster.id} with required updatemask query param, body is ClusterUpdate directly)/delete; NetworkPeeringService VPC peering; Operation lifecycle and cluster state machine; grounded in the public cluster.proto, networkpeering.proto, operation.proto, and openapi.controlplane.yaml.
• [Data Plane](references/data-plane.md): Using the per-cluster Data Plane API URL returned by GetCluster for a Dedicated cluster: Topic, ACL, User, and Secret endpoints with curl examples; verified /v1 service paths (pipelines under /v1/redpanda-connect/pipelines, cloud-storage mount tasks, monitoring); base path /v1; bearer auth; grounded in openapi.dataplane.yaml and dataplane.go.
• [Enterprise Features](references/enterprise-features.md): The Enterprise differentiators included on Dedicated and their nested settings/config keys — Tiered Storage, Cloud Topics, Iceberg Topics (redpanda.iceberg., iceberg), Continuous Data Balancing (partitionautobalancing, corebalancingcontinuous), Shadow Linking cross-cluster DR (control-plane ShadowLinkService at /v1/shadow-links, Schema Registry replication in topic or HTTP-API mode including Confluent Schema Registry migration, rpk shadow failover), Remote Read Replicas, Mountable Topics, Leadership Pinning, Server-side Schema ID Validation, Audit Logging (audit), RBAC/GBAC, OIDC/OAuthBearer/Kerberos, FIPS, and Whole Cluster Restore. Each entry lists topic vs cluster scope, values/defaults, curl + rpk examples, and license-expiration behavior; grounded in the upstream feature docs and licensing overview.