Use the Control Plane API with Serverless

The Redpanda Cloud API is a collection of REST APIs that allow you to interact with different parts of Redpanda Cloud. The Control Plane API enables you to programmatically manage your organization’s Redpanda infrastructure outside of the Cloud UI. You can call the API endpoints directly, or use tools like Terraform or Python scripts to automate cluster management.

See Control Plane API for the full API reference documentation.

Control Plane API

The Control Plane API is one central API that allows you to provision clusters, networks, and resource groups.

The Control Plane API consists of the following endpoint groups:

Create a cluster

To create a new serverless cluster, you can use the default resource group, or create a new resource group if you like. You need to choose a region where your cluster is hosted.

Create a resource group

This step is optional. Serverless includes a default resource group. To retrieve the default resource group ID, make a GET request to the /v1/resource-groups endpoint:

curl -H "Authorization: Bearer <token>" https://api.redpanda.com/v1/resource-groups

Create a resource group by making a POST request to the /v1/resource-groups endpoint. Pass a name for your resource group in the request body.

curl -H 'Content-Type: application/json' \
-H "Authorization: Bearer <token>" \
-d '{
  "name": "<serverless-resource-group-name>"
}' -X POST https://api.redpanda.com/v1/resource-groups

A resource group ID is returned. Pass this ID later when you call the Create Serverless Cluster endpoint.

Choose a region

To see the available regions for Redpanda Serverless, make a GET request to the /v1/serverless/regions endpoint. You can specify a cloud provider in your request. Serverless currently only supports AWS.

curl -H "Authorization: Bearer <token>" 'https://api.redpanda.com/v1/serverless/regions?cloud_provider=CLOUD_PROVIDER_AWS'
When using a shell substitution variable for the token, use double quotes to wrap the header value. 
{
    "serverless_regions": [
        {
            "name": "pro-eu-central-1",
            "display_name": "eu-central-1",
            "default_timezone": {
                "id": "Europe/Berlin",
                "version": ""
            },
            "cloud_provider": "CLOUD_PROVIDER_AWS",
            "available": true
        },
        {
            "name": "pro-us-east-1",
            "display_name": "us-east-1",
            "default_timezone": {
                "id": "America/New_York",
                "version": ""
            },
            "cloud_provider": "CLOUD_PROVIDER_AWS",
            "available": true
        }
    ],
    "next_page_token": ""
}

Create a new serverless cluster

Create a Serverless cluster by making a request to POST /v1/serverless/clusters with the resource group ID and serverless region name in the request body.

curl -H 'Content-Type: application/json' \
-H "Authorization: Bearer <token>" \
-d '{
  "name": <serverless-cluster-name>,
  "resource_group_id": <resource-group-id>,
  "serverless_region": "pro-us-east-1"
}' -X POST https://api.redpanda.com/v1/serverless/clusters

The Create Serverless Cluster endpoint returns a long-running operation. When the operation completes, you can retrieve cluster details by calling GET /v1/serverless/clusters/{id}, and passing the cluster ID as a parameter.

Delete a cluster

To delete a cluster, make a request to the DELETE /v1/serverless/clusters/{id} endpoint, passing the cluster ID as a parameter. This is a long-running operation.

curl -H "Authorization: Bearer <token>" -X DELETE https://api.redpanda.com/v1/serverless/clusters/<cluster-id>

Optional: When the cluster is deleted, the delete operation’s state changes to STATE_COMPLETED. At this point, you may make a DELETE request to the /v1/resource-groups/{id} endpoint to delete the resource group.

Long-running operations

Some endpoints do not directly return the resource itself, but instead return an operation. The following is an example response of POST /serverless/clusters:

{
    "operation": {
        "id": "cqaramrndjr40k3qei50",
        "metadata": null,
        "state": "STATE_IN_PROGRESS",
        "started_at": {
            "seconds": "1721087323",
            "nanos": 888601218
        },
        "finished_at": null,
        "type": "TYPE_CREATE_SERVERLESS_CLUSTER"
    }
}

The response object represents the long-running operation of creating a cluster. Cluster creation is an example of an operation that can take a longer period of time to complete.

Check operation state

To check the progress of an operation, make a request to the GET /operations/{id} endpoint using the operation ID as a parameter:

curl -H "Authorization: Bearer <token>" https://api.redpanda.com/v1/operations/<operation-id>

The response contains the current state of the operation: IN_PROGRESS, COMPLETED, or FAILED.

Manage RBAC

You can also use the Control Plane API to manage RBAC configurations.

List role bindings

To see role assignments for IAM user and service accounts, make a GET request to the /v1/role-bindings endpoint.

curl https://api.redpanda.com/v1/role-bindings?filter.role_name=<role-name>&filter.scope.resource_type=SCOPE_RESOURCE_TYPE_CLUSTER \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json"

Get role binding

To see roles assignments for a specific IAM account, make a GET request to the /v1/role-bindings/{id} endpoint, passing the role binding ID as a parameter.

curl "https://api.redpanda.com/v1/role-bindings/<role-binding-id> \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json"

Get user

To see details of an IAM user account, make a GET request to the /v1/users/{id} endpoint, passing the user account ID as a parameter.

curl "https://api.redpanda.com/v1/users/<user-account-id> \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json"

Create role binding

To assign a role to an IAM user or service account, make a POST request to the /v1/role-bindings endpoint. Specify the role and scope, which includes the specific resource ID and an optional resource type, in the request body.

curl -X POST "https://api.redpanda.com/v1/role-bindings" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
           "role_name": "<role-name>",
           "account_id": "<user-or-service-account-id>",
           "scope": {
             "resource_type": "SCOPE_RESOURCE_TYPE_CLUSTER",
             "resource_id": "<resource-id>"
           }
         }'

For <role-name>, use one of roles listed in Predefined roles (Reader, Writer, Admin).

Create service account

Service accounts are assigned the Admin role for all resources in the organization.

To create a new service account, make a POST request to the /v1/service-accounts endpoint, with a service account name and optional description in the request body.

curl -X POST "https://api.redpanda.com/v1/service-accounts" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
           "service_account": {
              "name": "<service-account-name>",
              "description": "<service-account-description>"
           }
         }'

Next steps