Use the CockroachDB Cloud API

On this page

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

This document pertains to the latest version of the API's v1 endpoints, 2024-09-16. For more detailed coverage of API endpoints for this version and prior verisons, refer to the API reference documentation.

To manage clusters and other resources in CockroachDB Cloud, you can also use the CockroachDB Cloud Terraform provider, which implements the API.

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}

Replace {secret_key} with the secret key string you stored when you created the API key in the Console.

Set the API version

The Cloud API uses date-based versions of the form YYYY-MM-DD, in ISO 8601 format. It is strongly recommended that you use the Cc-Version HTTP header to specify the version of the Cloud API to use. If you omit the Cc-Version header, the Cloud API will default to the latest version. If you don’t specify the version your application expects, breakage may occur. While we try to minimize the risk of breaking API changes, passing the version explicitly helps to mitigate against this risk and is strongly recommended.

If you set an invalid version, you will get an HTTP 400 response with the message "invalid Cc-Version."

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

Authorization: Bearer {secret_key}
Cc-Version: {version}

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

Create a cluster

Get started by creating a new CockroachDB Basic, Standard, or Advanced cluster.

Create a Basic cluster

To create a cluster, send a POST request to the /v1/clusters endpoint.

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

{
  "name": "{cluster_name}",
  "provider": "{cloud_provider}",
  "plan": "BASIC",
  "spec": {
    "serverless": {
      "regions": [
        "{region_name}"
      ]
    }
  }
}

Where:

• {cluster_name} is the name of the cluster. The name must be 6-20 characters in length and can include numbers, lowercase letters, and dashes (but no leading or trailing dashes).
• {cloud_provider} is the name of the cloud provider on which you want your cluster to run: AWS, AZURE, or GCP.
• {region_name} is the name of a CockroachDB Cloud region. Region names are set by the cloud provider. For example, us-central1 is a GCP region. Available regions vary based on both the selected plan type (BASIC, STANDARD, or ADVANCED) and the cloud provider.
• plan is set to BASIC for a Basic cluster.

For example, to create a new Basic cluster named basic-test using GCP as the cloud provider and setting specific usage limits:

curl --request POST \
  --url https://cockroachlabs.cloud/api/v1/clusters \
  --header 'Authorization: Bearer {secret_key}' \
  --json '{"name":"basic-test","provider":"GCP","plan":"BASIC","spec":{"serverless":{"regions":["us-central1"]}}}'

{
  "name": "basic-test",
  "provider": "GCP",
  "plan": "BASIC",
  "spec": {
    "serverless": {
      "regions": [
        "us-central1"
      ]
    }
  }
}

If the request was successful, the API returns information about the new cluster.

For details about returned fields, refer to the response example and schema in the API reference.

Create a Standard cluster

To create a cluster, send a POST request to the /v1/clusters endpoint.

curl --request POST \
  --url https://cockroachlabs.cloud/api/v1/clusters \
  --header 'Authorization: Bearer {secret_key}' \
  --json '{"name":"{cluster_name}","provider":"{cloud_provider}","plan":"STANDARD","spec":{"serverless":{"regions":["{region_name}"],"usage_limits":{"provisioned_virtual_cpus":"2"}}}}'

{
  "name": "{cluster_name}",
  "provider": "{cloud_provider}",
  "plan": "STANDARD",
  "spec": {
    "serverless": {
      "regions": [
        "{region_name}"
      ],
      "usage_limits": {
        "provisioned_virtual_cpus": "2"
      }
    }
  }
}

Where:

• {cluster_name} is the name of the cluster. The name must be 6-20 characters in length and can include numbers, lowercase letters, and dashes (but no leading or trailing dashes).
• {cloud_provider} is the name of the cloud provider on which you want your cluster to run: AWS, AZURE, or GCP.
• {region_name} is the name of a CockroachDB Cloud region. Region names are set by the cloud provider. For example,us-west2 is a GCP region. Available regions vary based on both the selected plan type (BASIC, STANDARD, or ADVANCED) and the cloud provider.
• plan is the cluster's plan, BASIC, STANDARD, or ADVANCED. The default is STANDARD.
• The usage_limits field specifies the resource limits for the cluster. The provisioned_virtual_cpus field indicates the maximum number of virtual CPUs (vCPUs) the cluster can provision.

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

curl --request POST \
  --url https://cockroachlabs.cloud/api/v1/clusters \
  --header 'Authorization: Bearer {secret_key}' \
  --json '{"name":"notorious-moose","provider":"GCP","plan":"STANDARD","spec":{"serverless":{"regions":["us-central1"],"usage_limits":{"provisioned_virtual_cpus":"2"}}}}'

{
  "name": "notorious-moose",
  "provider": "GCP",
  "plan": "STANDARD",
  "spec": {
    "serverless": {
      "regions": [
        "us-central1"
      ],
      "usage_limits": {
        "provisioned_virtual_cpus": "2"
      }
    }
  }
}

If the request was successful, the API returns information about the new cluster.

For details about returned fields, refer to the response example and schema in the API reference.

Create an Advanced cluster

To create a cluster, send a POST request to the /v1/clusters endpoint.

curl --request POST \
  --url https://cockroachlabs.cloud/api/v1/clusters \
  --header 'Authorization: Bearer {secret_key}' \
  --json '{"name":"{cluster_name}","provider":"{cloud_provider}","plan":"ADVANCED","spec":{"dedicated":{"region_nodes":{"{region_name}":3},"hardware":{"machine_spec":{"num_virtual_cpus":{num_vcpus}}},"cockroach_version":"{version}"}}}'

{
  "name": "{cluster_name}",
  "provider": "{cloud_provider}",
  "plan": "ADVANCED",
  "spec": {
    "dedicated": {
      "region_nodes": {
        "{region_name}": 3
      },
      "hardware": {
        "machine_spec": {
          "num_virtual_cpus": {num_vcpus}
        }
      },
      "cockroach_version": "{version}"
    }
  }
}

Where:

• {cluster_name} is the name of the cluster. The name must be 6-20 characters in length and can include numbers, lowercase letters, and dashes (but no leading or trailing dashes).
• {cloud_provider} is the name of the cloud provider on which you want your cluster to run: AWS, AZURE, or GCP.
• plan is set to ADVANCED for an Advanced cluster.
• {region_name} is the name of a CockroachDB Cloud region. Region names are set by the cloud provider. For example, us-east-1 is an AWS region. Available regions vary based on both the selected plan type and the cloud provider.
• The region_nodes field specifies the number of nodes in each region. The minimum is 3 nodes per region for an Advanced cluster.
• {num_cpus} is the number of virtual CPUs per node in the cluster. This value determines the machine type that will be provisioned.
• {version} is the CockroachDB version for the cluster. This field is optional; if omitted, the current version will be used.

For example, to create a new Advanced cluster named advanced-test using AWS as the cloud provider:

curl --request POST \
  --url https://cockroachlabs.cloud/api/v1/clusters \
  --header 'Authorization: Bearer {secret_key}' \
  --json '{"name":"advanced-test","provider":"AWS","plan":"ADVANCED","spec":{"dedicated":{"region_nodes":{"us-east-1":3},"hardware":{"machine_spec":{"num_virtual_cpus":4}},"cockroach_version":"v23.1.2"}}}'

{
  "name": "advanced-test",
  "provider": "AWS",
  "plan": "ADVANCED",
  "spec": {
    "dedicated": {
      "region_nodes": {
        "us-east-1": 3
      },
      "hardware": {
        "machine_spec": {
          "num_virtual_cpus": 4
        }
      },
      "cockroach_version": "v23.1.2"
    }
  }
}

If the request was successful, the API returns information about the new cluster.

For details about returned fields, refer to the response example and schema in the API reference.

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.

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 from 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.

For details about returned fields, refer to the response example and schema in the API reference.

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.

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 from 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 provider region where the cluster is located.
• {status} is the status of the node: LIVE or NOT_READY.

Set or update resource limits for a Basic cluster

To specify the maximum RU or storage limits for a cluster, send a PATCH request to the /v1/clusters/{cluster_id} endpoint with an updated serverless.usage_limits field.

curl --request PATCH \
  --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id} \
  --header 'Authorization: Bearer {secret_key}' \
  --json '{"serverless":{"usage_limits":{"storage_mib_limit":"5242880","request_unit_limit":"50000000"}}}'

{
  "serverless": {
    "usage_limits": {
      "storage_mib_limit": "5242880",
      "request_unit_limit": "100000000"
    }
  }
}

Where:

• {cluster_id} is the unique ID of this cluster.
  Note:

  The cluster ID used in the Cloud API is different from the routing ID used when connecting to clusters.
• {secret_key} is the secret key for the service account.
• storage_mib_limit is the maximum number of MiB of storage that the cluster can use at any time during the month. If this limit is exceeded, then the cluster is throttled, where only one SQL connection is allowed at a time, with the expectation that it is used to delete data to reduce storage usage. It is an error for this value to be zero.
• request_unit_limit is the maximum number of request units that the cluster can consume during the month. If this limit is exceeded, then the cluster is disabled until the limit is increased, or until the beginning of the next month when more request units are granted. It is an error for this to be zero.

If the request was successful, the API returns the updated cluster details.

For details about returned fields, refer to the response example and schema in the API reference.

Change the number of provisioned vCPUs for a Standard cluster

To update the provisioned capacity for a Standard cluster, send a PATCH request to the /v1/clusters/{cluster_id} endpoint with an updated serverless.usage_limits field to provide a new number of provisioned vCPUs.

curl --request PATCH \
  --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id} \
  --header 'Authorization: Bearer {secret_key}' \
  --json '{"serverless":{"usage_limits":{"provisioned_virtual_cpus":"{provisioned_virtual_cpus}"}}}'

{
  "serverless": {
    "usage_limits": {
      "provisioned_virtual_cpus": "{provisioned_virtual_cpus}"
    }
  }
}

Where:

• {cluster_id} is the unique ID of this cluster.
  Note:

  The cluster ID used in the Cloud API is different from the routing ID used when connecting to clusters.
• {secret_key} is the secret key for the service account.
• {provisioned_virtual_cpus} is the number of virtual CPUs (vCPUs) the cluster provides. Once this limit is reached, operation latency may increase due to throttling.

If the request was successful, the API returns the updated cluster details.

For details about returned fields, refer to the response example and schema in the API reference.

Change a cluster's plan

This section shows how to change a cluster's plan using the CockroachDB Cloud API. To use Terraform instead, refer to Provision a cluster with Terraform. . To change a cluster's plan from CockroachDB Basic to CockroachDB Standard in place:

1. Edit the API command or application code that was used to create the cluster. In the JSON header, replace the contents of serverless {} (which may be empty) with the provisioned vCPUs for the cluster. This field is required for CockroachDB Standard. It is not possible to set storage limitations on CockroachDB Standard. Refer to CockroachDB API: Create a Standard cluster for the specification for CockroachDB Standard.
2. Run the command or application code.

To migrate from CockroachDB Standard to CockroachDB Basic:

1. Edit the API command or application code that was used to create the cluster. In the JSON header:
   • Replace the serverless.usage_limits.provisioned_virtual_cpus field with an empty value for no resource limits, or optionally values for request_unit_limit and storage_mib_limit. It is not possible to reserve compute on CockroachDB Basic. Refer to CockroachDB API: Create a Standard cluster for the specification for CockroachDB Basic.
   • Remove configurations for features that are unsupported on CockroachDB Basic, such as private connectivity. Otherwise, running the updated command or application code will fail.

Delete a cluster

To delete a cluster, send a DELETE request to the /v1/clusters/{cluster_id} endpoint.

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 from 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.

Export Cloud Organization audit logs

To export audit logs for activities and events related to your Cloud organization, send a GET request to the /v1/auditlogevents endpoint.

curl --request GET \
  --url 'https://cockroachlabs.cloud/api/v1/auditlogevents?starting_from={timestamp}&sort_order={sort_order}&limit={limit}' \
  --header 'Authorization: Bearer {secret_key}' \
  --header 'Cc-Version: {api_version}'

Where:

• {timestamp} is an RFC3339 timestamp that indicates the first log entry to fetch. If unspecified, defaults to the time when the Cloud organization was created if {sort_order} is ASC, or the current time if {sort_order} is DESC.
• {sort_order} is either ASC (the default) or DESC.
• {limit} indicates roughly how many entries to return. If any entries would be returned for a timestamp, all entries for that timestamp are always returned. Defaults to 200.
• {api_version} is the Cloud API version.

A request that includes no parameters exports roughly 200 entries in ascending order, starting from when your CockroachDB Cloud organization was created.

If the request was successful, the client will receive a JSON array consisting of a list of log entries and, depending on the circumstances, a next_starting_from field.

• If {sort_order} is ASC, next_starting_from is always returned.
• If {sort_order} is DESC, then next_starting_from is returned as long as earlier audit logs are available. It is not returned when the earliest log entry is reached (when the CockroachDB Cloud organization was created).

{
  "entries": [
    "{entry_array}"
  ],
  "next_starting_from": "{timestamp}"
}

Where:

• {entry_array} is a structured JSON array of audit log entries.
• {timestamp} indicates the timestamp to send to export the next batch of results.

List all clusters in an organization

To list all active clusters within an organization, send a GET request to the /v1/clusters endpoint.

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, in the following format.

{
  "clusters": [
    {<cluster_object1>},
    {<cluster_object2>},
    {<cluster_object3>}
  ],
  "pagination": null
}    

List the available regions for a cloud provider

To list the available regions for creating new clusters, send a GET request to the /v1/clusters/available-regions?provider={cloud_provider} endpoint.

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 provider: AWS, AZURE, or GCP.
• {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 provider.

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

Where:

• <region_array> is a string array of regions available from the cloud provider.

List the SQL users in a cluster

To list the SQL users in a cluster, send a GET request to the /v1/clusters/{cluster_id}/sql-users endpoint.

curl --request GET \
  --url 'https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/sql-users' \
  --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 from the routing ID used when connecting to clusters.
• {secret_key} is the secret key for the service account.

If the request was successful, the client will receive a list of SQL users.

{
  "users": [
    {
      "name": "<SQL-username>"
    },
    {
      "name": "<SQL-username>"
    }
  ],
  "pagination": {
    "next_page": "<next_page_token>"
  }
}

Where: - <SQL-username> is the SQL username of the user. - <next_page_token> is the token to use for retrieving the next page of results, if any.

Create a SQL user

To create a SQL user, send a POST request to the /v1/clusters/{cluster_id}/sql-users endpoint.

curl --request POST \
  --url 'https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/sql-users' \
  --header 'Authorization: Bearer {secret_key}' \
  --json '{"name":"{sql_username}","password":"{password}"}'

Where:

• {cluster_id} is the unique ID of this cluster.
  Note:

  The cluster ID used in the Cloud API is different from the routing ID used when connecting to clusters.
• {secret_key} is the secret key for the service account.
• {sql_username} is the username of the new SQL user you want to create.
• {password} is the new user's password.

If the request was successful, the client receives a response with the name of the new user.

{
  "name": "<sql_username>"
}

Where <sql_username> is the username of the newly created SQL user.

Delete a SQL user

To delete a SQL user, send a DELETE request to the /v1/clusters/{cluster_id}/sql-users/{sql_username} endpoint.

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

Where: - {cluster_id} is the unique ID of this cluster.

If the request was successful, the client receives a response with the name of the deleted user.

{
  "name": "<sql_username>"
}

Change a SQL user's password

To change a SQL user's password send a PUT request to the /v1/clusters/{cluster_id}/sql-users/{sql_username}/password endpoint.

curl --request PUT \
  --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/sql-users/{sql_username}/password \
  --header 'Authorization: Bearer {secret_key}' \
  --json '{"password":"{new_password}"}'

Where: - {cluster_id} is the unique ID of this cluster.

If the request was successful, the client receives a response with the name of the SQL user whose password was changed.

{
  "name": "<sql_username>"
}

Where <sql_username> is the name of the SQL user whose password was changed.

Was this helpful?