# Use the CockroachDB Cloud API

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 versions, 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.

Note:

If you used the API to manage CockroachDB Serverless clusters that have been migrated to CockroachDB Basic, ensure your code is updated to work with CockroachDB Basic.

Note:

The Cloud API is rate-limited to 10 requests per second per user. When a request exceeds this limit, it receives an HTTP response with the `Retry-After` header and a "rate limit exceeded" message.

## 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 defaults 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 recieve 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.

Tip:

The service account associated with the secret key must have the Cluster Admin or Cluster Creator role.

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

Tip:

The service account associated with the secret key must have the Cluster Admin or Cluster Creator role.

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

Tip:

The service account associated with the secret key must have the Cluster Admin or Cluster Creator role.

    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 is provisioned.
- `{version}` is the CockroachDB version for the cluster. This field is optional; if omitted, the current version is 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 is 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.

Tip:

The service account associated with the secret key must have the Cluster Admin or Cluster Developer role.

    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 is successful, the API returns 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.

Tip:

The service account associated with the secret key must have the Cluster Admin or Cluster Developer role.

    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 is successful, the API returns 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.

Note:

The `spend_limit` field, which was deprecated in Serverless, is not supported on Basic or Standard. Instead, use `usage_limits`.

Tip:

The service account associated with the secret key must have the Cluster Admin or Cluster Developer role.

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

Tip:

You can decrease the provisioned capacity only three times within a 7-day period. You can increase the provisioned capacity at any time.

Tip:

The service account associated with the secret key must have the Cluster Admin or Cluster Developer role.

    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 is 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 resources for a CockroachDB Advanced cluster

To change the hardware specifications (e.g., number of vCPUs or number of nodes) for a CockroachDB Advanced cluster, use the `/v1/clusters/{cluster_id}` endpoint with the `PATCH` method. The API endpoint spawns a job to handle the change in resources. The duration of this job can vary depending on the amount of storage and the cloud provider.

For example, to change the number of vCPUs per node to 8:

    curl --request PATCH \
      --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id} \
      --header "Authorization: Bearer {secret_key}" \
      --json '{
        "spec": {
          "dedicated": {
            "hardware": {
              "machine_spec": {
                "num_virtual_cpus": 8
              }
            }
          }
        }
      }'

To change the number of nodes in a region:

    curl --request PATCH \
      --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id} \
      --header "Authorization: Bearer {secret_key}" \
      --json '{
        "spec": {
          "dedicated": {
            "region_nodes": {
              "us-east-1": 5
            }
          }
        }
      }'

Where `{cluster_id}` is the ID of your cluster and `{secret_key}` is your API key.

## Managed backups and restores

For information on using the Cloud API to handle managed backups and restore jobs, see the respective managed backup documentation for Basic, Standard, and Advanced plans.

## 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 fails.

Note:

To change a cluster's plan between CockroachDB Advanced and CockroachDB Standard, you must create and configure a new cluster, back up the existing cluster's data, and restore the backup to the new cluster. Migration in place is not supported. Refer to Self-managed backups.

## Delete a cluster

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

Tip:

The service account associated with the secret key must have the Cluster Admin or Cluster Creator role.

Warning:

Sending a `DELETE` request permanently deletes the cluster and all the data within the cluster. Deleted clusters can not be restored.

    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 is successful the client does not receive a response payload.

## Export Cloud Organization audit logs

Note:

This feature is in limited access and is only available to enrolled organizations. To enroll your organization, contact your Cockroach Labs account team. This feature is subject to change.

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

Tip:

The service account associated with the secret key must have the Cluster Admin role.

    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 is successful, the client receives 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.

## Get invoices for an organization

To list all invoices billed to an organization, send a `GET` request to the `/v1/invoices` endpoint.

Tip:

The service account associated with the secret key must have the Billing Coordinator or Cluster Admin role.

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

If the request is successful, the client receives a list of invoices billed to the organization. Each invoice object includes the start and end of the corresponding billing period, with each past invoice showing a `status` of `FINALIZED`. An invoice object is also returned for the current billing period showing usage so far with a `status` of `DRAFT`.

    {
      "invoices": [
        {<current_invoice_object>},
        {<past_invoice_object1>},
        {<past_invoice_object2>}
      ],
      "pagination": null
    }

You can request a specific invoice by providing the invoice ID in a `GET` request to the `/v1/invoices/{invoice_id}` endpoint:

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

    {
      "invoices": [
        {<invoice_object>}
      ],
      "pagination": null
    }

## List all clusters in an organization

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

Tip:

The service account associated with the secret key must have the Cluster Admin or Cluster Developer role.

    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 is successful, the client receives 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.

Tip:

The service account associated with the secret key must have the Cluster Admin or Cluster Developer role.

    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 is successful, the client receives 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.

Tip:

The service account associated with the secret key must have the Cluster Admin or Cluster Developer role.

    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 is successful, the client receives 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.

Tip:

The service account associated with the secret key must have the Cluster Admin or Cluster Creator role.

Warning:

By default, a new SQL user created using the UI or Cloud API is granted the SQL `admin` role. An `admin` SQL user has full privileges for all databases and tables in the cluster, and can create additional SQL users and manage their privileges. When possible, it is best practice to limit each user's privileges to the minimum necessary for their tasks, in keeping with the Principle of Least Privilege (PoLP).

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

Note:

Ensure that you store the password securely, as it cannot be retrieved later. If the password is lost, you'll need to reset it.

## Delete a SQL user

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

Tip:

The service account associated with the secret key must have the Cluster Admin or Cluster Creator role.

    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.
  Note:
  The cluster ID used in the Cloud API is different from the routing ID used when connecting to clusters.
- `{sql_username}` is the username of the SQL user you want to delete.
- `{secret_key}` is the secret key for the service account.

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

    {
      "name": "<sql_username>"
    }

Warning:

Deleting a SQL user cannot be undone.

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

Tip:

The service account associated with the secret key must have the Cluster Admin or Cluster Creator role.

    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.
  Note:
  The cluster ID used in the Cloud API is different from the routing ID used when connecting to clusters.
- `{sql_username}` is the username of the SQL user whose password you want to change.
- `{new_password}` is the new password for the SQL user.

If the request is 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.

## Configure a CockroachDB Advanced cluster's maintenance window

To configure a maintenance window on a CockroachDB Advanced cluster, send a `PUT` request to the `/v1/clusters/{cluster_id}/maintenance-window` endpoint.

Tip:

The service account associated with the secret key must have the Cluster Admin or Cluster Operator role.

    curl --request PUT \
      --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/maintenance-window \
      --header "Authorization: Bearer REPLACE_BEARER_TOKEN" \
      --json '{"offset_duration":"{offset_duration}","window_duration":"{window_duration}"}'

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.
- `{offset_duration}` is the start of the maintenance window, calculated as the amount of time after the start of a week (Monday 00:00 UTC) to begin the window.
- `{window_duration}` is the length of the maintenance window, which must be greater than 6 hours and less than one week.

To view a cluster's existing maintenance window, send a `GET` request to the `/api/v1/clusters/{cluster_id}/maintenance-window` endpoint:

    curl --request GET \
      --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/maintenance-window \
      --header "Authorization: Bearer REPLACE_BEARER_TOKEN"

    {
      "offset_duration": "172800s",
      "window_duration": "21600s"
    }

To remove a cluster's maintenance window, send a `DELETE` request to the `/api/v1/clusters/{cluster_id}/maintenance-window` endpoint:

    curl --request DELETE \
      --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/maintenance-window \
      --header "Authorization: Bearer REPLACE_BEARER_TOKEN"

    {
      "offset_duration": "172800s",
      "window_duration": "21600s"
    }

### Set a patch upgrade deferral policy

Automatic patch upgrades can be delayed for a period of 30, 60, or 90 days to ensure that development and testing clusters are upgraded before production clusters. This setting applies only to patch upgrades and not to major version upgrades.

To set a patch upgrade deferral policy, send a `PUT` request to the `/api/v1/clusters/{cluster_id}/version-deferral` endpoint.

Tip:

The service account associated with the secret key must have the Cluster Admin or Cluster Operator role.

    curl --request PUT \
      --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/version-deferral \
      --header "Authorization: Bearer REPLACE_BEARER_TOKEN" \
      --json '{"deferral_policy":"{deferral_policy}"}'

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.
- `{deferral_policy} is the length of the deferral window, set to`"DEFERRAL_30_DAYS"`,`"DEFERRAL_60_DAYS"`, or`"DEFERRAL_90_DAYS"`. Set to`"NOT_DEFERRED"` to remove the deferral policy and apply automatic patch upgrades immediately.

To view the existing patch deferral policy and current patch upgrade deferrals, send a `GET` request to the `/api/v1/clusters/{cluster_id}/version-deferral` endpoint.

    curl --request GET \
      --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/version-deferral \
      --header "Authorization: Bearer REPLACE_BEARER_TOKEN"

    {
      "deferral_policy": "DEFERRAL_60_DAYS",
      "deferred_until": "2025-12-15T00:00:00Z"
    }