Documentation Powered by ReDoc

CockroachDB Cloud API (2022-03-31)

Download OpenAPI specification:Download

Cockroach Labs Support: support@cockroachlabs.com URL: https://support.cockroachlabs.com

This is an early access, experimental version of the Cloud API. The interface and output is subject to change, and there may be bugs.

Use the CockroachDB Cloud API

Authentication

Bearer

Security Scheme Type HTTP
HTTP Authorization Scheme bearer

CockroachCloud

List clusters owned by an organization.

Sort order: Cluster name

Authorizations:
Bearer
query Parameters
show_inactive
boolean
Default: "false"

If true, show clusters that have been deleted or failed to initialize.

pagination.start_key
string
pagination.direction
string
Default: "PAGE_DIRECTION_NEXT"
Enum: "PAGE_DIRECTION_NEXT" "PAGE_DIRECTION_LAST"
pagination.limit
integer <int32>
pagination.time
string <date-time>
pagination.order
string
Default: "ASC"
Enum: "ASC" "DESC"
  • DESC: Sort in descending order. The default order is ascending.

Responses

Request samples 

curl --request GET \
  --url 'https://cockroachlabs.cloud/api/v1/clusters?show_inactive=SOME_BOOLEAN_VALUE&pagination.start_key=SOME_STRING_VALUE&pagination.direction=SOME_STRING_VALUE&pagination.limit=SOME_INTEGER_VALUE&pagination.time=SOME_STRING_VALUE&pagination.order=SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "clusters": [
    ],
  • "pagination": {
    }
}

Create and initialize a new cluster.

Authorizations:
Bearer
Request Body schema: application/json
name
required
string
provider
required
string (api.CloudProvider)
Default: "CLOUD_PROVIDER_UNSPECIFIED"
Enum: "CLOUD_PROVIDER_UNSPECIFIED" "GCP" "AWS"
  • GCP: The Google Cloud Platform cloud provider.
  • AWS: The Amazon Web Services cloud provider.
required
object (CreateClusterSpecification)

Responses

Request samples

Content type
application/json
{
  • "name": "test-cluster",
  • "provider": "GCP",
  • "spec": {
    }
}

Response samples

Content type
application/json
{
  • "id": "35c4abb2-bb66-46d7-afed-25ebef5ed2aa",
  • "name": "example-cluster",
  • "cockroach_version": "v21.2.4",
  • "plan": "SERVERLESS",
  • "cloud_provider": "GCP",
  • "account_id": "",
  • "state": "CREATED",
  • "creator_id": "7cde0cd9-0d8a-4008-8f90-45092ce8afc1",
  • "operation_status": "CLUSTER_STATUS_UNSPECIFIED",
  • "config": {
    },
  • "regions": [
    ],
  • "created_at": "2022-03-22T20:23:11.285067Z",
  • "updated_at": "2022-03-22T20:23:11.879593Z",
  • "deleted_at": null
}

List the regions available for new clusters and nodes.

Sort order: Distance (based on client IP address)

Authorizations:
Bearer
query Parameters
provider
string
Default: "CLOUD_PROVIDER_UNSPECIFIED"
Enum: "CLOUD_PROVIDER_UNSPECIFIED" "GCP" "AWS"

Optional CloudProvider for filtering.

  • GCP: The Google Cloud Platform cloud provider.
  • AWS: The Amazon Web Services cloud provider.
serverless
boolean
Default: "false"

Optional filter to only show regions available for serverless clusters.

pagination.start_key
string
pagination.direction
string
Default: "PAGE_DIRECTION_NEXT"
Enum: "PAGE_DIRECTION_NEXT" "PAGE_DIRECTION_LAST"
pagination.limit
integer <int32>
pagination.time
string <date-time>
pagination.order
string
Default: "ASC"
Enum: "ASC" "DESC"
  • DESC: Sort in descending order. The default order is ascending.

Responses

Request samples 

curl --request GET \
  --url 'https://cockroachlabs.cloud/api/v1/clusters/available-regions?provider=SOME_STRING_VALUE&serverless=SOME_BOOLEAN_VALUE&pagination.start_key=SOME_STRING_VALUE&pagination.direction=SOME_STRING_VALUE&pagination.limit=SOME_INTEGER_VALUE&pagination.time=SOME_STRING_VALUE&pagination.order=SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "regions": [
    ],
  • "pagination": {
    }
}

Get extended information about a cluster.

Authorizations:
Bearer
path Parameters
cluster_id
required
string

Responses

Request samples 

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

Response samples

Content type
application/json
{
  • "id": "35c4abb2-bb66-46d7-afed-25ebef5ed2aa",
  • "name": "example-cluster",
  • "cockroach_version": "v21.2.4",
  • "plan": "SERVERLESS",
  • "cloud_provider": "GCP",
  • "account_id": "",
  • "state": "CREATED",
  • "creator_id": "7cde0cd9-0d8a-4008-8f90-45092ce8afc1",
  • "operation_status": "CLUSTER_STATUS_UNSPECIFIED",
  • "config": {
    },
  • "regions": [
    ],
  • "created_at": "2022-03-22T20:23:11.285067Z",
  • "updated_at": "2022-03-22T20:23:11.879593Z",
  • "deleted_at": null
}

Delete a cluster and all of its data.

Authorizations:
Bearer
path Parameters
cluster_id
required
string

Responses

Request samples 

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

Response samples

Content type
application/json
{
  • "id": "35c4abb2-bb66-46d7-afed-25ebef5ed2aa",
  • "name": "example-cluster",
  • "cockroach_version": "v21.2.4",
  • "plan": "SERVERLESS",
  • "cloud_provider": "GCP",
  • "account_id": "",
  • "state": "CREATED",
  • "creator_id": "7cde0cd9-0d8a-4008-8f90-45092ce8afc1",
  • "operation_status": "CLUSTER_STATUS_UNSPECIFIED",
  • "config": {
    },
  • "regions": [
    ],
  • "created_at": "2022-03-22T20:23:11.285067Z",
  • "updated_at": "2022-03-22T20:23:11.879593Z",
  • "deleted_at": null
}

Scale or edit a cluster.

Authorizations:
Bearer
path Parameters
cluster_id
required
string
query Parameters
field_mask
string
Request Body schema: application/json
object (DedicatedClusterUpdateSpecification)
object (ServerlessClusterUpdateSpecification)

Responses

Request samples

Content type
application/json
{
  • "dedicated": {
    }
}

Response samples

Content type
application/json
{
  • "id": "35c4abb2-bb66-46d7-afed-25ebef5ed2aa",
  • "name": "example-cluster",
  • "cockroach_version": "v21.2.4",
  • "plan": "SERVERLESS",
  • "cloud_provider": "GCP",
  • "account_id": "",
  • "state": "CREATED",
  • "creator_id": "7cde0cd9-0d8a-4008-8f90-45092ce8afc1",
  • "operation_status": "CLUSTER_STATUS_UNSPECIFIED",
  • "config": {
    },
  • "regions": [
    ],
  • "created_at": "2022-03-22T20:23:11.285067Z",
  • "updated_at": "2022-03-22T20:23:11.879593Z",
  • "deleted_at": null
}

Get CMEK-related information for a cluster.

Authorizations:
Bearer
path Parameters
cluster_id
required
string

Responses

Request samples 

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

Response samples

Content type
application/json
{
  • "status": "UNKNOWN_STATUS",
  • "region_infos": [
    ]
}

Enable CMEK for a cluster.

Authorizations:
Bearer
path Parameters
cluster_id
required
string
Request Body schema: application/json
required
Array of objects (CMEKRegionSpecification)

Responses

Request samples

Content type
application/json
{
  • "region_specs": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "UNKNOWN_STATUS",
  • "region_infos": [
    ]
}

Update the CMEK-related status for a cluster.

Authorizations:
Bearer
path Parameters
cluster_id
required
string
Request Body schema: application/json
action
required
string (CMEKCustomerAction)
Default: "UNKNOWN_ACTION"
Enum: "UNKNOWN_ACTION" "REVOKE"

CMEKCustomerAction enumerates the actions a customer can take on a cluster that has been enabled for CMEK.

Responses

Request samples

Content type
application/json
{
  • "action": "REVOKE"
}

Response samples

Content type
application/json
{
  • "status": "UNKNOWN_STATUS",
  • "region_infos": [
    ]
}

Get the IP allowlist and propagation status for a cluster.

Sort order: CIDR address

Authorizations:
Bearer
path Parameters
cluster_id
required
string
query Parameters
pagination.start_key
string
pagination.direction
string
Default: "PAGE_DIRECTION_NEXT"
Enum: "PAGE_DIRECTION_NEXT" "PAGE_DIRECTION_LAST"
pagination.limit
integer <int32>
pagination.time
string <date-time>
pagination.order
string
Default: "ASC"
Enum: "ASC" "DESC"
  • DESC: Sort in descending order. The default order is ascending.

Responses

Request samples 

curl --request GET \
  --url 'https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/networking/allowlist?pagination.start_key=SOME_STRING_VALUE&pagination.direction=SOME_STRING_VALUE&pagination.limit=SOME_INTEGER_VALUE&pagination.time=SOME_STRING_VALUE&pagination.order=SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "allowlist": [
    ],
  • "propagating": true,
  • "pagination": {
    }
}

Add a new CIDR address to the IP allowlist.

Authorizations:
Bearer
path Parameters
cluster_id
required
string
Request Body schema: application/json
cidr_ip
required
string
cidr_mask
required
integer <int32>
ui
required
boolean
sql
required
boolean
name
string

Responses

Request samples

Content type
application/json
{
  • "cidr_ip": "192.168.1.1",
  • "cidr_mask": 32,
  • "ui": true,
  • "sql": true,
  • "name": "Example"
}

Response samples

Content type
application/json
{
  • "cidr_ip": "192.168.1.1",
  • "cidr_mask": 32,
  • "ui": true,
  • "sql": true,
  • "name": "Example"
}

Delete an IP allowlist entry.

Authorizations:
Bearer
path Parameters
cluster_id
required
string
cidr_ip
required
string
cidr_mask
required
integer <int32>

Responses

Request samples 

curl --request DELETE \
  --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/networking/allowlist/{cidr_ip}/{cidr_mask} \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "cidr_ip": "192.168.1.1",
  • "cidr_mask": 32,
  • "ui": true,
  • "sql": true,
  • "name": "Example"
}

Add a new CIDR address to the IP allowlist.

Authorizations:
Bearer
path Parameters
cluster_id
required
string
entry.cidr_ip
required
string
entry.cidr_mask
required
integer <int32>
Request Body schema: application/json
cidr_ip
required
string
cidr_mask
required
integer <int32>
ui
required
boolean
sql
required
boolean
name
string

Responses

Request samples

Content type
application/json
{
  • "cidr_ip": "192.168.1.1",
  • "cidr_mask": 32,
  • "ui": true,
  • "sql": true,
  • "name": "Example"
}

Response samples

Content type
application/json
{
  • "cidr_ip": "192.168.1.1",
  • "cidr_mask": 32,
  • "ui": true,
  • "sql": true,
  • "name": "Example"
}

Update an IP allowlist entry.

Authorizations:
Bearer
path Parameters
cluster_id
required
string
entry.cidr_ip
required
string
entry.cidr_mask
required
integer <int32>
query Parameters
field_mask
string
Request Body schema: application/json
cidr_ip
required
string
cidr_mask
required
integer <int32>
ui
required
boolean
sql
required
boolean
name
string

Responses

Request samples

Content type
application/json
{
  • "cidr_ip": "192.168.1.1",
  • "cidr_mask": 32,
  • "ui": true,
  • "sql": true,
  • "name": "Example"
}

Response samples

Content type
application/json
{
  • "cidr_ip": "192.168.1.1",
  • "cidr_mask": 32,
  • "ui": true,
  • "sql": true,
  • "name": "Example"
}

List nodes for a cluster.

Sort order: Region name, node name

Authorizations:
Bearer
path Parameters
cluster_id
required
string
query Parameters
region_name
string

Optional filter to limit response to a single region.

pagination.start_key
string
pagination.direction
string
Default: "PAGE_DIRECTION_NEXT"
Enum: "PAGE_DIRECTION_NEXT" "PAGE_DIRECTION_LAST"
pagination.limit
integer <int32>
pagination.time
string <date-time>
pagination.order
string
Default: "ASC"
Enum: "ASC" "DESC"
  • DESC: Sort in descending order. The default order is ascending.

Responses

Request samples 

curl --request GET \
  --url 'https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/nodes?region_name=SOME_STRING_VALUE&pagination.start_key=SOME_STRING_VALUE&pagination.direction=SOME_STRING_VALUE&pagination.limit=SOME_INTEGER_VALUE&pagination.time=SOME_STRING_VALUE&pagination.order=SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "nodes": [
    ],
  • "pagination": {
    }
}

List SQL users for a cluster.

Sort order: Username

Authorizations:
Bearer
path Parameters
cluster_id
required
string
query Parameters
pagination.start_key
string
pagination.direction
string
Default: "PAGE_DIRECTION_NEXT"
Enum: "PAGE_DIRECTION_NEXT" "PAGE_DIRECTION_LAST"
pagination.limit
integer <int32>
pagination.time
string <date-time>
pagination.order
string
Default: "ASC"
Enum: "ASC" "DESC"
  • DESC: Sort in descending order. The default order is ascending.

Responses

Request samples 

curl --request GET \
  --url 'https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/sql-users?pagination.start_key=SOME_STRING_VALUE&pagination.direction=SOME_STRING_VALUE&pagination.limit=SOME_INTEGER_VALUE&pagination.time=SOME_STRING_VALUE&pagination.order=SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "users": [
    ],
  • "pagination": {
    }
}

Create a new SQL user.

Authorizations:
Bearer
path Parameters
cluster_id
required
string
Request Body schema: application/json
name
required
string
password
required
string

Responses

Request samples

Content type
application/json
{
  • "name": "example_username",
  • "password": "example_password"
}

Response samples

Content type
application/json
{
  • "name": "string"
}

Delete a SQL user.

Authorizations:
Bearer
path Parameters
cluster_id
required
string
name
required
string

Responses

Request samples 

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

Response samples

Content type
application/json
{
  • "name": "string"
}

Update a SQL user's password.

Authorizations:
Bearer
path Parameters
cluster_id
required
string
name
required
string
Request Body schema: application/json
password
required
string

Responses

Request samples

Content type
application/json
{
  • "password": "example_new_password"
}

Response samples

Content type
application/json
{
  • "name": "string"
}