{ "openapi": "3.0.0", "info": { "title": "CockroachDB Cloud API", "description": "This is an early access, experimental version of the Cloud API. The interface and output is subject to change, and there may be bugs.\n\n# Authentication\n\n", "version": "2022-03-31", "contact": { "name": "Cockroach Labs Support", "url": "https://support.cockroachlabs.com", "email": "support@cockroachlabs.com" } }, "tags": [ { "name": "CockroachCloud" } ], "paths": { "/api/v1/clusters": { "get": { "summary": "List clusters owned by an organization.", "description": "Sort order: Cluster name", "operationId": "CockroachCloud_ListClusters", "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListClustersResponse" } } } }, "400": { "description": "Returned when a request field is invalid.", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Returned when the token bearer cannot be authenticated.", "content": { "application/json": { "schema": {} } } }, "403": { "description": "Returned when the user does not have permission to access the resource.", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Returned when the resource does not exist.", "content": { "application/json": { "schema": {} } } }, "5XX": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "parameters": [ { "name": "show_inactive", "description": "If `true`, show clusters that have been deleted or failed to initialize.", "in": "query", "required": false, "schema": { "type": "boolean", "default": "false" } }, { "name": "pagination.start_key", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "pagination.direction", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "PAGE_DIRECTION_NEXT", "PAGE_DIRECTION_LAST" ], "default": "PAGE_DIRECTION_NEXT" } }, { "name": "pagination.limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32" } }, { "name": "pagination.time", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "pagination.order", "description": " - DESC: Sort in descending order. The default order is ascending.", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "ASC" } } ], "tags": [ "CockroachCloud" ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --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' \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] }, "post": { "summary": "Create and initialize a new cluster.", "operationId": "CockroachCloud_CreateCluster", "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cluster" } } } }, "400": { "description": "Returned when a request field is invalid.", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Returned when the token bearer cannot be authenticated.", "content": { "application/json": { "schema": {} } } }, "403": { "description": "Returned when the user does not have permission to access the resource.", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Returned when the resource does not exist.", "content": { "application/json": { "schema": {} } } }, "5XX": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateClusterRequest" } } }, "required": true }, "tags": [ "CockroachCloud" ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request POST \\\n --url https://cockroachlabs.cloud/api/v1/clusters \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --header 'content-type: application/json' \\\n --data '{\"name\":\"test-cluster\",\"provider\":\"GCP\",\"spec\":{\"serverless\":{\"regions\":[\"us-central1\"],\"spend_limit\":0}}}'" } ] } }, "/api/v1/clusters/available-regions": { "get": { "summary": "List the regions available for new clusters and nodes.", "description": "Sort order: Distance (based on client IP address)", "operationId": "CockroachCloud_ListAvailableRegions", "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAvailableRegionsResponse" } } } }, "400": { "description": "Returned when a request field is invalid.", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Returned when the token bearer cannot be authenticated.", "content": { "application/json": { "schema": {} } } }, "403": { "description": "Returned when the user does not have permission to access the resource.", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Returned when the resource does not exist.", "content": { "application/json": { "schema": {} } } }, "5XX": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "parameters": [ { "name": "provider", "description": "Optional CloudProvider for filtering.\n\n - GCP: The Google Cloud Platform cloud provider.\n - AWS: The Amazon Web Services cloud provider.", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "CLOUD_PROVIDER_UNSPECIFIED", "GCP", "AWS" ], "default": "CLOUD_PROVIDER_UNSPECIFIED" } }, { "name": "serverless", "description": "Optional filter to only show regions available for serverless clusters.", "in": "query", "required": false, "schema": { "type": "boolean", "default": "false" } }, { "name": "pagination.start_key", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "pagination.direction", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "PAGE_DIRECTION_NEXT", "PAGE_DIRECTION_LAST" ], "default": "PAGE_DIRECTION_NEXT" } }, { "name": "pagination.limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32" } }, { "name": "pagination.time", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "pagination.order", "description": " - DESC: Sort in descending order. The default order is ascending.", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "ASC" } } ], "tags": [ "CockroachCloud" ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --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' \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] } }, "/api/v1/clusters/{cluster_id}": { "get": { "summary": "Get extended information about a cluster.", "operationId": "CockroachCloud_GetCluster", "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cluster" } } } }, "400": { "description": "Returned when a request field is invalid.", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Returned when the token bearer cannot be authenticated.", "content": { "application/json": { "schema": {} } } }, "403": { "description": "Returned when the user does not have permission to access the resource.", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Returned when the resource does not exist.", "content": { "application/json": { "schema": {} } } }, "5XX": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "tags": [ "CockroachCloud" ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id} \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] }, "delete": { "summary": "Delete a cluster and all of its data.", "operationId": "CockroachCloud_DeleteCluster", "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cluster" } } } }, "400": { "description": "Returned when a request field is invalid.", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Returned when the token bearer cannot be authenticated.", "content": { "application/json": { "schema": {} } } }, "403": { "description": "Returned when the user does not have permission to access the resource.", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Returned when the resource does not exist.", "content": { "application/json": { "schema": {} } } }, "5XX": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "tags": [ "CockroachCloud" ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request DELETE \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id} \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] }, "patch": { "summary": "Scale or edit a cluster.", "operationId": "CockroachCloud_UpdateCluster", "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cluster" } } } }, "400": { "description": "Returned when a request field is invalid.", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Returned when the token bearer cannot be authenticated.", "content": { "application/json": { "schema": {} } } }, "403": { "description": "Returned when the user does not have permission to access the resource.", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Returned when the resource does not exist.", "content": { "application/json": { "schema": {} } } }, "5XX": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "field_mask", "in": "query", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateClusterSpecification" } } }, "required": true }, "tags": [ "CockroachCloud" ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request PATCH \\\n --url 'https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}?field_mask=SOME_STRING_VALUE' \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --header 'content-type: application/json' \\\n --data '{\"dedicated\":{\"region_nodes\":{\"us-west1\":3,\"us-central1\":5},\"hardware\":{\"machine_type\":\"n2-standard-8\"}}}'" } ] } }, "/api/v1/clusters/{cluster_id}/cmek": { "get": { "summary": "Get CMEK-related information for a cluster.", "operationId": "CockroachCloud_GetCMEKClusterInfo", "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CMEKClusterInfo" } } } }, "400": { "description": "Returned when a request field is invalid.", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Returned when the token bearer cannot be authenticated.", "content": { "application/json": { "schema": {} } } }, "403": { "description": "Returned when the user does not have permission to access the resource.", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Returned when the resource does not exist.", "content": { "application/json": { "schema": {} } } }, "5XX": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "tags": [ "CockroachCloud" ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/cmek \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] }, "post": { "summary": "Enable CMEK for a cluster.", "operationId": "CockroachCloud_EnableCMEK", "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CMEKClusterInfo" } } } }, "400": { "description": "Returned when a request field is invalid.", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Returned when the token bearer cannot be authenticated.", "content": { "application/json": { "schema": {} } } }, "403": { "description": "Returned when the user does not have permission to access the resource.", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Returned when the resource does not exist.", "content": { "application/json": { "schema": {} } } }, "5XX": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "example": { "region_specs": [ { "region": "us-central1", "key_spec": { "type": "AWS_KMS", "uri": "arn:aws:kms:us-west-2:111122223333:key/id-of-kms-key", "auth_principal": "arn:aws:iam::account:role/role-name-with-path" } } ] }, "properties": { "region_specs": { "type": "array", "items": { "$ref": "#/components/schemas/CMEKRegionSpecification" } } }, "title": "CMEKClusterSpecification", "required": [ "region_specs" ] } } }, "required": true }, "tags": [ "CockroachCloud" ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request POST \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/cmek \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --header 'content-type: application/json' \\\n --data '{\"region_specs\":[{\"region\":\"us-central1\",\"key_spec\":{\"type\":\"AWS_KMS\",\"uri\":\"arn:aws:kms:us-west-2:111122223333:key/id-of-kms-key\",\"auth_principal\":\"arn:aws:iam::account:role/role-name-with-path\"}}]}'" } ] }, "patch": { "summary": "Update the CMEK-related status for a cluster.", "operationId": "CockroachCloud_UpdateCMEKStatus", "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CMEKClusterInfo" } } } }, "400": { "description": "Returned when a request field is invalid.", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Returned when the token bearer cannot be authenticated.", "content": { "application/json": { "schema": {} } } }, "403": { "description": "Returned when the user does not have permission to access the resource.", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Returned when the resource does not exist.", "content": { "application/json": { "schema": {} } } }, "5XX": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "example": { "action": "REVOKE" }, "properties": { "action": { "$ref": "#/components/schemas/CMEKCustomerAction" } }, "title": "UpdateCMEKStatusRequest", "required": [ "action" ] } } }, "required": true }, "tags": [ "CockroachCloud" ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request PATCH \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/cmek \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --header 'content-type: application/json' \\\n --data '{\"action\":\"REVOKE\"}'" } ] } }, "/api/v1/clusters/{cluster_id}/networking/allowlist": { "get": { "summary": "Get the IP allowlist and propagation status for a cluster.", "description": "Sort order: CIDR address", "operationId": "CockroachCloud_ListAllowlistEntries", "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAllowlistEntriesResponse" } } } }, "400": { "description": "Returned when a request field is invalid.", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Returned when the token bearer cannot be authenticated.", "content": { "application/json": { "schema": {} } } }, "403": { "description": "Returned when the user does not have permission to access the resource.", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Returned when the resource does not exist.", "content": { "application/json": { "schema": {} } } }, "5XX": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "pagination.start_key", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "pagination.direction", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "PAGE_DIRECTION_NEXT", "PAGE_DIRECTION_LAST" ], "default": "PAGE_DIRECTION_NEXT" } }, { "name": "pagination.limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32" } }, { "name": "pagination.time", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "pagination.order", "description": " - DESC: Sort in descending order. The default order is ascending.", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "ASC" } } ], "tags": [ "CockroachCloud" ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --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' \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] }, "post": { "summary": "Add a new CIDR address to the IP allowlist.", "operationId": "CockroachCloud_AddAllowlistEntry", "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AllowlistEntry" } } } }, "400": { "description": "Returned when a request field is invalid.", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Returned when the token bearer cannot be authenticated.", "content": { "application/json": { "schema": {} } } }, "403": { "description": "Returned when the user does not have permission to access the resource.", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Returned when the resource does not exist.", "content": { "application/json": { "schema": {} } } }, "5XX": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AllowlistEntry" } } }, "required": true }, "tags": [ "CockroachCloud" ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request POST \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/networking/allowlist \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --data '{\"cidr_ip\":\"192.168.1.1\",\"cidr_mask\":32,\"ui\":true,\"sql\":true,\"name\":\"Example\"}'" } ] } }, "/api/v1/clusters/{cluster_id}/networking/allowlist/{cidr_ip}/{cidr_mask}": { "delete": { "summary": "Delete an IP allowlist entry.", "operationId": "CockroachCloud_DeleteAllowlistEntry", "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AllowlistEntry" } } } }, "400": { "description": "Returned when a request field is invalid.", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Returned when the token bearer cannot be authenticated.", "content": { "application/json": { "schema": {} } } }, "403": { "description": "Returned when the user does not have permission to access the resource.", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Returned when the resource does not exist.", "content": { "application/json": { "schema": {} } } }, "5XX": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "cidr_ip", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "cidr_mask", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "tags": [ "CockroachCloud" ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request DELETE \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/networking/allowlist/{cidr_ip}/{cidr_mask} \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] } }, "/api/v1/clusters/{cluster_id}/networking/allowlist/{entry.cidr_ip}/{entry.cidr_mask}": { "put": { "summary": "Add a new CIDR address to the IP allowlist.", "operationId": "CockroachCloud_AddAllowlistEntry2", "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AllowlistEntry" } } } }, "400": { "description": "Returned when a request field is invalid.", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Returned when the token bearer cannot be authenticated.", "content": { "application/json": { "schema": {} } } }, "403": { "description": "Returned when the user does not have permission to access the resource.", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Returned when the resource does not exist.", "content": { "application/json": { "schema": {} } } }, "5XX": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "entry.cidr_ip", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "entry.cidr_mask", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AllowlistEntry" } } }, "required": true }, "tags": [ "CockroachCloud" ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request PUT \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/networking/allowlist/{entry.cidr_ip}/{entry.cidr_mask} \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --data '{\"cidr_ip\":\"192.168.1.1\",\"cidr_mask\":32,\"ui\":true,\"sql\":true,\"name\":\"Example\"}'" } ] }, "patch": { "summary": "Update an IP allowlist entry.", "operationId": "CockroachCloud_UpdateAllowlistEntry", "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AllowlistEntry" } } } }, "400": { "description": "Returned when a request field is invalid.", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Returned when the token bearer cannot be authenticated.", "content": { "application/json": { "schema": {} } } }, "403": { "description": "Returned when the user does not have permission to access the resource.", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Returned when the resource does not exist.", "content": { "application/json": { "schema": {} } } }, "5XX": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "entry.cidr_ip", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "entry.cidr_mask", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "field_mask", "in": "query", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AllowlistEntry" } } }, "required": true }, "tags": [ "CockroachCloud" ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request PATCH \\\n --url 'https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/networking/allowlist/{entry.cidr_ip}/{entry.cidr_mask}?field_mask=SOME_STRING_VALUE' \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --data '{\"cidr_ip\":\"192.168.1.1\",\"cidr_mask\":32,\"ui\":true,\"sql\":true,\"name\":\"Example\"}'" } ] } }, "/api/v1/clusters/{cluster_id}/nodes": { "get": { "summary": "List nodes for a cluster.", "description": "Sort order: Region name, node name", "operationId": "CockroachCloud_ListClusterNodes", "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListClusterNodesResponse" } } } }, "400": { "description": "Returned when a request field is invalid.", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Returned when the token bearer cannot be authenticated.", "content": { "application/json": { "schema": {} } } }, "403": { "description": "Returned when the user does not have permission to access the resource.", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Returned when the resource does not exist.", "content": { "application/json": { "schema": {} } } }, "5XX": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "region_name", "description": "Optional filter to limit response to a single region.", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "pagination.start_key", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "pagination.direction", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "PAGE_DIRECTION_NEXT", "PAGE_DIRECTION_LAST" ], "default": "PAGE_DIRECTION_NEXT" } }, { "name": "pagination.limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32" } }, { "name": "pagination.time", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "pagination.order", "description": " - DESC: Sort in descending order. The default order is ascending.", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "ASC" } } ], "tags": [ "CockroachCloud" ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --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' \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] } }, "/api/v1/clusters/{cluster_id}/sql-users": { "get": { "summary": "List SQL users for a cluster.", "description": "Sort order: Username", "operationId": "CockroachCloud_ListSQLUsers", "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSQLUsersResponse" } } } }, "400": { "description": "Returned when a request field is invalid.", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Returned when the token bearer cannot be authenticated.", "content": { "application/json": { "schema": {} } } }, "403": { "description": "Returned when the user does not have permission to access the resource.", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Returned when the resource does not exist.", "content": { "application/json": { "schema": {} } } }, "5XX": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "pagination.start_key", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "pagination.direction", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "PAGE_DIRECTION_NEXT", "PAGE_DIRECTION_LAST" ], "default": "PAGE_DIRECTION_NEXT" } }, { "name": "pagination.limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32" } }, { "name": "pagination.time", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "pagination.order", "description": " - DESC: Sort in descending order. The default order is ascending.", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "ASC" } } ], "tags": [ "CockroachCloud" ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --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' \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] }, "post": { "summary": "Create a new SQL user.", "operationId": "CockroachCloud_CreateSQLUser", "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SQLUser" } } } }, "400": { "description": "Returned when a request field is invalid.", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Returned when the token bearer cannot be authenticated.", "content": { "application/json": { "schema": {} } } }, "403": { "description": "Returned when the user does not have permission to access the resource.", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Returned when the resource does not exist.", "content": { "application/json": { "schema": {} } } }, "5XX": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "example": { "name": "example_username", "password": "example_password" }, "properties": { "name": { "type": "string" }, "password": { "type": "string" } }, "title": "CreateSQLUserRequest", "required": [ "name", "password" ] } } }, "required": true }, "tags": [ "CockroachCloud" ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request POST \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/sql-users \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --header 'content-type: application/json' \\\n --data '{\"name\":\"example_username\",\"password\":\"example_password\"}'" } ] } }, "/api/v1/clusters/{cluster_id}/sql-users/{name}": { "delete": { "summary": "Delete a SQL user.", "operationId": "CockroachCloud_DeleteSQLUser", "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SQLUser" } } } }, "400": { "description": "Returned when a request field is invalid.", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Returned when the token bearer cannot be authenticated.", "content": { "application/json": { "schema": {} } } }, "403": { "description": "Returned when the user does not have permission to access the resource.", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Returned when the resource does not exist.", "content": { "application/json": { "schema": {} } } }, "5XX": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "tags": [ "CockroachCloud" ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request DELETE \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/sql-users/{name} \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] } }, "/api/v1/clusters/{cluster_id}/sql-users/{name}/password": { "put": { "summary": "Update a SQL user's password.", "operationId": "CockroachCloud_UpdateSQLUserPassword", "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SQLUser" } } } }, "400": { "description": "Returned when a request field is invalid.", "content": { "application/json": { "schema": {} } } }, "401": { "description": "Returned when the token bearer cannot be authenticated.", "content": { "application/json": { "schema": {} } } }, "403": { "description": "Returned when the user does not have permission to access the resource.", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Returned when the resource does not exist.", "content": { "application/json": { "schema": {} } } }, "5XX": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "example": { "password": "example_new_password" }, "properties": { "password": { "type": "string" } }, "title": "UpdateSQLUserPasswordRequest", "required": [ "password" ] } } }, "required": true }, "tags": [ "CockroachCloud" ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request PUT \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/sql-users/{name}/password \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --header 'content-type: application/json' \\\n --data '{\"password\":\"example_new_password\"}'" } ] } } }, "security": [ { "Bearer": [] } ], "externalDocs": { "description": "Use the CockroachDB Cloud API", "url": "https://www.cockroachlabs.com/docs/cockroachcloud/cloud-api" }, "servers": [ { "url": "https://cockroachlabs.cloud" } ], "components": { "requestBodies": { "AllowlistEntry": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AllowlistEntry" } } }, "required": true } }, "securitySchemes": { "Bearer": { "type": "http", "scheme": "bearer" } }, "schemas": { "AllowlistEntry": { "type": "object", "example": { "cidr_ip": "192.168.1.1", "cidr_mask": 32, "ui": true, "sql": true, "name": "Example" }, "properties": { "cidr_ip": { "type": "string" }, "cidr_mask": { "type": "integer", "format": "int32" }, "ui": { "type": "boolean" }, "sql": { "type": "boolean" }, "name": { "type": "string" } }, "title": "AllowlistEntry", "required": [ "cidr_ip", "cidr_mask", "ui", "sql" ] }, "Any": { "type": "object", "properties": { "@type": { "type": "string" } }, "additionalProperties": {} }, "CMEKClusterInfo": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/CMEKStatus" }, "region_infos": { "type": "array", "items": { "$ref": "#/components/schemas/CMEKRegionInfo" } } }, "description": "CMEKClusterInfo contains the status of CMEK across an entire cluster,\nincluding within each one its regions." }, "CMEKCustomerAction": { "type": "string", "enum": [ "UNKNOWN_ACTION", "REVOKE" ], "default": "UNKNOWN_ACTION", "description": "CMEKCustomerAction enumerates the actions a customer can take on a cluster\nthat has been enabled for CMEK." }, "CMEKKeyInfo": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/CMEKStatus" }, "user_message": { "type": "string" }, "spec": { "$ref": "#/components/schemas/CMEKKeySpecification" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "description": "CMEKKeyInfo contains the status of a customer-provided key alongside the\nspecification." }, "CMEKKeySpecification": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/CMEKKeyType" }, "uri": { "type": "string" }, "auth_principal": { "type": "string" } }, "description": "CMEKKeySpecification contains all the details necessary to use a customer-provided\nencryption key. This involves the type/location of the key and the principal\nto authenticate as when accessing it." }, "CMEKKeyType": { "type": "string", "enum": [ "UNKNOWN_KEY_TYPE", "AWS_KMS", "GCP_CLOUD_KMS" ], "default": "UNKNOWN_KEY_TYPE", "description": "CMEKKeyType enumerates types of customer-managed keys.\n\n - UNKNOWN_KEY_TYPE: UNKNOWN should never be used; if it is used, it indicates a bug." }, "CMEKRegionInfo": { "type": "object", "properties": { "region": { "type": "string" }, "key_infos": { "type": "array", "items": { "$ref": "#/components/schemas/CMEKKeyInfo" } } }, "description": "CMEKRegionInfo contains the status of CMEK within a region. This includes\ncurrent and past key specifications used within the region, as well as the\nstatus of those specifications." }, "CMEKRegionSpecification": { "type": "object", "properties": { "region": { "type": "string" }, "key_spec": { "$ref": "#/components/schemas/CMEKKeySpecification" } }, "description": "CMEKRegionSpecification declares the customer-provided key specification that\nshould be used in a given region." }, "CMEKStatus": { "type": "string", "enum": [ "UNKNOWN_STATUS", "DISABLED", "DISABLING", "DISABLE_FAILED", "ENABLED", "ENABLING", "ENABLE_FAILED", "REVOKED", "REVOKING", "REVOKE_FAILED" ], "default": "UNKNOWN_STATUS", "description": "CMEKStatus describes the current status of CMEK for an entire CRDB cluster\nor a key within a region.\n\n - UNKNOWN_STATUS: UNKNOWN should never be used; if it is used, it indicates a bug.\n - DISABLED: DISABLED corresponds to the state of a cluster or region-level key\nwhen CMEK has finished being disabled. By default, CMEK will be disabled\nfor new clusters.\n - DISABLING: DISABLED corresponds to the state of a cluster or region-level key\nwhen CMEK is in the process of being disabled.\n - DISABLE_FAILED: DISABLE_FAILED corresponds to the state of a cluster or region-level key\nwhen CMEK has failed to be disabled.\n - ENABLED: ENABLED corresponds to the state of a cluster or region-level key\nwhen CMEK is enabled.\n - ENABLING: ENABLING corresponds to the state of a cluster or region-level key\nwhen CMEK is in the process of being enabled.\n - ENABLE_FAILED: ENABLE_FAILED corresponds to the state of a cluster or region-level key\nwhen CMEK has failed to be enabled.\n - REVOKED: REVOKED corresponds to the state of a cluster or region-level key\nwhen the customer has revoked CockroachLab's permissions for their key.\n - REVOKING: REVOKING corresponds to the state of a cluster or region-level key\nwhen CMEK is in the process of being revoked.\n - REVOKE_FAILED: REVOKE_FAILED corresponds to the state of a cluster or region-level key\nwhen CMEK has failed to be revoked." }, "CloudProviderRegion": { "type": "object", "properties": { "name": { "type": "string" }, "location": { "type": "string" }, "provider": { "$ref": "#/components/schemas/api.CloudProvider" }, "serverless": { "type": "boolean" }, "distance": { "type": "number", "format": "float", "title": "Distance in miles, based on client IP address" } }, "required": [ "name", "location", "provider", "serverless", "distance" ] }, "Cluster": { "type": "object", "example": { "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": { "serverless": { "spend_limit": 0, "routing_id": "example-cluster-1533" } }, "regions": [ { "name": "us-central1", "sql_dns": "free-tier7.gcp-us-central1.crdb.io", "ui_dns": "", "node_count": 0 } ], "created_at": "2022-03-22T20:23:11.285067Z", "updated_at": "2022-03-22T20:23:11.879593Z", "deleted_at": null }, "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "cockroach_version": { "type": "string" }, "plan": { "$ref": "#/components/schemas/Plan" }, "cloud_provider": { "$ref": "#/components/schemas/api.CloudProvider" }, "account_id": { "type": "string" }, "state": { "$ref": "#/components/schemas/ClusterStateType" }, "creator_id": { "type": "string" }, "operation_status": { "$ref": "#/components/schemas/ClusterStatusType" }, "config": { "$ref": "#/components/schemas/ClusterConfig" }, "regions": { "type": "array", "items": { "$ref": "#/components/schemas/Region" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "deleted_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "cockroach_version", "plan", "cloud_provider", "state", "creator_id", "operation_status", "config", "regions" ] }, "ClusterConfig": { "type": "object", "properties": { "dedicated": { "$ref": "#/components/schemas/DedicatedHardwareConfig" }, "serverless": { "$ref": "#/components/schemas/ServerlessClusterConfig" } } }, "ClusterStateType": { "type": "string", "enum": [ "CLUSTER_STATE_UNSPECIFIED", "CREATING", "CREATED", "CREATION_FAILED", "DELETED", "LOCKED" ], "default": "CLUSTER_STATE_UNSPECIFIED", "description": " - LOCKED: An exclusive operation is being performed on this cluster.\nOther operations should not proceed if they did not set a cluster into the LOCKED state." }, "ClusterStatusType": { "type": "string", "enum": [ "CLUSTER_STATUS_UNSPECIFIED", "CRDB_MAJOR_UPGRADE_RUNNING", "CRDB_MAJOR_UPGRADE_FAILED", "CRDB_MAJOR_ROLLBACK_RUNNING", "CRDB_MAJOR_ROLLBACK_FAILED", "CRDB_PATCH_RUNNING", "CRDB_PATCH_FAILED", "CRDB_SCALE_RUNNING", "CRDB_SCALE_FAILED", "MAINTENANCE_RUNNING", "CRDB_INSTANCE_UPDATE_RUNNING", "CRDB_INSTANCE_UPDATE_FAILED", "CRDB_EDIT_CLUSTER_RUNNING", "CRDB_EDIT_CLUSTER_FAILED", "CRDB_CMEK_OPERATION_RUNNING", "CRDB_CMEK_OPERATION_FAILED", "TENANT_RESTORE_RUNNING", "TENANT_RESTORE_FAILED" ], "default": "CLUSTER_STATUS_UNSPECIFIED" }, "CreateClusterRequest": { "type": "object", "example": { "name": "test-cluster", "provider": "GCP", "spec": { "serverless": { "regions": [ "us-central1" ], "spend_limit": 0 } } }, "properties": { "name": { "type": "string" }, "provider": { "$ref": "#/components/schemas/api.CloudProvider" }, "spec": { "$ref": "#/components/schemas/CreateClusterSpecification" } }, "title": "CreateClusterRequest", "required": [ "name", "provider", "spec" ] }, "CreateClusterSpecification": { "type": "object", "properties": { "dedicated": { "$ref": "#/components/schemas/DedicatedClusterCreateSpecification" }, "serverless": { "$ref": "#/components/schemas/ServerlessClusterCreateSpecification" } } }, "DedicatedClusterCreateSpecification": { "type": "object", "properties": { "region_nodes": { "type": "object", "additionalProperties": { "type": "integer", "format": "int32" }, "description": "Region keys should match the cloud provider's zone code.\nFor example, for Oregon, set region_name to \"us-west2\" for\nGCP and \"us-west-2\" for AWS. Values represent the node count." }, "hardware": { "$ref": "#/components/schemas/DedicatedHardwareCreateSpecification" }, "cockroach_version": { "type": "string", "description": "The CockroachDB version for the cluster. The current version\nis used if omitted." } }, "required": [ "region_nodes", "hardware" ] }, "DedicatedClusterUpdateSpecification": { "type": "object", "properties": { "region_nodes": { "type": "object", "additionalProperties": { "type": "integer", "format": "int32" }, "description": "Region keys should match the cloud provider's zone code.\nFor example, for Oregon, set region_name to \"us-west2\" for\nGCP and \"us-west-2\" for AWS. Values represent the node count." }, "hardware": { "$ref": "#/components/schemas/DedicatedHardwareUpdateSpecification" } } }, "DedicatedHardwareConfig": { "type": "object", "properties": { "machine_type": { "type": "string", "description": "MachineType is the machine type identifier within the given cloud\nprovider, ex. m5.xlarge, n2-standard-4." }, "num_virtual_cpus": { "type": "integer", "format": "int32", "description": "NumVirtualCPUs is the number of virtual CPUs per node in the cluster." }, "storage_gib": { "type": "integer", "format": "int32", "description": "StorageGiB is the number of storage GiB per node in the cluster." }, "memory_gib": { "type": "number", "format": "float", "description": "MemoryGiB is the memory GiB per node in the cluster." }, "disk_iops": { "type": "integer", "format": "int32", "description": "DiskIOPs is the number of disk I/O operations per second that are\npermitted on each node in the cluster. Zero indicates the cloud\nprovider-specific default." } }, "required": [ "machine_type", "num_virtual_cpus", "storage_gib", "memory_gib", "disk_iops" ] }, "DedicatedHardwareCreateSpecification": { "type": "object", "properties": { "machine_spec": { "$ref": "#/components/schemas/DedicatedMachineTypeSpecification" }, "storage_gib": { "type": "integer", "format": "int32", "description": "StorageGiB is the number of storage GiB per node in the cluster.\nZero indicates default to the lowest storage GiB available given machine specs." }, "disk_iops": { "type": "integer", "format": "int32", "description": "DiskIOPs is the number of disk I/O operations per second that are\npermitted on each node in the cluster. Zero indicates the cloud\nprovider-specific default. Only available for AWS clusters." } }, "required": [ "machine_spec", "storage_gib" ] }, "DedicatedHardwareUpdateSpecification": { "type": "object", "properties": { "machine_spec": { "$ref": "#/components/schemas/DedicatedMachineTypeSpecification" }, "storage_gib": { "type": "integer", "format": "int32", "description": "StorageGiB is the number of storage GiB per node in the cluster." }, "disk_iops": { "type": "integer", "format": "int32", "description": "DiskIOPs is the number of disk I/O operations per second that are\npermitted on each node in the cluster. Zero indicates the cloud\nprovider-specific default. Only available for AWS clusters." } } }, "DedicatedMachineTypeSpecification": { "type": "object", "properties": { "machine_type": { "type": "string", "description": "MachineType is the machine type identifier within the given cloud\nprovider, ex. m5.xlarge, n2-standard-4." }, "num_virtual_cpus": { "type": "integer", "format": "int32", "description": "NumVirtualCPUs may be used to automatically select a machine type\naccording to the desired number of vCPUs." } } }, "KeysetPaginationRequest": { "type": "object", "properties": { "start_key": { "type": "string" }, "direction": { "$ref": "#/components/schemas/PageDirection" }, "limit": { "type": "integer", "format": "int32" }, "time": { "type": "string", "format": "date-time" }, "order": { "$ref": "#/components/schemas/SortOrder" } } }, "KeysetPaginationResponse": { "type": "object", "properties": { "next": { "type": "string" }, "last": { "type": "string" }, "limit": { "type": "integer", "format": "int32" }, "time": { "type": "string", "format": "date-time" }, "order": { "$ref": "#/components/schemas/SortOrder" } } }, "ListAllowlistEntriesResponse": { "type": "object", "properties": { "allowlist": { "type": "array", "items": { "$ref": "#/components/schemas/AllowlistEntry" } }, "propagating": { "type": "boolean" }, "pagination": { "$ref": "#/components/schemas/KeysetPaginationResponse" } }, "title": "ListAllowlistEntriesResponse", "required": [ "allowlist", "propagating" ] }, "ListAvailableRegionsResponse": { "type": "object", "properties": { "regions": { "type": "array", "items": { "$ref": "#/components/schemas/CloudProviderRegion" } }, "pagination": { "$ref": "#/components/schemas/KeysetPaginationResponse" } }, "required": [ "regions" ] }, "ListClusterNodesResponse": { "type": "object", "properties": { "nodes": { "type": "array", "items": { "$ref": "#/components/schemas/Node" } }, "pagination": { "$ref": "#/components/schemas/KeysetPaginationResponse" } }, "required": [ "nodes" ] }, "ListClustersResponse": { "type": "object", "properties": { "clusters": { "type": "array", "items": { "$ref": "#/components/schemas/Cluster" } }, "pagination": { "$ref": "#/components/schemas/KeysetPaginationResponse" } }, "required": [ "clusters" ] }, "ListSQLUsersResponse": { "type": "object", "properties": { "users": { "type": "array", "items": { "$ref": "#/components/schemas/SQLUser" } }, "pagination": { "$ref": "#/components/schemas/KeysetPaginationResponse" } }, "required": [ "users" ] }, "Node": { "type": "object", "properties": { "name": { "type": "string" }, "region_name": { "type": "string" }, "status": { "$ref": "#/components/schemas/NodeStatus" } }, "required": [ "name", "region_name", "status" ] }, "NodeStatus": { "type": "string", "enum": [ "NODE_STATUS_UNSPECIFIED", "LIVE", "NOT_READY" ], "default": "NODE_STATUS_UNSPECIFIED" }, "PageDirection": { "type": "string", "enum": [ "PAGE_DIRECTION_NEXT", "PAGE_DIRECTION_LAST" ], "default": "PAGE_DIRECTION_NEXT" }, "Plan": { "type": "string", "enum": [ "PLAN_UNSPECIFIED", "DEDICATED", "CUSTOM", "SERVERLESS" ], "default": "PLAN_UNSPECIFIED", "description": " - DEDICATED: A paid plan that offers dedicated hardware in any location.\n - CUSTOM: A plan option that is used for clusters whose machine configs are not \nsupported in self-service. All INVOICE clusters are under this plan option.\n - SERVERLESS: A paid plan that runs on shared hardware and caps the users'\nmaximum monthly spending to a user-specified (possibly 0) amount." }, "Region": { "type": "object", "properties": { "name": { "type": "string" }, "sql_dns": { "type": "string" }, "ui_dns": { "type": "string" }, "node_count": { "type": "integer", "format": "int32", "description": "NodeCount will be 0 for serverless clusters." } }, "required": [ "name", "sql_dns", "ui_dns", "node_count" ] }, "SQLUser": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] }, "ServerlessClusterConfig": { "type": "object", "properties": { "spend_limit": { "type": "integer", "format": "int32", "description": "Spend limit in US cents." }, "routing_id": { "type": "string", "description": "Used to build a connection string." } }, "required": [ "spend_limit", "routing_id" ] }, "ServerlessClusterCreateSpecification": { "type": "object", "properties": { "regions": { "type": "array", "items": { "type": "string" }, "description": "Region values should match the cloud provider's zone code.\nFor example, for Oregon, set region_name to \"us-west2\" for\nGCP and \"us-west-2\" for AWS." }, "spend_limit": { "type": "integer", "format": "int32", "title": "Spend limit in US cents" } }, "required": [ "regions", "spend_limit" ] }, "ServerlessClusterUpdateSpecification": { "type": "object", "properties": { "spend_limit": { "type": "integer", "format": "int32", "title": "Spend limit in US cents" } }, "required": [ "spend_limit" ] }, "SortOrder": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "ASC", "description": " - DESC: Sort in descending order. The default order is ascending." }, "Status": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32" }, "message": { "type": "string" }, "details": { "type": "array", "items": { "$ref": "#/components/schemas/Any" } } } }, "UpdateClusterSpecification": { "type": "object", "example": { "dedicated": { "region_nodes": { "us-west1": 3, "us-central1": 5 }, "hardware": { "machine_type": "n2-standard-8" } } }, "properties": { "dedicated": { "$ref": "#/components/schemas/DedicatedClusterUpdateSpecification" }, "serverless": { "$ref": "#/components/schemas/ServerlessClusterUpdateSpecification" } } }, "api.CloudProvider": { "type": "string", "enum": [ "CLOUD_PROVIDER_UNSPECIFIED", "GCP", "AWS" ], "default": "CLOUD_PROVIDER_UNSPECIFIED", "description": " - GCP: The Google Cloud Platform cloud provider.\n - AWS: The Amazon Web Services cloud provider." } } } }