Redpanda Cloud API: Serverless Clusters

Redpanda Cloud Serverless clusters are fully managed Kafka-compatible clusters provisioned through the public Control Plane API at https://api.redpanda.com. You authenticate once with OAuth2 client credentials, then create a ResourceGroup, pick a ServerlessRegion, and call POST /v1/serverless/clusters. The API returns an async Operation; when the Operation reaches STATECOMPLETED, the cluster has reached STATEREADY and its dataplaneapi.url is live for Kafka workloads and the Data Plane REST API. (STATECOMPLETED is the Operation state; STATE_READY is the cluster state — they are distinct state machines.)

This skill does not cover BYOC (Bring Your Own Cloud) clusters — see the cloud-byoc skill for those. For the CLI equivalent, see the rpk-cloud skill.

Quickstart

Copy-paste these commands. Replace CLIENTID and CLIENTSECRET with the credentials from your Redpanda Cloud service account.

# ── 1. Get a bearer token ─────────────────────────────────────────────────────
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)

# ── 2. List available serverless regions ──────────────────────────────────────
curl -s -X GET "https://api.redpanda.com/v1/serverless/regions?cloud_provider=CLOUD_PROVIDER_AWS" \
  -H "Authorization: Bearer ${TOKEN}" | jq .

# ── 3. Create a resource group (billing/org container) ───────────────────────
RG_ID=$(curl -s -X POST https://api.redpanda.com/v1/resource-groups \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"resource_group": {"name": "my-dev-group"}}' \
  | jq -r .resource_group.id)

# ── 4. Create a serverless cluster ────────────────────────────────────────────
OP_ID=$(curl -s -X POST https://api.redpanda.com/v1/serverless/clusters \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{
    \"serverless_cluster\": {
      \"name\": \"my-cluster\",
      \"resource_group_id\": \"${RG_ID}\",
      \"serverless_region\": \"us-east-1\"
    }
  }" | jq -r .operation.id)

# ── 5. Poll the operation until STATE_COMPLETED ───────────────────────────────
watch -n 5 "curl -s https://api.redpanda.com/v1/operations/${OP_ID} \
  -H 'Authorization: Bearer ${TOKEN}' | jq '{state: .operation.state}'"

# ── 6. Get the cluster and its data-plane URL ─────────────────────────────────
# Read the cluster ID directly from the completed operation (resource_id or
# metadata.serverless_cluster_id) — more reliable than listing by name.
OP_RESP=$(curl -s "https://api.redpanda.com/v1/operations/${OP_ID}" \
  -H "Authorization: Bearer ${TOKEN}")
CLUSTER_ID=$(echo "${OP_RESP}" | jq -r '.operation.resource_id')

CLUSTER=$(curl -s "https://api.redpanda.com/v1/serverless/clusters/${CLUSTER_ID}" \
  -H "Authorization: Bearer ${TOKEN}" | jq '.serverless_cluster')
echo "${CLUSTER}" | jq '{id: .id, state: .state, dataplane_url: .dataplane_api.url}'

DP_URL=$(echo "${CLUSTER}" | jq -r '.dataplane_api.url')

# ── 7. Create a topic via the data-plane URL ──────────────────────────────────
curl -s -X POST "${DP_URL}/v1/topics" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"topic": {"name": "events", "partition_count": 3, "replication_factor": 3}}'

Authentication

The Control Plane API and Data Plane API both use the same OAuth2 bearer token. See [Authentication Reference](references/auth.md) for full details.

Credentials come from a ServiceAccount created in the Redpanda Cloud console or via POST /v1/service-accounts. The response includes a clientid and clientsecret (the secret is only shown once on creation; save it securely).

Control Plane Resources

ResourceGroup

A ResourceGroup is the billing and organizational container for clusters. It must exist before you can create a ServerlessCluster.

POST   /v1/resource-groups
GET    /v1/resource-groups/{id}
GET    /v1/resource-groups          # list with optional filter.name_contains
PATCH  /v1/resource-groups/{resource_group.id}
DELETE /v1/resource-groups/{id}

Name constraints: 3–253 alphanumeric characters and hyphens (^[a-zA-Z0-9-]+$).

ServerlessRegion

Regions represent the cloud-provider geographic areas where Serverless clusters can be placed. List them before creating a cluster to confirm placement.enabled.

GET /v1/serverless/regions?cloud_provider=CLOUD_PROVIDER_AWS
GET /v1/serverless/regions?cloud_provider=CLOUD_PROVIDER_GCP
GET /v1/serverless/region?cloud_provider=CLOUD_PROVIDER_AWS&name=us-east-1

cloudprovider accepts CLOUDPROVIDERAWS, CLOUDPROVIDERGCP, or CLOUDPROVIDERAZURE. Use filter.placementenabled_only=true to skip regions that cannot currently accept new clusters.

ServerlessCluster Lifecycle

Full CRUD plus the Operation pattern:

POST   /v1/serverless/clusters           → 202 CreateServerlessClusterOperation
GET    /v1/serverless/clusters/{id}      → ServerlessCluster
GET    /v1/serverless/clusters           → ListServerlessClustersResponse (paginated)
PATCH  /v1/serverless/clusters/{id}      → 202 UpdateServerlessClusterOperation
DELETE /v1/serverless/clusters/{id}      → 202 DeleteServerlessClusterOperation
GET    /v1/serverless/clusters/{id}/prometheus/credentials

State machine (from the proto):

Create request fields (grounded in serverless.proto):

Response fields on GET (output-only):

Operations

Create, Update, and Delete each return an Operation whose type is TYPECREATESERVERLESSCLUSTER, TYPEUPDATESERVERLESSCLUSTER, or TYPEDELETESERVERLESS_CLUSTER respectively, so you can filter operations by any of the three. Poll at GET /v1/operations/{id}.

GET /v1/operations/{id}
GET /v1/operations               # list with filter.type_in / filter.state / filter.resource_id

Operation states: STATEINPROGRESS, STATECOMPLETED, STATEFAILED. When state == STATECOMPLETED, the response field contains the final resource. When state == STATEFAILED, the error field contains a google.rpc.Status.

ServerlessPrivateLink (AWS PrivateLink)

The privatelinkid field on a cluster refers to a ServerlessPrivateLink resource, managed by its own control-plane service (AWS only). Create the private link first, then pass its 20-char id as privatelinkid when you create a cluster with private networking enabled. Serverless on AWS went GA in Feb 2026 with PrivateLink support.

POST   /v1/serverless/private-links       → 202 Operation (TYPE_CREATE_SERVERLESS_PRIVATE_LINK)
GET    /v1/serverless/private-links/{id}
GET    /v1/serverless/private-links        # list (paginated, filterable)
PATCH  /v1/serverless/private-links/{id}   → 202 Operation
DELETE /v1/serverless/private-links/{id}   → 202 Operation

Required create fields: name, resourcegroupid, cloudprovider (CLOUDPROVIDERAWS only — CEL-enforced with awsconfig), awsconfig.allowedprincipals (min 1 AWS principal ARN), and serverlessregion. See [Control Plane: Serverless](references/control-plane-serverless.md#serverlessprivatelink) for the full field-level reference and the private-networking workflow.

Data Plane API

Once your cluster is STATEREADY, use dataplaneapi.url as the base URL. The same bearer token is valid. Base path is /v1. Always read the URL from the API response — do not construct it manually. The real DNS pattern (from openapi.controlplane.yaml examples) is https://<cluster-id>.any.<region>.mpx.prd.cloud.redpanda.com.

Available services (grounded in dataplane.go and openapi.dataplane.yaml):

See [Data Plane Reference](references/data-plane.md) for examples and availability notes on Serverless clusters.

Enterprise Features on Serverless

Redpanda Cloud is a managed deployment of Redpanda Enterprise Edition — the license is included, so there is no rpk cluster license step for tenants. The enterprise differentiators you configure on Serverless are exposed as topic configuration keys (via ${DPURL}/v1/topics) and RBAC roles (via ${DPURL}/v1/roles), not cluster/node config:

Cluster/node-level enterprise features (Tiered Storage internals, FIPS, Continuous Data Balancing thresholds, Audit Logging, Remote Read Replicas, Cloud Topics, Shadow Linking / cross-cluster DR, Whole Cluster Restore) are managed by Redpanda on Serverless and are not tenant-configurable — use a BYOC/Dedicated or self-managed cluster for those. See [Enterprise Features Reference](references/enterprise-features.md) for the full key tables, accepted values, defaults, mode semantics, and self-managed mappings.

Serverless vs BYOC

Reference Directory

• [Authentication](references/auth.md): OAuth2 client-credentials flow, token endpoint, audience, Authorization header, service-account creation, and token refresh.
• [Control Plane: Serverless](references/control-plane-serverless.md): ResourceGroup, ServerlessRegion, and ServerlessCluster field-level reference, the async Operation pattern, state machine, and list filtering.
• [Data Plane](references/data-plane.md): Using the per-cluster Data Plane API URL, Topic/ACL/User/Secret/Pipeline endpoints with curl examples.
• [Enterprise Features](references/enterprise-features.md): Enterprise differentiators configurable on Serverless — Iceberg Topics, Server-Side Schema ID Validation, Leadership Pinning, and RBAC — with every topic config key, accepted values, defaults, Iceberg mode semantics, license-requirement notes, and which cluster-level features are managed by Redpanda (not tenant-configurable).