> ## Documentation Index
> Fetch the complete documentation index at: https://cockroachlabs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Use the CockroachDB Cloud API

export const InternalLink = ({version, path = "", children, ...props}) => {
  let detectedVersion = version || "stable";
  if (typeof window !== 'undefined' && !version) {
    const match = window.location.pathname.match(/\/docs\/([^/]+)/);
    if (match) {
      detectedVersion = match[1];
    }
  }
  const normalizedPath = path.startsWith("/") ? path.slice(1) : path;
  return <a href={`/docs/${detectedVersion}/${normalizedPath}`} {...props}>
      {children}
    </a>;
};

export const version = "stable";

The Cloud API is a [REST interface](https://wikipedia.org/wiki/Representational_state_transfer) 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 <InternalLink version="api" path="cloud">API reference documentation</InternalLink>.

To manage clusters and other resources in CockroachDB Cloud, you can also use the <InternalLink version="cockroachcloud" path="provision-a-cluster-with-terraform">CockroachDB Cloud Terraform provider</InternalLink>, 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>

<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.
</Note>

## Call the API

The API uses [bearer token authentication](https://swagger.io/docs/specification/authentication/bearer-authentication), and each request requires a <InternalLink version="cockroachcloud" path="managing-access#api-access">secret key</InternalLink>. The secret key is associated with a service account, and inherits the <InternalLink version="cockroachcloud" path="managing-access#manage-service-accounts">permissions of the account</InternalLink>.

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

<CodeGroup>
  ```shell curl theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
  curl --request GET \
    --url https://cockroachlabs.cloud/api/v1/clusters \
    --header "Authorization: Bearer {secret_key}"
  ```

  ```text Raw header with Authorization theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
  Authorization: Bearer {secret_key}
  ```
</CodeGroup>

Replace <code>{'{secret_key}'}</code> with the secret key string you stored when you <InternalLink version="cockroachcloud" path="managing-access#create-api-keys">created the API key in the Console</InternalLink>.

## Set the API version

The Cloud API uses date-based versions of the form `YYYY-MM-DD`, in [ISO 8601 format](https://www.w3.org/TR/NOTE-datetime). 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."

<CodeGroup>
  ```shell curl theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
  curl --request GET \
    --url https://cockroachlabs.cloud/api/v1/clusters \
    --header "Authorization: Bearer {secret_key}" \
    --header "Cc-Version: {version}"
  ```

  ```text Raw header with Authorization, Cc-Version theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
  Authorization: Bearer {secret_key}
  Cc-Version: {version}
  ```
</CodeGroup>

Where <code>{'{secret_key}'}</code> is the <InternalLink version="cockroachcloud" path="managing-access#create-api-keys">secret key string you stored when you created the API key in the Console</InternalLink> and <code>{'{version}'}</code> is the version of the Cloud API.

## Create a cluster

Get started by creating a new CockroachDB [Basic](#create-a-basic-cluster), [Standard](#create-a-standard-cluster), or [Advanced](#create-an-advanced-cluster) 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 <InternalLink version="cockroachcloud" path="authorization#organization-user-roles">role</InternalLink>.
</Tip>

<CodeGroup>
  ```shell curl theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
  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}"]}}}'
  ```

  ```json Expanded JSON (Basic cluster creation format) theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
  {
    "name": "{cluster_name}",
    "provider": "{cloud_provider}",
    "plan": "BASIC",
    "spec": {
      "serverless": {
        "regions": [
          "{region_name}"
        ]
      }
    }
  }
  ```
</CodeGroup>

Where:

* <code>{'{cluster_name}'}</code> 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).
* <code>{'{cloud_provider}'}</code> is the name of the cloud provider on which you want your cluster to run: `AWS`, `AZURE`, or `GCP`.
* <code>{'{region_name}'}</code> is the name of a CockroachDB Cloud <InternalLink version="cockroachcloud" path="regions">region</InternalLink>. 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:

<CodeGroup>
  ```shell curl theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
  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"]}}}'
  ```

  ```json Expanded JSON (Basic cluster creation example) theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
  {
    "name": "basic-test",
    "provider": "GCP",
    "plan": "BASIC",
    "spec": {
      "serverless": {
        "regions": [
          "us-central1"
        ]
      }
    }
  }
  ```
</CodeGroup>

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

For details about returned fields, refer to the <InternalLink version="api" path="cloud/v1/clusters/create-and-initialize-a-new-cluster">response example and schema</InternalLink> in the API reference.

### Create a Standard cluster

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

The service account associated with the secret key must have the Cluster Admin or Cluster Creator <InternalLink version="cockroachcloud" path="authorization#organization-user-roles">role</InternalLink>.

<CodeGroup>
  ```shell curl theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
  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"}}}}'
  ```

  ```json Expanded JSON (Standard cluster creation format) theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
  {
    "name": "{cluster_name}",
    "provider": "{cloud_provider}",
    "plan": "STANDARD",
    "spec": {
      "serverless": {
        "regions": [
          "{region_name}"
        ],
        "usage_limits": {
          "provisioned_virtual_cpus": "2"
        }
      }
    }
  }
  ```
</CodeGroup>

Where:

* <code>{'{cluster_name}'}</code> 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).
* <code>{'{cloud_provider}'}</code> is the name of the cloud provider on which you want your cluster to run: `AWS`, `AZURE`, or `GCP`.
* <code>{'{region_name}'}</code> is the name of a CockroachDB Cloud <InternalLink version="cockroachcloud" path="regions">region</InternalLink>. 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:

<CodeGroup>
  ```shell curl theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
  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"}}}}'
  ```

  ```json Expanded JSON (Standard cluster creation example) theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
  {
    "name": "notorious-moose",
    "provider": "GCP",
    "plan": "STANDARD",
    "spec": {
      "serverless": {
        "regions": [
          "us-central1"
        ],
        "usage_limits": {
          "provisioned_virtual_cpus": "2"
        }
      }
    }
  }
  ```
</CodeGroup>

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

For details about returned fields, refer to the <InternalLink version="api" path="cloud/v1/clusters/create-and-initialize-a-new-cluster">response example and schema</InternalLink> in the API reference.

### Create an Advanced cluster

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

The service account associated with the secret key must have the Cluster Admin or Cluster Creator <InternalLink version="cockroachcloud" path="authorization#organization-user-roles">role</InternalLink>.

<CodeGroup>
  ```shell curl theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
  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}"}}}'
  ```

  ```json Expanded JSON (Advanced cluster creation format) theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
  {
    "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}"
      }
    }
  }
  ```
</CodeGroup>

Where:

* <code>{'{cluster_name}'}</code> 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).
* <code>{'{cloud_provider}'}</code> 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.
* <code>{'{region_name}'}</code> is the name of a CockroachDB Cloud <InternalLink version="cockroachcloud" path="regions">region</InternalLink>. 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.
* <code>{'{num_cpus}'}</code> is the number of virtual CPUs per node in the cluster. This value determines the machine type that is provisioned.
* <code>{'{version}'}</code> 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:

<CodeGroup>
  ```shell curl theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
  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"}}}'
  ```

  ```json Expanded JSON (Advanced cluster creation example) theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
  {
    "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"
      }
    }
  }
  ```
</CodeGroup>

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

For details about returned fields, refer to the <InternalLink version="api" path="cloud/v1/clusters/create-and-initialize-a-new-cluster">response example and schema</InternalLink> 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.

The service account associated with the secret key must have the Cluster Admin or Cluster Developer <InternalLink version="cockroachcloud" path="authorization#organization-user-roles">role</InternalLink>.

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
curl --request GET \
  --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id} \
  --header "Authorization: Bearer {secret_key}"
```

Where:

* <code>{'{cluster_id}'}</code> 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 <InternalLink version="cockroachcloud" path="connect-to-your-cluster">connecting to clusters</InternalLink>.
</Note>

* <code>{'{secret_key}'}</code> 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 <InternalLink version="api" path="cloud/v1/clusters/create-and-initialize-a-new-cluster">response example and schema</InternalLink> in the API reference.

## Get information about a CockroachDB Advanced cluster's nodes

To retrieve information about a CockroachDB Advanced 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 the Cluster Admin or Cluster Developer <InternalLink version="cockroachcloud" path="authorization#organization-user-roles">role</InternalLink>.

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
curl --request GET \
  --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/nodes \
  --header "Authorization: Bearer {secret_key}"
```

Where:

* <code>{'{cluster_id}'}</code> is the cluster ID returned after creating the cluster.

  The cluster ID used in the Cloud API is different from the routing ID used when <InternalLink version="cockroachcloud" path="connect-to-your-cluster">connecting to clusters</InternalLink>.

* <code>{'{secret_key}'}</code> is the secret key for the service account.

If the request is successful, the API returns detailed information about the nodes in the cluster.

```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
{
  "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:

* <code>{'{node_name}'}</code> is the name of the node.
* <code>{'{region_name}'}</code> is the cloud provider region where the cluster is located.
* <code>{'{status}'}</code> 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`.
</Note>

The service account associated with the secret key must have the Cluster Admin or Cluster Developer <InternalLink version="cockroachcloud" path="authorization#organization-user-roles">role</InternalLink>.

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 <InternalLink version="cockroachcloud" path="authorization#organization-user-roles">role</InternalLink>.
</Tip>

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
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:

* <code>{'{timestamp}'}</code> is an [RFC3339 timestamp](https://www.ietf.org/rfc/rfc3339.txt) that indicates the first log entry to fetch. If unspecified, defaults to the time when the Cloud organization was created if <code>{'{sort_order}'}</code> is `ASC`, or the current time if <code>{'{sort_order}'}</code> is `DESC`.
* <code>{'{sort_order}'}</code> is either `ASC` (the default) or `DESC`.
* <code>{'{limit}'}</code> 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`.
* <code>{'{api_version}'}</code> is the [Cloud API version](#set-the-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 <code>{'{sort_order}'}</code> is `ASC`, `next_starting_from` is always returned.
* If <code>{'{sort_order}'}</code> 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).

```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
{
  "entries": [
    "{entry_array}"
  ],
  "next_starting_from": "{timestamp}"
}
```

Where:

* <code>{'{entry_array}'}</code> is a structured JSON array of audit log entries.
* <code>{'{timestamp}'}</code> indicates the timestamp to send to export the next batch of results.

## Get invoices for an organization

To list all <InternalLink version="cockroachcloud" path="billing-management#view-invoices">invoices billed</InternalLink> 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 <InternalLink version="cockroachcloud" path="authorization#organization-user-roles">role</InternalLink>.
</Tip>

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
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`.

```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
{
  "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:

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
curl --request GET \
  --url https://cockroachlabs.cloud/api/v1/invoices/{invoice_id} \
  --header "Authorization: Bearer {secret_key}"
```

```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
{
  "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.

The service account associated with the secret key must have the Cluster Admin or Cluster Developer <InternalLink version="cockroachcloud" path="authorization#organization-user-roles">role</InternalLink>.

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
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.

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
curl --request GET \
  --url https://cockroachlabs.cloud/api/v1/clusters?show_inactive=true \
  --header "Authorization: Bearer {secret_key}"
```

Where:

* <code>{'{secret_key}'}</code> 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.

```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
{
  "clusters": [
    {<cluster_object1},
    {<cluster_object2},
    {<cluster_object3}
  ],
  "pagination": null
}
```

## List the available regions for a cloud provider

To list the <InternalLink version="cockroachcloud" path="regions">available regions</InternalLink> 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 the Cluster Admin or Cluster Developer <InternalLink version="cockroachcloud" path="authorization#organization-user-roles">role</InternalLink>.

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
curl --request GET \
  --url https://cockroachlabs.cloud/api/v1/clusters/available-regions?provider={cloud_provider} \
  --header "Authorization: Bearer {secret_key}"
```

Where:

* <code>{'{cloud_provider}'}</code> is the name of the cloud provider: `AWS`, `AZURE`, or `GCP`.
* <code>{'{secret_key}'}</code> 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.

```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
{
  "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.

The service account associated with the secret key must have the Cluster Admin or Cluster Developer <InternalLink version="cockroachcloud" path="authorization#organization-user-roles">role</InternalLink>.

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
curl --request GET \
  --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/sql-users \
  --header "Authorization: Bearer {secret_key}"
```

Where:

* <code>{'{cluster_id}'}</code> is the unique ID of this cluster.

  The cluster ID used in the Cloud API is different from the routing ID used when <InternalLink version="cockroachcloud" path="connect-to-your-cluster">connecting to clusters</InternalLink>.

* <code>{'{secret_key}'}</code> is the secret key for the service account.

If the request is successful, the client receives a list of SQL users.

```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
{
  "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.

The service account associated with the secret key must have the Cluster Admin or Cluster Creator <InternalLink version="cockroachcloud" path="authorization#organization-user-roles">role</InternalLink>.

<Danger>
  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 <InternalLink version="cockroachcloud" path="managing-access#use-sql-roles-to-manage-access">limit each user's privileges</InternalLink> to the minimum necessary for their tasks, in keeping with the [Principle of Least Privilege (PoLP)](https://wikipedia.org/wiki/Principle_of_least_privilege).
</Danger>

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
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:

* <code>{'{cluster_id}'}</code> is the unique ID of this cluster.

  The cluster ID used in the Cloud API is different from the routing ID used when <InternalLink version="cockroachcloud" path="connect-to-your-cluster">connecting to clusters</InternalLink>.

* <code>{'{secret_key}'}</code> is the secret key for the service account.

* <code>{'{sql_username}'}</code> is the username of the new SQL user you want to create.

* <code>{'{password}'}</code> is the new user's password.

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

```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
{
  "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.
</Note>

## Delete a SQL user

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

The service account associated with the secret key must have the Cluster Admin or Cluster Creator <InternalLink version="cockroachcloud" path="authorization#organization-user-roles">role</InternalLink>.

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
curl --request DELETE \
  --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/sql-users/{sql_username} \
  --header "Authorization: Bearer {secret_key}"
```

Where:

* <code>{'{cluster_id}'}</code> is the unique ID of this cluster.

  The cluster ID used in the Cloud API is different from the routing ID used when <InternalLink version="cockroachcloud" path="connect-to-your-cluster">connecting to clusters</InternalLink>.

* <code>{'{sql_username}'}</code> is the username of the SQL user you want to delete.

* <code>{'{secret_key}'}</code> 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.

```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
{
  "name": "<sql_username"
}
```

<Danger>
  Deleting a SQL user cannot be undone.
</Danger>

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

The service account associated with the secret key must have the Cluster Admin or Cluster Creator <InternalLink version="cockroachcloud" path="authorization#organization-user-roles">role</InternalLink>.

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
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:

* <code>{'{cluster_id}'}</code> is the unique ID of this cluster.

  The cluster ID used in the Cloud API is different from the routing ID used when <InternalLink version="cockroachcloud" path="connect-to-your-cluster">connecting to clusters</InternalLink>.

* <code>{'{sql_username}'}</code> is the username of the SQL user whose password you want to change.

* <code>{'{new_password}'}</code> 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.

```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
{
  "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 <InternalLink version="cockroachcloud" path="advanced-cluster-management#set-a-maintenance-window">maintenance window</InternalLink> on a CockroachDB Advanced cluster, send a `PUT` request to the `/v1/clusters/{cluster_id}/maintenance-window` endpoint.

The service account associated with the secret key must have the Cluster Admin or Cluster Operator <InternalLink version="cockroachcloud" path="authorization#organization-user-roles">role</InternalLink>.

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
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:

* <code>{'{cluster_id}'}</code> is the unique ID of this cluster.

  The cluster ID used in the Cloud API is different from the routing ID used when <InternalLink version="cockroachcloud" path="connect-to-your-cluster">connecting to clusters</InternalLink>.

* <code>{'{offset_duration}'}</code> 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.

* <code>{'{window_duration}'}</code> 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:

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
curl --request GET \
  --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/maintenance-window \
  --header "Authorization: Bearer REPLACE_BEARER_TOKEN"
```

```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
{
  "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:

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
curl --request DELETE \
  --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/maintenance-window \
  --header "Authorization: Bearer REPLACE_BEARER_TOKEN"
```

```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
{
  "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.

The service account associated with the secret key must have the Cluster Admin or Cluster Operator <InternalLink version="cockroachcloud" path="authorization#organization-user-roles">role</InternalLink>.

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
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:

* <code>{'{cluster_id}'}</code> is the unique ID of this cluster.

  The cluster ID used in the Cloud API is different from the routing ID used when <InternalLink version="cockroachcloud" path="connect-to-your-cluster">connecting to clusters</InternalLink>.

* `{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.

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
curl --request GET \
  --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/version-deferral \
  --header "Authorization: Bearer REPLACE_BEARER_TOKEN"
```

```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
{
  "deferral_policy": "DEFERRAL_60_DAYS",
  "deferred_until": "2025-12-15T00:00:00Z"
}
```