Use the Cloud API

The Cloud API is a REST interface that allows users programmatic access to manage the lifecycle of clusters within their organization.

Warning:

This is a private and experimental feature. The interface and output are subject to change. To request access to this feature, contact us at earlyaccess@cockroachlabs.com.

API reference

Refer to the full API reference documentation for detailed descriptions of the API endpoints and options.

Call the API

The API uses bearer token authentication, and each request requires a secret key. The secret key is associated with a service account, and inherits the permissions of the account.

To send the secret key when making an API call, add the secret key to the Authorization HTTP header sent with the request.

curl --request GET \
  --url 'https://cockroachlabs.cloud/api/v1/clusters' \
  --header 'Authorization: Bearer {secret_key}'

Authorization: Bearer {secret_key}

Where {secret_key} is the secret key string you stored when you created the API key in the Console.

Create a new cluster

To create a cluster, send a POST request to the /v1/clusters endpoint. The service account associated with the secret key must have ADMIN or CREATE permission to create new clusters.

curl --request POST \
  --url https://cockroachlabs.cloud/api/v1/clusters \
  --header 'Authorization: Bearer {secret_key}' \
  --data '{"name":"{cluster_name}","provider":"{cloud_provider}","spec":{"serverless":{"regions":["{region_name}"],"spendLimit":{spend_limit}}}}'

{
  "name": "{cluster_name}",
  "provider": "{cloud_provider}",
  "spec": {
    "serverless": {
      "regions": [
        "{region_name}"
      ],
      "spendLimit": {spend_limit}
    }
  }
}

Where:

{cluster_name} is the name of the cluster. This should be a short string with no whitespace.
{cloud_provider} is the name of the cloud infrastructure provider on which you want your cluster to run. Possible values are: CLOUD_PROVIDER_GCP and CLOUD_PROVIDER_AWS.
{region_name} is the zone code of the cloud infrastructure provider. For example, on GCP you can set the "us-west2" zone code.
{spend_limit} is the maximum amount of money, in US cents, you want to spend per month on this cluster.

For example, to create a new free Serverless cluster named "notorious-moose" using the default values for the cloud infrastructure provider and region:

curl --request POST \
  --url https://cockroachlabs.cloud/api/v1/clusters \
  --header 'Authorization: Bearer {secret_key}' \
  --data '{"name":"notorious-moose","provider":"CLOUD_PROVIDER_GCP","spec":{"serverless":{"regions":["us-central1"],"spendLimit":0}}}'

{
  "name": "notorious-moose",
  "provider": "CLOUD_PROVIDER_GCP",
  "spec": {
    "serverless": {
      "regions": [
        "us-central1"
      ],
      "spendLimit": 0
    }
  }
}

If the request was successful, the API will return information about the newly created cluster.

{
  "cloud_provider": "{cloud_provider}",
  "created_at": "2022-03-14T14:15:22Z",
  "creator_id": "{account_id}",
  "deleted_at": "2022-03-14T14:15:22Z",
  "id": "{cluster_id}",
  "operation_status": "CLUSTER_STATUS_UNSPECIFIED",
  "name": "{cluster_name}",
  "plan": "PLAN_SERVERLESS",
  "regions": [
    {
      "name": "{region_name}",
      "sql_dns": "{server_host}",
      "ui_dns": ""
    }
  ],
  "config": {
    "serverless": {
      "regions": [
        "{region_name}"
      ],
      "spend_limit": 0,
      "routing_id": "{routing_id}"
    }
  },
  "state": "CLUSTER_STATE_CREATING",
  "updated_at": "2022-03-14T14:15:22Z"
}

Where:

{cloud_provider} is the name of the cloud infrastructure provider on which you want your cluster to run. Possible values are: CLOUD_PROVIDER_GCP and CLOUD_PROVIDER_AWS. The default value is CLOUD_PROVIDER_UNSPECIFIED.
{cluster_id} is the unique ID of this cluster. Use this ID when making API requests for this particular cluster.
Note:
The cluster ID used in the Cloud API is different than the routing ID used when connecting to clusters.
{cluster_name} is the name of the cluster you specified when creating the cluster.
{account_id} is the ID of the account that created the cluster. If the cluster was created using the API, this will be the service account ID associated with the secret key used when creating the cluster.
{region_name} is the zone code of the cloud infrastructure provider where the cluster is located.
{routing_id} is the cluster name and tenant ID of the cluster used when connecting to clusters. For example, funky-skunk-123.
{server_host} is the DNS name of the host on which the cluster is located.

Get information about a specific cluster

To retrieve detailed information about a specific cluster, make a GET request to the /v1/clusters/{cluster_id} endpoint. The service account associated with the secret key must have ADMIN or READ permission to retrieve information about an organization's clusters.

curl --request GET \
  --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id} \
  --header 'Authorization: Bearer {secret_key}'

Where:

{cluster_id} is the cluster ID returned after creating the cluster.
Note:
The cluster ID used in the Cloud API is different than the routing ID used when connecting to clusters.
{secret_key} is the secret key for the service account.

If the request was successful, the API will return detailed information about the cluster.

{
  "cloud_provider": "{cloud_provider}",
  "created_at": "2022-03-14T14:15:22Z",
  "creator_id": "{account_id}",
  "deleted_at": "2022-03-14T14:15:22Z",
  "id": "{cluster_id}",
  "operation_status": "CLUSTER_STATUS_UNSPECIFIED",
  "name": "{cluster_name}",
  "plan": "PLAN_SERVERLESS",
  "regions": [
    {
      "name": "{region_name}",
      "sql_dns": "{server_host}",
      "ui_dns": ""
    }
  ],
  "config": {
    "serverless": {
      "regions": [
        "{region_name}"
      ],
      "spend_limit": {spend_limit},
      "routing_id": "{routing_id}"
    }
  },
  "state": "CLUSTER_STATE_CREATING",
  "updated_at": "2022-03-14T14:15:22Z"
}

Where:

{cluster_id} is the unique ID of this cluster. Use this ID when making API requests for this particular cluster.
Note:
The cluster ID used in the Cloud API is different than the routing ID used when connecting to clusters.
{cluster_name} is the name of the cluster you specified when creating the cluster.
{cloud_provider} is the name of the cloud infrastructure provider on which you want your cluster to run. Possible values are: CLOUD_PROVIDER_GCP and CLOUD_PROVIDER_AWS. The default value is CLOUD_PROVIDER_UNSPECIFIED.
{account_id} is the ID of the account that created the cluster. If the cluster was created using the API, this will be the service account ID associated with the secret key used when creating the cluster.
{region_name} is the cloud infrastructure provider region where the cluster is located.
{spend_limit} is the maximum amount of money, in US cents, you want to spend per month on this cluster.
{routing_id} is the cluster name and tenant ID of the cluster used when connecting to clusters. For example, funky-skunk-123.
{server_host} is the DNS name of the host on which the cluster is located.

Get information about a cluster's nodes

To retrieve information about a cluster's nodes, including the node status, make a GET request to the /v1/clusters/{cluster_id}/nodes endpoint. The service account associated with the secret key must have ADMIN or READ permission to retrieve information about an organization's clusters.

curl --request GET \
  --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/nodes \
  --header 'Authorization: Bearer {secret_key}'

Where:

{cluster_id} is the cluster ID returned after creating the cluster.
Note:
The cluster ID used in the Cloud API is different than the routing ID used when connecting to clusters.
{secret_key} is the secret key for the service account.

If the request was successful, the API will return detailed information about the nodes in the cluster.

{
  "nodes": [
    {
      "name": "{node_name}",
      "region_name": "{region_name}",
      "status": "{status}"
    }
  ],
  "pagination": {
    "next": 0,
    "last": 0,
    "limit": 0,
    "total_results": 0,
    "time": "2022-03-14T14:15:22Z",
    "order": "ASC"
  }
}

Where:

{node_name} is the name of the node.
{region_name} is the cloud infrastructure provider region where the cluster is located.
{status} is the status of the node. Possible values are: NODE_STATUS_LIVE and NODE_STATUS_NOT_READY.

Set the maximum spend limit of a Serverless cluster

To set the maximum spend limit for a Serverless cluster, send a PUT request to the /v1/clusters/{cluster_id}/spend-limit endpoint. The service account associated with the secret key must have ADMIN or EDIT permission to retrieve information about an organization's clusters.

curl --request PUT \
  --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/spend-limit \
  --header 'Authorization: Bearer {secret_key}' \
  --data '{"spendLimit": {spend_limit}}'

{
  "spendLimit": {spend_limit}
}

Where:

{cluster_id} is the unique ID of this cluster.
Note:
The cluster ID used in the Cloud API is different than the routing ID used when connecting to clusters.
{secret_key} is the secret key for the service account.
{spend_limit} is the maximum amount of money, in US cents, you want to spend per month on this cluster.

If the request was successful, the client will not receive a response payload.

Delete a cluster

To delete a cluster, send a DELETE request to the /v1/clusters/{cluster_id} endpoint. The service account associated with the secret key must have ADMIN or DELETE permission to delete an organization's clusters.

Deleting a cluster will permanently delete the cluster and all the data within the cluster.

curl --request DELETE \
  --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id} \
  --header 'Authorization: Bearer {secret_key}'

Where:

{cluster_id} is the unique ID of this cluster.
Note:
The cluster ID used in the Cloud API is different than the routing ID used when connecting to clusters.
{secret_key} is the secret key for the service account.

If the DELETE request was successful the client will not receive a response payload.

List all clusters in an organization

To list all active clusters within an organization, send a GET request to the /v1/clusters endpoint. The service account associated with the secret key must have ADMIN or READ permission to list an organization's clusters.

curl --request GET \
  --url 'https://cockroachlabs.cloud/api/v1/clusters' \
  --header 'Authorization: Bearer {secret_key}'

To return both active clusters and clusters that have been deleted or failed to initialize, send the show_inactive=true query parameter.

curl --request GET \
  --url 'https://cockroachlabs.cloud/api/v1/clusters?show_inactive=true' \
  --header 'Authorization: Bearer {secret_key}'

Where:

{secret_key} is the secret key for the service account.

If the request was successful, the client will receive a list of all clusters within the organization.

{
  "clusters": [
    {
      "cloud_provider": "{cloud_provider}",
      "created_at": "2022-03-14T14:15:22Z",
      "creator_id": "{account_id}",
      "deleted_at": "2022-03-14T14:15:22Z",
      "id": "{cluster_id}",
      "operation_status": "CLUSTER_STATUS_UNSPECIFIED",
      "name": "{cluster_name}",
      "plan": "PLAN_SERVERLESS",
      "regions": [
        {
          "name": "{region_name}",
          "sql_dns": "{server_host}",
          "ui_dns": ""
        }
      ],
      "config": {
        "serverless": {
          "regions": [
            "{region_name}"
          ],
          "spend_limit": {spend_limit},
          "routing_id": "{routing_id}"
        }
      },
      "state": "CLUSTER_STATE_CREATING",
      "updated_at": "2022-03-14T14:15:22Z"
    }
  ],
  ...
  }
}

Where:

{cluster_id} is the unique ID of this cluster.
Note:
The cluster ID used in the Cloud API is different than the routing ID used when connecting to clusters.
{cluster_name} is the name of the cluster.
{cloud_provider} is the name of the cloud infrastructure provider. Possible values are: CLOUD_PROVIDER_GCP and CLOUD_PROVIDER_AWS.
{account_id} is the ID of the account that created the cluster. If the cluster was created using the API, this will be the service account ID associated with the secret key used when creating the cluster.
{region_name} is the zone code of the cloud infrastructure provider where the cluster is located.
{spend_limit} is the maximum amount of money, in US cents, you want to spend per month on this cluster.

List the available regions for a cloud infrastructure provider

To list the available regions for creating new clusters, send a GET request to the /v1/clusters/available-regions?provider={cloud_provider} endpoint. The service account associated with the secret key must have ADMIN or READ permission to list the available regions.

curl --request GET \
  --url 'https://cockroachlabs.cloud/api/v1/clusters/available-regions?provider={cloud_provider}' \
  --header 'Authorization: Bearer {secret_key}'

Where:

{cloud_provider} is the name of the cloud infrastructure provider. Possible values are: CLOUD_PROVIDER_GCP and CLOUD_PROVIDER_AWS.
{secret_key} is the secret key for the service account.

If the request was successful, the client will receive a list of available regions for the specified cloud infrastructure provider.

{
  "regions": [
    "{region_array}"
  ]
}

Where:

{region_array} is a string array of regions available from the cloud infrastructure provider.

Was this page helpful?

Yes

Cockroach
University

Docs Hub

API reference

Call the API

Create a new cluster

Get information about a specific cluster

Get information about a cluster's nodes

Set the maximum spend limit of a Serverless cluster

Delete a cluster

List all clusters in an organization

List the available regions for a cloud infrastructure provider

Cockroach University

Docs Hub

Cockroach University

Docs Hub

Use the Cloud API

API reference

Call the API

Create a new cluster

Get information about a specific cluster

Get information about a cluster's nodes

Set the maximum spend limit of a Serverless cluster

Delete a cluster

List all clusters in an organization

List the available regions for a cloud infrastructure provider

Cockroach
University

Cockroach
University