Use the Cloud API

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

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: GCP and 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":"GCP","spec":{"serverless":{"regions":["us-central1"],"spendLimit":0}}}'

{
  "name": "notorious-moose",
  "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": "SERVERLESS",
  "regions": [
    {
      "name": "{region_name}",
      "sql_dns": "{server_host}",
      "ui_dns": ""
    }
  ],
  "config": {
    "serverless": {
      "regions": [
        "{region_name}"
      ],
      "spend_limit": 0,
      "routing_id": "{routing_id}"
    }
  },
  "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: GCP and AWS.
• {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": "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": "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: GCP and 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 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: LIVE and 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": "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": "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: GCP and 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: GCP and 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.

List all 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 ADMIN or READ permission to list the SQL users.

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 than the routing ID used when connecting to clusters.

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

{
  "users": [
    {
      "name": "{user name}"
    }
  ],
  ...
}

Where {user name} is the SQL username of the user.

Create a new SQL user

To create a new 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 ADMIN permission to create new SQL users. By default the newly created SQL user is a member of the admin role. An admin SQL user has full privileges for all databases and tables in your cluster. This user can also create additional users and grant them appropriate privileges.

curl --request POST \
  --url 'https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/sql-users' \
  --header 'Authorization: Bearer {secret_key}' \
  --data '{"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 than the routing ID used when connecting to clusters.
• {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 will receive 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. The service account associated with the secret key must have ADMIN permission to delete SQL users.

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 will receive a response with the name of the deleted user.

{
  "name": "{sql_username}"
}

Where {sql_username} is the username of the deleted SQL user.

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 ADMIN permission to change a SQL user's password.

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

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

If the request was successful, the client will receive 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?