{ "openapi": "3.0.0", "info": { "contact": { "email": "support@cockroachlabs.com", "name": "Cockroach Labs Support", "url": "https://support.cockroachlabs.com" }, "description": "An API for managing CockroachDB Cloud resources", "title": "CockroachDB Cloud API", "version": "2024-09-16" }, "servers": [ { "url": "https://cockroachlabs.cloud" } ], "paths": { "/api/scim/v2/Groups": { "get": { "operationId": "CockroachCloud_GetGroups", "summary": "List groups", "description": "Can be used by the following roles assigned at the organization scope:\n- ORG_ADMIN\n", "parameters": [ { "name": "attributes", "in": "query", "schema": { "type": "string" } }, { "name": "excludedAttributes", "in": "query", "schema": { "type": "string" } }, { "name": "filter", "in": "query", "schema": { "type": "string" } }, { "name": "count", "in": "query", "description": "The maximum number of resources to return. If omitted, defaults to 20.\nIf set to 0, the response will contain no resources but will include metadata such as\n`totalResults`, complying with [RFC 7644, Section 3.4.2.4: Pagination](https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2.4).", "schema": { "type": "integer", "format": "int32" } }, { "name": "startIndex", "in": "query", "description": "The 1-based index of the first resource to return in the response.\nIf omitted or less than 1, defaults to 1. This behavior complies with [RFC 7644, Section 3.4.2.4: Pagination](https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2.4).", "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetGroupsResponse" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["SCIM"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --url 'https://cockroachlabs.cloud/api/scim/v2/Groups?attributes=SOME_STRING_VALUE&excludedAttributes=SOME_STRING_VALUE&filter=SOME_STRING_VALUE&count=SOME_INTEGER_VALUE&startIndex=SOME_INTEGER_VALUE' \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] }, "post": { "operationId": "CockroachCloud_CreateGroup", "summary": "Create a group", "description": "Can be used by the following roles assigned at the organization scope:\n- ORG_ADMIN\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateGroupRequest" } } } }, "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScimGroup" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["SCIM"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request POST \\\n --url https://cockroachlabs.cloud/api/scim/v2/Groups \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --json '{\"displayName\":\"Test SCIM\",\"members\":[],\"schemas\":[\"urn:ietf:params:scim:schemas:core:2.0:Group\"]}'" } ] } }, "/api/scim/v2/Groups/.search": { "post": { "operationId": "CockroachCloud_SearchGroups", "summary": "Search groups", "description": "Similar to GetGroups however search parameters are passed via the POST body. See https://www.rfc-editor.org/rfc/rfc7644.html#section-3.4.3 for more details.\n\nCan be used by the following roles assigned at the organization scope:\n- ORG_ADMIN\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetGroupsRequest" } } } }, "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetGroupsResponse" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["SCIM"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request POST \\\n --url https://cockroachlabs.cloud/api/scim/v2/Groups/.search \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --json '{\"attributes\":\"string\",\"count\":20,\"excludedAttributes\":\"string\",\"filter\":\"string\",\"startIndex\":1}'" } ] }, "put": { "operationId": "CockroachCloud_GetGroups2", "summary": "Search groups (Deprecated)", "description": "Can be used by the following roles assigned at the organization scope:\n- ORG_ADMIN\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetGroupsRequest" } } } }, "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetGroupsResponse" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "deprecated": true, "tags": ["SCIM"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request PUT \\\n --url https://cockroachlabs.cloud/api/scim/v2/Groups/.search \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --json '{\"attributes\":\"string\",\"count\":20,\"excludedAttributes\":\"string\",\"filter\":\"string\",\"startIndex\":1}'" } ] } }, "/api/scim/v2/Groups/{id}": { "delete": { "operationId": "CockroachCloud_DeleteGroup", "summary": "Delete a group based on ID", "description": "Can be used by the following roles assigned at the organization scope:\n- ORG_ADMIN\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "type": "object" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["SCIM"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request DELETE \\\n --url https://cockroachlabs.cloud/api/scim/v2/Groups/{id} \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] }, "get": { "operationId": "CockroachCloud_GetGroup", "summary": "Get a group by ID", "description": "Can be used by the following roles assigned at the organization scope:\n- ORG_ADMIN\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "attributes", "in": "query", "schema": { "type": "string" } }, { "name": "excludedAttributes", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScimGroup" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["SCIM"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --url 'https://cockroachlabs.cloud/api/scim/v2/Groups/{id}?attributes=SOME_STRING_VALUE&excludedAttributes=SOME_STRING_VALUE' \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] }, "patch": { "operationId": "CockroachCloud_PatchGroup", "summary": "Patch a group by supplying partial updates", "description": "Apply a sequence of operations to modify attributes of a SCIM Group resource. Supports 'add', 'remove', and 'replace' operations per RFC 7644 Section 3.5.2. Operations are applied atomically — if any operation fails, no changes are applied. The request body must include the 'schemas' field set to 'urn:ietf:params:scim:api:messages:2.0:PatchOp'.\n\nCan be used by the following roles assigned at the organization scope:\n- ORG_ADMIN\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchGroupBody" } } } }, "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScimGroup" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["SCIM"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request PATCH \\\n --url https://cockroachlabs.cloud/api/scim/v2/Groups/{id} \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --json '{\"Operations\":[{\"op\":\"replace\",\"path\":\"displayName\",\"value\":\"Updated Group Name\"},{\"op\":\"replace\",\"path\":\"externalId\",\"value\":\"ext-123\"},{\"op\":\"remove\",\"path\":\"members\"},{\"op\":\"add\",\"path\":\"externalId\",\"value\":\"new-external-id\"},{\"op\":\"add\",\"path\":\"members\",\"value\":[{\"value\":\"45a35c27-23d3-4d03-c4c5-9043c09e7175\"}]}],\"schemas\":[\"urn:ietf:params:scim:api:messages:2.0:PatchOp\"]}'" } ] }, "put": { "operationId": "CockroachCloud_UpdateGroup", "summary": "Update a group by supplying all values of the user object", "description": "Can be used by the following roles assigned at the organization scope:\n- ORG_ADMIN\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateGroupBody" } } } }, "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScimGroup" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["SCIM"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request PUT \\\n --url https://cockroachlabs.cloud/api/scim/v2/Groups/{id} \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --json '{\"displayName\":\"Test SCIM\",\"id\":\"23a35c27-23d3-4c03-b4c5-6443c09e7173\",\"members\":[{\"display\":\"croach@example.com\",\"value\":\"45a35c27-23d3-4d03-c4c5-9043c09e7175\"}],\"schemas\":[\"urn:ietf:params:scim:schemas:core:2.0:Group\"]}'" } ] } }, "/api/scim/v2/Groups/{id}/.search": { "post": { "operationId": "CockroachCloud_SearchGroup", "summary": "Search a group by ID", "description": "Similar to GetGroup however search parameters are passed via the POST body. See https://www.rfc-editor.org/rfc/rfc7644.html#section-3.4.3 for more details.\n\nCan be used by the following roles assigned at the organization scope:\n- ORG_ADMIN\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchGroupBody" } } } }, "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScimGroup" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["SCIM"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request POST \\\n --url https://cockroachlabs.cloud/api/scim/v2/Groups/{id}/.search \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --json '{\"attributes\":\"string\",\"excludedAttributes\":\"string\"}'" } ] }, "put": { "operationId": "CockroachCloud_GetGroup2", "summary": "Search a group by ID (Deprecated)", "description": "Can be used by the following roles assigned at the organization scope:\n- ORG_ADMIN\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetGroup2Body" } } } }, "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScimGroup" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "deprecated": true, "tags": ["SCIM"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request PUT \\\n --url https://cockroachlabs.cloud/api/scim/v2/Groups/{id}/.search \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --json '{\"attributes\":\"string\",\"excludedAttributes\":\"string\"}'" } ] } }, "/api/scim/v2/ResourceTypes": { "get": { "operationId": "CockroachCloud_GetResourceTypes", "summary": "List the SCIM resource types", "description": "This endpoint may be used by any member of the organization.", "parameters": [ { "name": "attributes", "in": "query", "schema": { "type": "string" } }, { "name": "excludedAttributes", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetResourceTypesResponse" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["SCIM"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --url 'https://cockroachlabs.cloud/api/scim/v2/ResourceTypes?attributes=SOME_STRING_VALUE&excludedAttributes=SOME_STRING_VALUE' \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] } }, "/api/scim/v2/ResourceTypes/{resourceId}": { "get": { "operationId": "CockroachCloud_GetResourceType", "summary": "Get a SCIM resource type by ID", "description": "This endpoint may be used by any member of the organization.", "parameters": [ { "name": "resourceId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "attributes", "in": "query", "schema": { "type": "string" } }, { "name": "excludedAttributes", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScimResourceType" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["SCIM"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --url 'https://cockroachlabs.cloud/api/scim/v2/ResourceTypes/{resourceId}?attributes=SOME_STRING_VALUE&excludedAttributes=SOME_STRING_VALUE' \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] } }, "/api/scim/v2/Schemas": { "get": { "operationId": "CockroachCloud_GetSchemas", "summary": "List the SCIM schemas", "description": "This endpoint may be used by any member of the organization.", "parameters": [ { "name": "attributes", "in": "query", "schema": { "type": "string" } }, { "name": "excludedAttributes", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSchemasResponse" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["SCIM"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --url 'https://cockroachlabs.cloud/api/scim/v2/Schemas?attributes=SOME_STRING_VALUE&excludedAttributes=SOME_STRING_VALUE' \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] } }, "/api/scim/v2/Schemas/{schemaId}": { "get": { "operationId": "CockroachCloud_GetSchema", "summary": "Get a SCIM schema by ID", "description": "This endpoint may be used by any member of the organization.", "parameters": [ { "name": "schemaId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "attributes", "in": "query", "schema": { "type": "string" } }, { "name": "excludedAttributes", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScimSchema" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["SCIM"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --url 'https://cockroachlabs.cloud/api/scim/v2/Schemas/{schemaId}?attributes=SOME_STRING_VALUE&excludedAttributes=SOME_STRING_VALUE' \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] } }, "/api/scim/v2/ServiceProviderConfig": { "get": { "operationId": "CockroachCloud_GetServiceProviderConfig", "summary": "Return the SCIM Service Provider configuration", "description": "This endpoint may be used by any member of the organization.", "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetServiceProviderConfigResponse" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["SCIM"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --url https://cockroachlabs.cloud/api/scim/v2/ServiceProviderConfig \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] } }, "/api/scim/v2/Users": { "get": { "operationId": "CockroachCloud_GetUsers", "summary": "List Users", "description": "Can be used by the following roles assigned at the organization scope:\n- ORG_ADMIN\n", "parameters": [ { "name": "filter", "in": "query", "schema": { "type": "string" } }, { "name": "attributes", "in": "query", "schema": { "type": "string" } }, { "name": "excludedAttributes", "in": "query", "schema": { "type": "string" } }, { "name": "count", "in": "query", "description": "The maximum number of resources to return. If omitted, defaults to 20.\nIf set to 0, the response will contain no resources but will include metadata such as\n`totalResults`, complying with [RFC 7644, Section 3.4.2.4: Pagination](https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2.4).", "schema": { "type": "integer", "format": "int32" } }, { "name": "startIndex", "in": "query", "description": "The 1-based index of the first resource to return in the response.\nIf omitted or less than 1, defaults to 1. This behavior complies with [RFC 7644, Section 3.4.2.4: Pagination](https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2.4).", "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetUsersResponse" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["SCIM"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --url 'https://cockroachlabs.cloud/api/scim/v2/Users?filter=SOME_STRING_VALUE&attributes=SOME_STRING_VALUE&excludedAttributes=SOME_STRING_VALUE&count=SOME_INTEGER_VALUE&startIndex=SOME_INTEGER_VALUE' \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] }, "post": { "operationId": "CockroachCloud_CreateUser", "summary": "Create a user", "description": "Can be used by the following roles assigned at the organization scope:\n- ORG_ADMIN\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUserRequest" } } } }, "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUserResponse" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["SCIM"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request POST \\\n --url https://cockroachlabs.cloud/api/scim/v2/Users \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --json '{\"active\":true,\"displayName\":\"Carl Roach\",\"emails\":[{\"primary\":true,\"type\":\"work\",\"value\":\"croach@example.com\"}],\"externalId\":\"11ujl29u0le5T6Aj10h9\",\"name\":{\"familyName\":\"Roach\",\"givenName\":\"Carl\"},\"schemas\":[\"urn:ietf:params:scim:schemas:core:2.0:User\"],\"userName\":\"croach@example.com\"}'" } ] } }, "/api/scim/v2/Users/.search": { "post": { "operationId": "CockroachCloud_SearchUsers", "summary": "Search Users", "description": "Similar to GetUsers however search parameters are passed via the POST body. See https://www.rfc-editor.org/rfc/rfc7644.html#section-3.4.3 for more details.\n\nCan be used by the following roles assigned at the organization scope:\n- ORG_ADMIN\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetUsersRequest" } } } }, "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetUsersResponse" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["SCIM"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request POST \\\n --url https://cockroachlabs.cloud/api/scim/v2/Users/.search \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --json '{\"attributes\":\"string\",\"count\":20,\"excludedAttributes\":\"string\",\"filter\":\"string\",\"startIndex\":1}'" } ] }, "put": { "operationId": "CockroachCloud_GetUsers2", "summary": "Search User (Deprecated)", "description": "Can be used by the following roles assigned at the organization scope:\n- ORG_ADMIN\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetUsersRequest" } } } }, "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetUsersResponse" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "deprecated": true, "tags": ["SCIM"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request PUT \\\n --url https://cockroachlabs.cloud/api/scim/v2/Users/.search \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --json '{\"attributes\":\"string\",\"count\":20,\"excludedAttributes\":\"string\",\"filter\":\"string\",\"startIndex\":1}'" } ] } }, "/api/scim/v2/Users/{id}": { "delete": { "operationId": "CockroachCloud_DeleteUser", "summary": "Delete a user based on ID", "description": "Can be used by the following roles assigned at the organization scope:\n- ORG_ADMIN\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "type": "object" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["SCIM"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request DELETE \\\n --url https://cockroachlabs.cloud/api/scim/v2/Users/{id} \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] }, "get": { "operationId": "CockroachCloud_GetUser", "summary": "Get a user by ID", "description": "Can be used by the following roles assigned at the organization scope:\n- ORG_ADMIN\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "attributes", "in": "query", "schema": { "type": "string" } }, { "name": "excludedAttributes", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScimUser" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["SCIM"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --url 'https://cockroachlabs.cloud/api/scim/v2/Users/{id}?attributes=SOME_STRING_VALUE&excludedAttributes=SOME_STRING_VALUE' \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] }, "patch": { "operationId": "CockroachCloud_PatchUser", "summary": "Patch a user by supplying partial updates", "description": "Apply a sequence of operations to modify attributes of a SCIM User resource. Supports 'add', 'remove', and 'replace' operations per RFC 7644 Section 3.5.2. Operations are applied atomically — if any operation fails, no changes are applied. The request body must include the 'schemas' field set to 'urn:ietf:params:scim:api:messages:2.0:PatchOp'.\n\nCan be used by the following roles assigned at the organization scope:\n- ORG_ADMIN\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchUserBody" } } } }, "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScimUser" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["SCIM"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request PATCH \\\n --url https://cockroachlabs.cloud/api/scim/v2/Users/{id} \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --json '{\"Operations\":[{\"op\":\"replace\",\"path\":\"userName\",\"value\":\"newUserName\"},{\"op\":\"replace\",\"value\":{\"displayName\":\"New Name\",\"emails\":[{\"primary\":true,\"value\":\"new@example.com\"}]}},{\"op\":\"remove\",\"path\":\"externalId\"}],\"schemas\":[\"urn:ietf:params:scim:api:messages:2.0:PatchOp\"]}'" } ] }, "put": { "operationId": "CockroachCloud_UpdateUser", "summary": "Update a user by supplying all values of the user object", "description": "Can be used by the following roles assigned at the organization scope:\n- ORG_ADMIN\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUserBody" } } } }, "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScimUser" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["SCIM"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request PUT \\\n --url https://cockroachlabs.cloud/api/scim/v2/Users/{id} \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --json '{\"active\":true,\"emails\":[{\"display\":\"croach@example.com\",\"primary\":true,\"type\":\"work\",\"value\":\"croach@example.com\"}],\"name\":{\"familyName\":\"Roach\",\"givenName\":\"Carl\"},\"schemas\":[\"urn:ietf:params:scim:schemas:core:2.0:User\"]}'" } ] } }, "/api/scim/v2/Users/{id}/.search": { "post": { "operationId": "CockroachCloud_SearchUser", "summary": "Search for a user by ID", "description": "Similar to GetUser however search parameters are passed via the POST body. See https://www.rfc-editor.org/rfc/rfc7644.html#section-3.4.3 for more details.\n\nCan be used by the following roles assigned at the organization scope:\n- ORG_ADMIN\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchUserBody" } } } }, "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScimUser" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["SCIM"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request POST \\\n --url https://cockroachlabs.cloud/api/scim/v2/Users/{id}/.search \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --json '{\"attributes\":\"string\",\"excludedAttributes\":\"string\"}'" } ] }, "put": { "operationId": "CockroachCloud_GetUser2", "summary": "Search for a user by ID (Deprecated)", "description": "Can be used by the following roles assigned at the organization scope:\n- ORG_ADMIN\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetUser2Body" } } } }, "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScimUser" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "deprecated": true, "tags": ["SCIM"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request PUT \\\n --url https://cockroachlabs.cloud/api/scim/v2/Users/{id}/.search \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --json '{\"attributes\":\"string\",\"excludedAttributes\":\"string\"}'" } ] } }, "/api/v1/api-keys": { "get": { "operationId": "CockroachCloud_ListApiKeys", "summary": "List API Keys", "description": "Sort order: created_at\n\nCan be used by the following roles assigned at the organization scope:\n- ORG_ADMIN\n- CLUSTER_ADMIN\n", "parameters": [ { "name": "service_account_id", "in": "query", "description": "Optional filter to limit the response to include only api keys for a specific\nservice account.", "schema": { "type": "string" } }, { "name": "pagination.page", "in": "query", "schema": { "type": "string" } }, { "name": "pagination.limit", "in": "query", "schema": { "type": "integer", "format": "int32" } }, { "name": "pagination.as_of_time", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "pagination.sort_order", "in": "query", "description": " - ASC: Sort in ascending order. This is the default unless otherwise specified.\n - DESC: Sort in descending order.", "schema": { "type": "string", "enum": ["ASC", "DESC"] } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListApiKeysResponse" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["API Keys"], "x-badges": [ { "color": "blue", "label": "PREVIEW" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --url 'https://cockroachlabs.cloud/api/v1/api-keys?service_account_id=SOME_STRING_VALUE&pagination.page=SOME_STRING_VALUE&pagination.limit=SOME_INTEGER_VALUE&pagination.as_of_time=SOME_STRING_VALUE&pagination.sort_order=SOME_STRING_VALUE' \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] }, "post": { "operationId": "CockroachCloud_CreateApiKey", "summary": "Create a new API Key", "description": "Can be used by the following roles assigned at the organization scope:\n- ORG_ADMIN\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyRequest" } } } }, "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyResponse" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["API Keys"], "x-badges": [ { "color": "blue", "label": "PREVIEW" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request POST \\\n --url https://cockroachlabs.cloud/api/v1/api-keys \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --json '{\"name\":\"example name\",\"service_account_id\":\"1234abcd-1234-1234-abcd-12345678abcd\"}'" } ] } }, "/api/v1/api-keys/{id}": { "delete": { "operationId": "CockroachCloud_DeleteApiKey", "summary": "Delete an API Key", "description": "Can be used by the following roles assigned at the organization scope:\n- ORG_ADMIN\n", "parameters": [ { "name": "id", "in": "path", "description": "The ID of the api key.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKey" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["API Keys"], "x-badges": [ { "color": "blue", "label": "PREVIEW" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request DELETE \\\n --url https://cockroachlabs.cloud/api/v1/api-keys/{id} \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] }, "get": { "operationId": "CockroachCloud_GetApiKey", "summary": "Get an API Key by ID", "description": "Can be used by the following roles assigned at the organization scope:\n- ORG_ADMIN\n- CLUSTER_ADMIN\n", "parameters": [ { "name": "id", "in": "path", "description": "the ID of the api key.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKey" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["API Keys"], "x-badges": [ { "color": "blue", "label": "PREVIEW" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --url https://cockroachlabs.cloud/api/v1/api-keys/{id} \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] }, "patch": { "operationId": "CockroachCloud_UpdateApiKey", "summary": "Update an API Key", "description": "Can be used by the following roles assigned at the organization scope:\n- ORG_ADMIN\n", "parameters": [ { "name": "id", "in": "path", "description": "The ID of the api key.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateApiKeySpecification" } } } }, "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKey" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["API Keys"], "x-badges": [ { "color": "blue", "label": "PREVIEW" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request PATCH \\\n --url https://cockroachlabs.cloud/api/v1/api-keys/{id} \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --json '{\"name\":\"new name\"}'" } ] } }, "/api/v1/auditlogevents": { "get": { "operationId": "CockroachCloud_ListAuditLogs", "summary": "List audit logs", "description": "Can be used by the following roles assigned at the organization scope:\n- ORG_ADMIN\n", "parameters": [ { "name": "starting_from", "in": "query", "description": "starting_from is the (exclusive) timestamp from which log entries will be\nreturned in the response based on their created_at time, respecting the\nsort order specified in pagination. If unset, the default will be the\ncurrent time if results are returned in descending order and the\nbeginning of time if results are in ascending order.", "schema": { "type": "string", "format": "date-time" } }, { "name": "sort_order", "in": "query", "description": "sort_order is the direction of pagination, with starting_from as the\nstart point. If unset, the default is ascending order.\n\n - ASC: Sort in ascending order. This is the default unless otherwise specified.\n - DESC: Sort in descending order.", "schema": { "type": "string", "enum": ["ASC", "DESC"] } }, { "name": "limit", "in": "query", "description": "limit is the number of entries requested in the response. Note that the\nresponse may still contain slightly more results, since the response will\nalways contain every entry at a particular timestamp.", "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListAuditLogsResponse" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Audit Logs"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --url 'https://cockroachlabs.cloud/api/v1/auditlogevents?starting_from=SOME_STRING_VALUE&sort_order=SOME_STRING_VALUE&limit=SOME_INTEGER_VALUE' \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] } }, "/api/v1/cluster-versions": { "get": { "operationId": "CockroachCloud_ListMajorClusterVersions", "summary": "List available major cluster versions", "description": "Sort order: Version number descending\n\nThis endpoint may be used by any member of the organization.", "parameters": [ { "name": "pagination.page", "in": "query", "schema": { "type": "string" } }, { "name": "pagination.limit", "in": "query", "schema": { "type": "integer", "format": "int32" } }, { "name": "pagination.as_of_time", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "pagination.sort_order", "in": "query", "description": " - ASC: Sort in ascending order. This is the default unless otherwise specified.\n - DESC: Sort in descending order.", "schema": { "type": "string", "enum": ["ASC", "DESC"] } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListMajorClusterVersionsResponse" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Clusters"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --url 'https://cockroachlabs.cloud/api/v1/cluster-versions?pagination.page=SOME_STRING_VALUE&pagination.limit=SOME_INTEGER_VALUE&pagination.as_of_time=SOME_STRING_VALUE&pagination.sort_order=SOME_STRING_VALUE' \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] } }, "/api/v1/clusters": { "get": { "operationId": "CockroachCloud_ListClusters", "summary": "List clusters in the organization", "description": "By default, clusters are sorted alphabetically by name in ascending A to Z order. To customize sorting, use the pagination.sort_by and pagination.sort_order query parameters.\n\nCan be used by the following roles assigned at the organization, folder or cluster scope:\n- ORG_ADMIN\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n- CLUSTER_DEVELOPER\n- FOLDER_ADMIN\n- FOLDER_MOVER\n- METRICS_VIEWER\n- CLUSTER_MONITOR\n", "parameters": [ { "name": "show_inactive", "in": "query", "description": "If `true`, show clusters that have been deleted or failed to initialize.\nNote that inactive clusters will only be included if the requesting user\nhas organization-scoped cluster read permissions.", "schema": { "type": "boolean", "default": false } }, { "name": "pagination.page", "in": "query", "schema": { "type": "string" } }, { "name": "pagination.limit", "in": "query", "schema": { "type": "integer", "format": "int32" } }, { "name": "pagination.as_of_time", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "pagination.sort_order", "in": "query", "description": " - ASC: Sort in ascending order. This is the default unless otherwise specified.\n - DESC: Sort in descending order.", "schema": { "type": "string", "enum": ["ASC", "DESC"] } }, { "name": "pagination.sort_by", "in": "query", "description": " - NAME: Sort by cluster name. This is the default unless otherwise specified.\n - CREATED_AT: Sort by cluster created_at.\n - DELETED_AT: Sort by cluster deleted_at. Active clusters will be sorted by created_at.", "schema": { "type": "string", "enum": ["NAME", "CREATED_AT", "DELETED_AT"] } } ], "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Clusters"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --url 'https://cockroachlabs.cloud/api/v1/clusters?show_inactive=SOME_BOOLEAN_VALUE&pagination.page=SOME_STRING_VALUE&pagination.limit=SOME_INTEGER_VALUE&pagination.as_of_time=SOME_STRING_VALUE&pagination.sort_order=SOME_STRING_VALUE&pagination.sort_by=SOME_STRING_VALUE' \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] }, "post": { "operationId": "CockroachCloud_CreateCluster", "summary": "Create and initialize a new cluster", "description": "Can be used by the following roles assigned at the organization or folder scope:\n- CLUSTER_ADMIN\n- CLUSTER_CREATOR\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateClusterRequest" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Clusters"], "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 --json '{\"name\":\"test-cluster\",\"plan\":\"STANDARD\",\"provider\":\"GCP\",\"spec\":{\"serverless\":{\"regions\":[\"us-central1\"],\"usage_limits\":{\"provisioned_virtual_cpus\":\"2\"}}}}'" } ] } }, "/api/v1/clusters/available-regions": { "get": { "operationId": "CockroachCloud_ListAvailableRegions", "summary": "List the regions available for new clusters and nodes", "description": "Sort order: Distance (based on client IP address)\n\nThis endpoint may be used by any member of the organization.", "parameters": [ { "name": "provider", "in": "query", "description": "Optional CloudProvider for filtering.\n\n - GCP: The Google Cloud Platform cloud provider.\n - AWS: The Amazon Web Services cloud provider.\n - AZURE: The Azure cloud provider.", "schema": { "type": "string", "enum": ["GCP", "AWS", "AZURE"] } }, { "name": "serverless", "in": "query", "description": "Optional filter to only show regions available for serverless clusters.", "schema": { "type": "boolean", "default": false } }, { "name": "pagination.page", "in": "query", "schema": { "type": "string" } }, { "name": "pagination.limit", "in": "query", "schema": { "type": "integer", "format": "int32" } }, { "name": "pagination.as_of_time", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "pagination.sort_order", "in": "query", "description": " - ASC: Sort in ascending order. This is the default unless otherwise specified.\n - DESC: Sort in descending order.", "schema": { "type": "string", "enum": ["ASC", "DESC"] } } ], "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Clusters"], "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.page=SOME_STRING_VALUE&pagination.limit=SOME_INTEGER_VALUE&pagination.as_of_time=SOME_STRING_VALUE&pagination.sort_order=SOME_STRING_VALUE' \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] } }, "/api/v1/clusters/{cluster_id}": { "delete": { "operationId": "CockroachCloud_DeleteCluster", "summary": "Delete a cluster and all of its data", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Clusters"], "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'" } ] }, "get": { "operationId": "CockroachCloud_GetCluster", "summary": "Get extended information about a cluster", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- ORG_ADMIN\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n- CLUSTER_DEVELOPER\n- FOLDER_ADMIN\n- FOLDER_MOVER\n- METRICS_VIEWER\n- CLUSTER_MONITOR\n", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Clusters"], "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'" } ] }, "patch": { "operationId": "CockroachCloud_UpdateCluster", "summary": "Scale, edit or upgrade a cluster", "description": "In addition to adding nodes and changing cluster fields, the PATCH Cluster endpoint can be used to upgrade the cluster version. A cluster can be upgraded when its `upgrade_status` field is equal to `UPGRADE_AVAILABLE`. The `/api/v1/cluster-versions` endpoint can be used to enumerate versions which are valid to upgrade to. To begin the upgrade, PATCH the desired version into `cockroach_version`. For example `{\"cockroach_version\": \"v24.2\"}`. Multi-node clusters will undergo a rolling upgrade and will remain available, but single-node clusters will be briefly unavailable while the upgrade takes place. Upgrades will be finalized automatically after 72 hours but can be manually finalized by sending a PATCH containing `{\"upgrade_status\": \"FINALIZED\"}` to this endpoint. Before the cluster is finalized, it can be rolled back by either sending a PATCH of the previous version via `cockroach_version` or sending a PATCH containing `{\"upgrade_status\": \"ROLLBACK_RUNNING\"}`. Version upgrade operations cannot be performed simultaneously with other update operations. Only one of `upgrade_status` or `cockroach_version` is allowed in the request.\n\nCan be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateClusterSpecification" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Clusters"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request PATCH \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id} \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --json '{\"dedicated\":{\"hardware\":{\"machine_spec\":{\"num_virtual_cpus\":8}},\"region_nodes\":{\"us-central1\":5,\"us-west1\":3}}}'" } ] } }, "/api/v1/clusters/{cluster_id}/backups": { "get": { "operationId": "CockroachCloud_ListBackups", "summary": "List cluster backups", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "parameters": [ { "name": "cluster_id", "in": "path", "description": "The cluster associated with the backups being retrieved.", "required": true, "schema": { "type": "string" } }, { "name": "pagination.page", "in": "query", "schema": { "type": "string" } }, { "name": "pagination.limit", "in": "query", "schema": { "type": "integer", "format": "int32" } }, { "name": "pagination.as_of_time", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "pagination.sort_order", "in": "query", "description": " - ASC: Sort in ascending order. This is the default unless otherwise specified.\n - DESC: Sort in descending order.", "schema": { "type": "string", "enum": ["ASC", "DESC"] } }, { "name": "start_time", "in": "query", "description": "The beginning of the time range (inclusive) used to search for backups.", "schema": { "type": "string", "format": "date-time" } }, { "name": "end_time", "in": "query", "description": "The end of the time range (exclusive) used to search for backups.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListBackupsResponse" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Backup/Restore"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --url 'https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/backups?pagination.page=SOME_STRING_VALUE&pagination.limit=SOME_INTEGER_VALUE&pagination.as_of_time=SOME_STRING_VALUE&pagination.sort_order=SOME_STRING_VALUE&start_time=SOME_STRING_VALUE&end_time=SOME_STRING_VALUE' \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] } }, "/api/v1/clusters/{cluster_id}/backups-config": { "get": { "operationId": "CockroachCloud_GetBackupConfiguration", "summary": "Get the backup configuration for a cluster", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "parameters": [ { "name": "cluster_id", "in": "path", "description": "The UUID of the cluster that this backup configuration belongs to.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupConfiguration" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Backup/Restore"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/backups-config \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] }, "patch": { "operationId": "CockroachCloud_UpdateBackupConfiguration", "summary": "Update the backup configuration for a cluster", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "parameters": [ { "name": "cluster_id", "in": "path", "description": "The UUID of the cluster that this backup configuration belongs to.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "spec contains the information that is being updated for the given\nBackupConfiguration.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBackupConfigurationSpec" } } } }, "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackupConfiguration" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Backup/Restore"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request PATCH \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/backups-config \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --json '{\"enabled\":true,\"frequency_minutes\":60,\"retention_days\":7}'" } ] } }, "/api/v1/clusters/{cluster_id}/blackout-windows": { "get": { "operationId": "CockroachCloud_ListBlackoutWindows", "summary": "List all blackout windows for a cluster", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "pagination.page", "in": "query", "schema": { "type": "string" } }, { "name": "pagination.limit", "in": "query", "schema": { "type": "integer", "format": "int32" } }, { "name": "pagination.as_of_time", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "pagination.sort_order", "in": "query", "description": " - ASC: Sort in ascending order. This is the default unless otherwise specified.\n - DESC: Sort in descending order.", "schema": { "type": "string", "enum": ["ASC", "DESC"] } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListBlackoutWindowsResponse" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Blackout Windows"], "x-badges": [ { "color": "red", "label": "LIMITED ACCESS" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --url 'https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/blackout-windows?pagination.page=SOME_STRING_VALUE&pagination.limit=SOME_INTEGER_VALUE&pagination.as_of_time=SOME_STRING_VALUE&pagination.sort_order=SOME_STRING_VALUE' \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] }, "post": { "operationId": "CockroachCloud_CreateBlackoutWindow", "summary": "Create a blackout window for a cluster", "description": "Blackout windows are supported for ADVANCED clusters only.\n\nCan be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBlackoutWindowBody" } } } }, "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlackoutWindow" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Blackout Windows"], "x-badges": [ { "color": "red", "label": "LIMITED ACCESS" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request POST \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/blackout-windows \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --json '{\"cluster_id\":\"12345678-1234-1234-1234-123456789012\",\"end_time\":\"2025-10-15T06:00:00Z\",\"start_time\":\"2025-10-15T00:00:00Z\"}'" } ] } }, "/api/v1/clusters/{cluster_id}/blackout-windows/{blackout_window_id}": { "delete": { "operationId": "CockroachCloud_DeleteBlackoutWindow", "summary": "Delete a blackout window for a cluster", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "blackout_window_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlackoutWindow" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Blackout Windows"], "x-badges": [ { "color": "red", "label": "LIMITED ACCESS" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request DELETE \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/blackout-windows/{blackout_window_id} \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] }, "get": { "operationId": "CockroachCloud_GetBlackoutWindow", "summary": "Get a blackout window by its ID for a cluster", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "blackout_window_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlackoutWindow" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Blackout Windows"], "x-badges": [ { "color": "red", "label": "LIMITED ACCESS" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/blackout-windows/{blackout_window_id} \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] }, "patch": { "operationId": "CockroachCloud_UpdateBlackoutWindow", "summary": "Update a blackout window for a cluster", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "blackout_window_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBlackoutWindowBody" } } } }, "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlackoutWindow" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Blackout Windows"], "x-badges": [ { "color": "red", "label": "LIMITED ACCESS" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request PATCH \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/blackout-windows/{blackout_window_id} \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --json '{\"blackout_window_id\":\"12345678-1234-1234-1234-123456789012\",\"cluster_id\":\"12345678-1234-1234-1234-123456789012\",\"end_time\":\"2025-10-15T06:00:00Z\",\"start_time\":\"2025-10-15T00:00:00Z\"}'" } ] } }, "/api/v1/clusters/{cluster_id}/client-ca-cert": { "delete": { "operationId": "CockroachCloud_DeleteClientCACert", "summary": "Delete Client CA Cert for a cluster", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientCACertInfo" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Client CA Certificates"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request DELETE \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/client-ca-cert \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] }, "get": { "operationId": "CockroachCloud_GetClientCACert", "summary": "Get Client CA Cert information for a cluster", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientCACertInfo" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Client CA Certificates"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/client-ca-cert \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] }, "patch": { "operationId": "CockroachCloud_UpdateClientCACert", "summary": "Update Client CA Cert for a cluster", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateClientCACertBody" } } } }, "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientCACertInfo" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Client CA Certificates"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request PATCH \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/client-ca-cert \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --json '{\"x509_pem_cert\":\"-----BEGIN CERTIFICATE-----...\"}'" } ] }, "post": { "operationId": "CockroachCloud_SetClientCACert", "summary": "Set Client CA Cert for a cluster", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetClientCACertBody" } } } }, "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientCACertInfo" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Client CA Certificates"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request POST \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/client-ca-cert \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --json '{\"x509_pem_cert\":\"-----BEGIN CERTIFICATE-----...\"}'" } ] } }, "/api/v1/clusters/{cluster_id}/cmek": { "get": { "operationId": "CockroachCloud_GetCMEKClusterInfo", "summary": "Get CMEK-related information for a cluster", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Customer-managed Encryption Keys"], "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'" } ] }, "patch": { "operationId": "CockroachCloud_UpdateCMEKStatus", "summary": "Update the CMEK-related status for a cluster", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCMEKStatusBody" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Customer-managed Encryption Keys"], "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 --json '{\"action\":\"REVOKE\"}'" } ] }, "post": { "operationId": "CockroachCloud_EnableCMEKSpec", "summary": "Enable CMEK for a cluster", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnableCMEKSpecBody" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Customer-managed Encryption Keys"], "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 --json '{\"region_specs\":[{\"key_spec\":{\"auth_principal\":\"arn:aws:iam::account:role/role-name-with-path\",\"type\":\"AWS_KMS\",\"uri\":\"arn:aws:kms:us-west-2:111122223333:key/id-of-kms-key\"},\"region\":\"us-central1\"}]}'" } ] }, "put": { "operationId": "CockroachCloud_UpdateCMEKSpec", "summary": "Enable or update the CMEK spec for a cluster", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCMEKSpecBody" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Customer-managed Encryption Keys"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request PUT \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/cmek \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --json '{\"region_specs\":[{\"key_spec\":{\"auth_principal\":\"arn:aws:iam::account:role/role-name-with-path\",\"type\":\"AWS_KMS\",\"uri\":\"arn:aws:kms:us-west-2:111122223333:key/id-of-kms-key\"},\"region\":\"us-central1\"}]}'" } ] } }, "/api/v1/clusters/{cluster_id}/connection-string": { "get": { "operationId": "CockroachCloud_GetConnectionString", "summary": "Get a formatted generic connection string for a cluster", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- ORG_ADMIN\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n- CLUSTER_DEVELOPER\n- FOLDER_ADMIN\n- FOLDER_MOVER\n- METRICS_VIEWER\n- CLUSTER_MONITOR\n", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "database", "in": "query", "schema": { "type": "string", "default": "defaultdb" } }, { "name": "sql_user", "in": "query", "schema": { "type": "string" } }, { "name": "os", "in": "query", "description": "os indicates the target operating system, used with formatting the default SSL certificate path.\nRequired only for dedicated clusters.", "schema": { "type": "string", "enum": ["MAC", "LINUX", "WINDOWS"] } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetConnectionStringResponse" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Clusters"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --url 'https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/connection-string?database=SOME_STRING_VALUE&sql_user=SOME_STRING_VALUE&os=SOME_STRING_VALUE' \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] } }, "/api/v1/clusters/{cluster_id}/databases": { "get": { "operationId": "CockroachCloud_ListDatabases", "summary": "List databases for a cluster", "description": "Sort order: Database name ascending\n\nCan be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n- CLUSTER_DEVELOPER\n", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "pagination.page", "in": "query", "schema": { "type": "string" } }, { "name": "pagination.limit", "in": "query", "schema": { "type": "integer", "format": "int32" } }, { "name": "pagination.as_of_time", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "pagination.sort_order", "in": "query", "description": " - ASC: Sort in ascending order. This is the default unless otherwise specified.\n - DESC: Sort in descending order.", "schema": { "type": "string", "enum": ["ASC", "DESC"] } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListDatabasesResponse" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Databases"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --url 'https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/databases?pagination.page=SOME_STRING_VALUE&pagination.limit=SOME_INTEGER_VALUE&pagination.as_of_time=SOME_STRING_VALUE&pagination.sort_order=SOME_STRING_VALUE' \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] }, "patch": { "operationId": "CockroachCloud_EditDatabase2", "summary": "Update a database", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditDatabaseBody" } } } }, "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Database" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Databases"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request PATCH \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/databases \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --json '{\"name\":\"example_database_name\",\"new_name\":\"example_new_database_name\"}'" } ] }, "post": { "operationId": "CockroachCloud_CreateDatabase", "summary": "Create a new database", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDatabaseBody" } } } }, "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Database" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Databases"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request POST \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/databases \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --json '{\"name\":\"example_database_name\"}'" } ] } }, "/api/v1/clusters/{cluster_id}/databases/{name}": { "delete": { "operationId": "CockroachCloud_DeleteDatabase", "summary": "Delete a database", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Database" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Databases"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request DELETE \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/databases/{name} \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] }, "patch": { "operationId": "CockroachCloud_EditDatabase", "summary": "Update a database", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditDatabaseBody" } } } }, "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Database" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Databases"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request PATCH \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/databases/{name} \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --json '{\"name\":\"example_database_name\",\"new_name\":\"example_new_database_name\"}'" } ] } }, "/api/v1/clusters/{cluster_id}/disrupt": { "get": { "operationId": "CockroachCloud_GetClusterDisruptionInfo", "summary": "Get disruption specifications for a cluster", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "parameters": [ { "name": "cluster_id", "in": "path", "description": "cluster_id is the cluster we are requesting disruption information for.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClusterDisruptionInfo" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Cluster Disruption"], "x-badges": [ { "color": "red", "label": "LIMITED ACCESS" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/disrupt \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] }, "put": { "operationId": "CockroachCloud_UpdateClusterDisruption", "summary": "Update disruption specifications for a cluster", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "parameters": [ { "name": "cluster_id", "in": "path", "description": "cluster_id specifies the cluster for this request.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateClusterDisruptionBody" } } } }, "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClusterDisruptionInfo" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Cluster Disruption"], "x-badges": [ { "color": "red", "label": "LIMITED ACCESS" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request PUT \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/disrupt \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --json '{\"regional_disruptor_specifications\":[{\"azs\":[\"string\"],\"is_whole_region\":true,\"pods\":[\"string\"],\"region_code\":\"string\"}]}'" } ] } }, "/api/v1/clusters/{cluster_id}/logexport": { "delete": { "operationId": "CockroachCloud_DeleteLogExport", "summary": "Delete the Log Export configuration for a cluster", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- ORG_ADMIN\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogExportClusterInfo" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Log Export"], "x-badges": [ { "color": "blue", "label": "PREVIEW" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request DELETE \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/logexport \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] }, "get": { "operationId": "CockroachCloud_GetLogExportInfo", "summary": "Get the Log Export configuration for a cluster", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- ORG_ADMIN\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n- METRICS_VIEWER\n", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogExportClusterInfo" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Log Export"], "x-badges": [ { "color": "blue", "label": "PREVIEW" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/logexport \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] }, "post": { "operationId": "CockroachCloud_EnableLogExport", "summary": "Create or update the Log Export configuration for a cluster", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- ORG_ADMIN\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnableLogExportBody" } } } }, "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogExportClusterInfo" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Log Export"], "x-badges": [ { "color": "blue", "label": "PREVIEW" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request POST \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/logexport \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --json '{\"auth_principal\":\"my-gcp-project-id\",\"groups\":[{\"channels\":[\"OPS\",\"HEALTH\"],\"log_name\":\"devops\",\"min_level\":\"WARNING\"}],\"log_name\":\"default\",\"omitted_channels\":[\"SESSIONS\",\"SQL_PERF\"],\"redact\":true,\"shared_key\":\"shared-key\",\"type\":\"GCP_CLOUD_LOGGING\"}'" } ] } }, "/api/v1/clusters/{cluster_id}/maintenance-window": { "delete": { "operationId": "CockroachCloud_DeleteMaintenanceWindow", "summary": "Delete the maintenance window for a cluster", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MaintenanceWindow" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Maintenance Windows"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request DELETE \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/maintenance-window \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] }, "get": { "operationId": "CockroachCloud_GetMaintenanceWindow", "summary": "Get the maintenance window for a cluster", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MaintenanceWindow" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Maintenance Windows"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/maintenance-window \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] }, "put": { "operationId": "CockroachCloud_SetMaintenanceWindow", "summary": "Set the maintenance window for a cluster", "description": "Maintenance windows are supported for ADVANCED clusters.\n\nCan be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MaintenanceWindow" } } } }, "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MaintenanceWindow" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Maintenance Windows"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request PUT \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/maintenance-window \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --json '{\"offset_duration\":\"172800s\",\"window_duration\":\"21600s\"}'" } ] } }, "/api/v1/clusters/{cluster_id}/metricexport/cloudwatch": { "delete": { "operationId": "CockroachCloud_DeleteCloudWatchMetricExport", "summary": "Delete the CloudWatch Metric Export configuration for a cluster", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteMetricExportResponse" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Metric Export"], "x-badges": [ { "color": "blue", "label": "PREVIEW" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request DELETE \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/metricexport/cloudwatch \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] }, "get": { "operationId": "CockroachCloud_GetCloudWatchMetricExportInfo", "summary": "Get the CloudWatch Metric Export configuration for a cluster", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n- METRICS_VIEWER\n", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloudWatchMetricExportInfo" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Metric Export"], "x-badges": [ { "color": "blue", "label": "PREVIEW" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/metricexport/cloudwatch \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] }, "post": { "operationId": "CockroachCloud_EnableCloudWatchMetricExport", "summary": "Create or update the CloudWatch Metric Export configuration for a cluster", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnableCloudWatchMetricExportBody" } } } }, "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloudWatchMetricExportInfo" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Metric Export"], "x-badges": [ { "color": "blue", "label": "PREVIEW" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request POST \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/metricexport/cloudwatch \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --json '{\"external_id\":\"example_external_id\",\"log_group_name\":\"example\",\"role_arn\":\"arn:aws:iam::account:role/ExampleRole\",\"target_region\":\"us-east-1\"}'" } ] } }, "/api/v1/clusters/{cluster_id}/metricexport/datadog": { "delete": { "operationId": "CockroachCloud_DeleteDatadogMetricExport", "summary": "Delete the Datadog Metric Export configuration for a cluster", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteMetricExportResponse" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Metric Export"], "x-badges": [ { "color": "blue", "label": "PREVIEW" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request DELETE \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/metricexport/datadog \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] }, "get": { "operationId": "CockroachCloud_GetDatadogMetricExportInfo", "summary": "Get the Datadog Metric Export configuration for a cluster", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n- METRICS_VIEWER\n", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatadogMetricExportInfo" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Metric Export"], "x-badges": [ { "color": "blue", "label": "PREVIEW" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/metricexport/datadog \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] }, "post": { "operationId": "CockroachCloud_EnableDatadogMetricExport", "summary": "Create or update the Datadog Metric Export configuration for a cluster", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnableDatadogMetricExportBody" } } } }, "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatadogMetricExportInfo" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Metric Export"], "x-badges": [ { "color": "blue", "label": "PREVIEW" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request POST \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/metricexport/datadog \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --json '{\"api_key\":\"datadog_api_key\",\"site\":\"US1\"}'" } ] } }, "/api/v1/clusters/{cluster_id}/metricexport/prometheus": { "delete": { "operationId": "CockroachCloud_DeletePrometheusMetricExport", "summary": "Disable Prometheus Metric Export for a cluster", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteMetricExportResponse" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Metric Export"], "x-badges": [ { "color": "blue", "label": "PREVIEW" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request DELETE \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/metricexport/prometheus \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] }, "get": { "operationId": "CockroachCloud_GetPrometheusMetricExportInfo", "summary": "Get the Prometheus Metric Export configuration for a cluster", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n- METRICS_VIEWER\n", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrometheusMetricExportInfo" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Metric Export"], "x-badges": [ { "color": "blue", "label": "PREVIEW" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/metricexport/prometheus \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] }, "post": { "operationId": "CockroachCloud_EnablePrometheusMetricExport", "summary": "Enable Prometheus Metric Export for a cluster", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrometheusMetricExportInfo" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Metric Export"], "x-badges": [ { "color": "blue", "label": "PREVIEW" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request POST \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/metricexport/prometheus \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] } }, "/api/v1/clusters/{cluster_id}/networking/allowlist": { "get": { "operationId": "CockroachCloud_ListAllowlistEntries", "summary": "Get the IP allowlist and propagation status for a cluster", "description": "Sort order: CIDR address\n\nCan be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n- CLUSTER_DEVELOPER\n", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "pagination.page", "in": "query", "schema": { "type": "string" } }, { "name": "pagination.limit", "in": "query", "schema": { "type": "integer", "format": "int32" } }, { "name": "pagination.as_of_time", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "pagination.sort_order", "in": "query", "description": " - ASC: Sort in ascending order. This is the default unless otherwise specified.\n - DESC: Sort in descending order.", "schema": { "type": "string", "enum": ["ASC", "DESC"] } } ], "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["IP Allowlists"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --url 'https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/networking/allowlist?pagination.page=SOME_STRING_VALUE&pagination.limit=SOME_INTEGER_VALUE&pagination.as_of_time=SOME_STRING_VALUE&pagination.sort_order=SOME_STRING_VALUE' \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] }, "post": { "operationId": "CockroachCloud_AddAllowlistEntry", "summary": "Add a new CIDR address to the IP allowlist", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AllowlistEntry" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["IP Allowlists"], "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 --json '{\"cidr_ip\":\"192.168.1.1\",\"cidr_mask\":32,\"name\":\"Example\",\"sql\":true,\"ui\":true}'" } ] } }, "/api/v1/clusters/{cluster_id}/networking/allowlist/{cidr_ip}/{cidr_mask}": { "delete": { "operationId": "CockroachCloud_DeleteAllowlistEntry", "summary": "Delete an IP allowlist entry", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "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" } } ], "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["IP Allowlists"], "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'" } ] }, "patch": { "operationId": "CockroachCloud_UpdateAllowlistEntry", "summary": "Update an IP allowlist entry", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "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" } } ], "requestBody": { "description": "AllowlistEntry", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "sql": { "type": "boolean" }, "ui": { "type": "boolean" } }, "example": { "cidr_ip": "192.168.1.1", "cidr_mask": 32, "name": "Example", "sql": true, "ui": true }, "required": ["ui", "sql"], "title": "AllowlistEntry" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["IP Allowlists"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request PATCH \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/networking/allowlist/{cidr_ip}/{cidr_mask} \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --json '{\"cidr_ip\":\"192.168.1.1\",\"cidr_mask\":32,\"name\":\"Example\",\"sql\":true,\"ui\":true}'" } ] }, "put": { "operationId": "CockroachCloud_AddAllowlistEntry2", "summary": "Add a new CIDR address to the IP allowlist", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "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" } } ], "requestBody": { "description": "AllowlistEntry", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "sql": { "type": "boolean" }, "ui": { "type": "boolean" } }, "example": { "cidr_ip": "192.168.1.1", "cidr_mask": 32, "name": "Example", "sql": true, "ui": true }, "required": ["ui", "sql"], "title": "AllowlistEntry" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["IP Allowlists"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request PUT \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/networking/allowlist/{cidr_ip}/{cidr_mask} \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --json '{\"cidr_ip\":\"192.168.1.1\",\"cidr_mask\":32,\"name\":\"Example\",\"sql\":true,\"ui\":true}'" } ] } }, "/api/v1/clusters/{cluster_id}/networking/aws-endpoint-connections": { "get": { "operationId": "CockroachCloud_ListAwsEndpointConnections", "summary": "List all AwsEndpointConnections for a cluster", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "parameters": [ { "name": "cluster_id", "in": "path", "description": "cluster_id is the ID for the cluster.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AwsEndpointConnections" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Private Endpoint Services"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/networking/aws-endpoint-connections \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] } }, "/api/v1/clusters/{cluster_id}/networking/aws-endpoint-connections/{endpoint_id}": { "patch": { "operationId": "CockroachCloud_SetAwsEndpointConnectionState", "summary": "Set the AWS Endpoint Connection state", "description": "The \"status\" in the response does not reflect the latest post-update\nstatus, but rather the status before the state is transitioned.\n\nCan be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "parameters": [ { "name": "cluster_id", "in": "path", "description": "cluster_id is the ID for the cluster.", "required": true, "schema": { "type": "string" } }, { "name": "endpoint_id", "in": "path", "description": "endpoint_id is the ID for the VPC endpoint on the customer's side.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetAwsEndpointConnectionStateBody" } } } }, "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AwsEndpointConnection" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Private Endpoint Services"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request PATCH \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/networking/aws-endpoint-connections/{endpoint_id} \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --json '{\"status\":\"AVAILABLE\"}'" } ] } }, "/api/v1/clusters/{cluster_id}/networking/egress-private-endpoints": { "get": { "operationId": "CockroachCloud_ListEgressPrivateEndpoints", "summary": "List egress private endpoints", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "parameters": [ { "name": "cluster_id", "in": "path", "description": "cluster_id identifies the CockroachDB Cloud cluster whose egress private endpoints to list.", "required": true, "schema": { "type": "string" } }, { "name": "pagination.page", "in": "query", "schema": { "type": "string" } }, { "name": "pagination.limit", "in": "query", "schema": { "type": "integer", "format": "int32" } }, { "name": "pagination.as_of_time", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "pagination.sort_order", "in": "query", "description": " - ASC: Sort in ascending order. This is the default unless otherwise specified.\n - DESC: Sort in descending order.", "schema": { "type": "string", "enum": ["ASC", "DESC"] } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEgressPrivateEndpointsResponse" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Egress Private Endpoints"], "x-badges": [ { "color": "red", "label": "LIMITED ACCESS" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --url 'https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/networking/egress-private-endpoints?pagination.page=SOME_STRING_VALUE&pagination.limit=SOME_INTEGER_VALUE&pagination.as_of_time=SOME_STRING_VALUE&pagination.sort_order=SOME_STRING_VALUE' \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] }, "post": { "operationId": "CockroachCloud_CreateEgressPrivateEndpoint", "summary": "Create an egress private endpoint", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "parameters": [ { "name": "cluster_id", "in": "path", "description": "cluster_id identifies the cluster to which this egress private endpoint applies.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEgressPrivateEndpointBody" } } } }, "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EgressPrivateEndpoint" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Egress Private Endpoints"], "x-badges": [ { "color": "red", "label": "LIMITED ACCESS" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request POST \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/networking/egress-private-endpoints \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --json '{\"region\":\"us-east-1\",\"target_service_identifier\":\"arn:aws:s3:::example-bucket\",\"target_service_type\":\"MSK_SASL_IAM\"}'" } ] } }, "/api/v1/clusters/{cluster_id}/networking/egress-private-endpoints/{id}": { "delete": { "operationId": "CockroachCloud_DeleteEgressPrivateEndpoint", "summary": "Delete an egress private endpoint", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "parameters": [ { "name": "cluster_id", "in": "path", "description": "cluster_id identifies the CockroachDB Cloud cluster owning the egress private endpoint.", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "id is the UUID value of the egress private endpoint in CockroachDB Cloud.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "type": "object" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Egress Private Endpoints"], "x-badges": [ { "color": "red", "label": "LIMITED ACCESS" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request DELETE \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/networking/egress-private-endpoints/{id} \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] }, "get": { "operationId": "CockroachCloud_GetEgressPrivateEndpoint", "summary": "Get egress private endpoint", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "parameters": [ { "name": "cluster_id", "in": "path", "description": "cluster_id identifies the CockroachDB Cloud cluster owning the egress private endpoint.", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "id is the UUID value of the egress private endpoint in CockroachDB Cloud.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EgressPrivateEndpoint" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Egress Private Endpoints"], "x-badges": [ { "color": "red", "label": "LIMITED ACCESS" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/networking/egress-private-endpoints/{id} \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] }, "patch": { "operationId": "CockroachCloud_UpdateEgressPrivateEndpoint", "summary": "Update egress private endpoint.", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "parameters": [ { "name": "cluster_id", "in": "path", "description": "cluster_id identifies the CockroachDB Cloud cluster owning the egress private endpoint.", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "id is the UUID value of the egress private endpoint in CockroachDB Cloud.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEgressPrivateEndpointBody" } } } }, "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EgressPrivateEndpoint" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Egress Private Endpoints"], "x-badges": [ { "color": "red", "label": "LIMITED ACCESS" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request PATCH \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/networking/egress-private-endpoints/{id} \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --json '{\"domain_names\":[\"example.com\",\"api.example.com\"]}'" } ] } }, "/api/v1/clusters/{cluster_id}/networking/egress-private-endpoints/{id}/domain-names": { "patch": { "operationId": "CockroachCloud_UpdateEgressPrivateEndpointDomainNames", "summary": "Update egress private endpoint domain names. This endpoint is deprecated\nin favor of PATCH /api/v1/clusters/{cluster_id}/networking/egress-private-endpoints/{id}\nand will be removed in a future version.", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "parameters": [ { "name": "cluster_id", "in": "path", "description": "cluster_id identifies the CockroachDB Cloud cluster owning the egress private endpoint.", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "id is the UUID value of the egress private endpoint in CockroachDB Cloud.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEgressPrivateEndpointDomainNamesBody" } } } }, "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "type": "object" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "deprecated": true, "tags": ["Egress Private Endpoints"], "x-badges": [ { "color": "red", "label": "LIMITED ACCESS" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request PATCH \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/networking/egress-private-endpoints/{id}/domain-names \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --json '{\"domain_names\":[\"example.com\",\"api.example.com\"]}'" } ] } }, "/api/v1/clusters/{cluster_id}/networking/egress-rules": { "get": { "operationId": "CockroachCloud_ListEgressRules", "summary": "List all egress rules associated with a cluster", "description": "Sort order: Name\n\nCan be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "parameters": [ { "name": "cluster_id", "in": "path", "description": "cluster_id identifies the CockroachDB cluster owning the set of returned\negress rules.", "required": true, "schema": { "type": "string" } }, { "name": "pagination.page", "in": "query", "schema": { "type": "string" } }, { "name": "pagination.limit", "in": "query", "schema": { "type": "integer", "format": "int32" } }, { "name": "pagination.as_of_time", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "pagination.sort_order", "in": "query", "description": " - ASC: Sort in ascending order. This is the default unless otherwise specified.\n - DESC: Sort in descending order.", "schema": { "type": "string", "enum": ["ASC", "DESC"] } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEgressRulesResponse" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Egress Rules"], "x-badges": [ { "color": "blue", "label": "PREVIEW" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --url 'https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/networking/egress-rules?pagination.page=SOME_STRING_VALUE&pagination.limit=SOME_INTEGER_VALUE&pagination.as_of_time=SOME_STRING_VALUE&pagination.sort_order=SOME_STRING_VALUE' \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] }, "post": { "operationId": "CockroachCloud_AddEgressRule", "summary": "Add an egress rule", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "parameters": [ { "name": "cluster_id", "in": "path", "description": "cluster_id identifies the cluster to which this egress rule applies.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddEgressRuleBody" } } } }, "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddEgressRuleResponse" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Egress Rules"], "x-badges": [ { "color": "blue", "label": "PREVIEW" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request POST \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/networking/egress-rules \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --json '{\"cluster_id\":\"35c4abb2-bb66-46d7-afed-25ebef5ed100\",\"description\":\"egress for GCP storage buckets\",\"destination\":\"storage.googleapis.com\",\"name\":\"roach-buckets\",\"ports\":[443,80],\"type\":\"FQDN\"}'" } ] } }, "/api/v1/clusters/{cluster_id}/networking/egress-rules/egress-traffic-policy": { "post": { "operationId": "CockroachCloud_SetEgressTrafficPolicy", "summary": "Outbound traffic management", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "parameters": [ { "name": "cluster_id", "in": "path", "description": "cluster_id identifies the cluster whose egress policy will be updated.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetEgressTrafficPolicyBody" } } } }, "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "type": "object" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Egress Rules"], "x-badges": [ { "color": "blue", "label": "PREVIEW" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request POST \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/networking/egress-rules/egress-traffic-policy \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --json '{\"allow_all\":true,\"idempotency_key\":\"string\"}'" } ] } }, "/api/v1/clusters/{cluster_id}/networking/egress-rules/{rule_id}": { "delete": { "operationId": "CockroachCloud_DeleteEgressRule", "summary": "Delete an existing egress rule", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "parameters": [ { "name": "cluster_id", "in": "path", "description": "cluster_id uniquely identifies the cluster owning the egress rule.", "required": true, "schema": { "type": "string" } }, { "name": "rule_id", "in": "path", "description": "rule_id is the UUID of an existing egress rule. This field is required.", "required": true, "schema": { "type": "string" } }, { "name": "idempotency_key", "in": "query", "description": "idempotency_key uniquely identifies this request. If not set, it will be\nset by the server.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteEgressRuleResponse" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Egress Rules"], "x-badges": [ { "color": "blue", "label": "PREVIEW" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request DELETE \\\n --url 'https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/networking/egress-rules/{rule_id}?idempotency_key=SOME_STRING_VALUE' \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] }, "get": { "operationId": "CockroachCloud_GetEgressRule", "summary": "Get an existing egress rule", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "parameters": [ { "name": "cluster_id", "in": "path", "description": "cluster_id uniquely identifies the cluster owning the egress rule.", "required": true, "schema": { "type": "string" } }, { "name": "rule_id", "in": "path", "description": "rule_id is the UUID of an existing egress rule.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetEgressRuleResponse" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Egress Rules"], "x-badges": [ { "color": "blue", "label": "PREVIEW" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/networking/egress-rules/{rule_id} \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] }, "patch": { "operationId": "CockroachCloud_EditEgressRule", "summary": "Edit an existing egress rule", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "parameters": [ { "name": "cluster_id", "in": "path", "description": "cluster_id uniquely identifies the cluster owning the egress rule.", "required": true, "schema": { "type": "string" } }, { "name": "rule_id", "in": "path", "description": "rule_id is the UUID of an existing egress rule. This field is required.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditEgressRuleBody" } } } }, "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditEgressRuleResponse" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Egress Rules"], "x-badges": [ { "color": "blue", "label": "PREVIEW" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request PATCH \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/networking/egress-rules/{rule_id} \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --json '{\"cluster_id\":\"35c4abb2-bb66-46d7-afed-25ebef5ed100\",\"ports\":[443,80],\"rule_id\":\"35c4abb2-bb66-46d7-afed-25ebef5ed2aa\"}'" } ] } }, "/api/v1/clusters/{cluster_id}/networking/private-endpoint-connections": { "get": { "operationId": "CockroachCloud_ListPrivateEndpointConnections", "summary": "List all connections to a cluster's private endpoint service.", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "parameters": [ { "name": "cluster_id", "in": "path", "description": "cluster_id is the ID for the cluster.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivateEndpointConnections" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Private Endpoint Services"], "x-badges": [ { "color": "blue", "label": "PREVIEW" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/networking/private-endpoint-connections \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] }, "post": { "operationId": "CockroachCloud_AddPrivateEndpointConnection", "summary": "Add a connection to a cluster's private endpoint service.", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "parameters": [ { "name": "cluster_id", "in": "path", "description": "cluster_id is the id of the cluster to which the private endpoint\nconnection will be added.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddPrivateEndpointConnectionBody" } } } }, "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivateEndpointConnection" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Private Endpoint Services"], "x-badges": [ { "color": "blue", "label": "PREVIEW" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request POST \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/networking/private-endpoint-connections \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --json '{\"cluster_id\":\"35c4abb2-bb66-46d7-afed-25ebef5ed2aa\",\"endpoint_id\":\"e-65de2gf3\"}'" } ] } }, "/api/v1/clusters/{cluster_id}/networking/private-endpoint-connections/{endpoint_id}": { "delete": { "operationId": "CockroachCloud_DeletePrivateEndpointConnection", "summary": "Delete a connection from a cluster's private endpoint service.", "description": "Remove a private endpoint from a service's trusted endpoints list. Caller should make sure to URL encode the endpoint_id before calling this method.\n\nCan be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "parameters": [ { "name": "cluster_id", "in": "path", "description": "cluster_id is the id of the cluster from which the private endpoint\nconnection will be removed.", "required": true, "schema": { "type": "string" } }, { "name": "endpoint_id", "in": "path", "description": "endpoint_id is the id of the private endpoint associated with a cluster's\nprivate endpoint service.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "type": "object" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Private Endpoint Services"], "x-badges": [ { "color": "blue", "label": "PREVIEW" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request DELETE \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/networking/private-endpoint-connections/{endpoint_id} \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] } }, "/api/v1/clusters/{cluster_id}/networking/private-endpoint-services": { "get": { "operationId": "CockroachCloud_ListPrivateEndpointServices", "summary": "List all PrivateEndpointServices for a cluster", "description": "The internal_dns property from the regions field in the ListClusters response can be used to connect to PrivateEndpointServices.\n\nCan be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "parameters": [ { "name": "cluster_id", "in": "path", "description": "cluster_id is the ID for the cluster.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivateEndpointServices" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Private Endpoint Services"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/networking/private-endpoint-services \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] }, "post": { "operationId": "CockroachCloud_CreatePrivateEndpointServices", "summary": "Create all PrivateEndpointServices for a cluster", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "parameters": [ { "name": "cluster_id", "in": "path", "description": "cluster_id is the ID for the cluster.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivateEndpointServices" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Private Endpoint Services"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request POST \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/networking/private-endpoint-services \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] } }, "/api/v1/clusters/{cluster_id}/networking/private-endpoint-trusted-owners": { "get": { "operationId": "CockroachCloud_ListPrivateEndpointTrustedOwners", "summary": "List all private endpoint trusted owners for a cluster", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "parameters": [ { "name": "cluster_id", "in": "path", "description": "cluster_id is the ID for the cluster.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListPrivateEndpointTrustedOwnersResponse" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Private Endpoint Services"], "x-badges": [ { "color": "red", "label": "LIMITED ACCESS" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/networking/private-endpoint-trusted-owners \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] }, "post": { "operationId": "CockroachCloud_AddPrivateEndpointTrustedOwner", "summary": "Add a private endpoint trusted owner to a cluster", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n", "parameters": [ { "name": "cluster_id", "in": "path", "description": "cluster_id is the ID for the cluster.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddPrivateEndpointTrustedOwnerBody" } } } }, "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddPrivateEndpointTrustedOwnerResponse" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Private Endpoint Services"], "x-badges": [ { "color": "red", "label": "LIMITED ACCESS" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request POST \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/networking/private-endpoint-trusted-owners \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --json '{\"external_owner_id\":\"012345678901\",\"type\":\"AWS_ACCOUNT_ID\"}'" } ] } }, "/api/v1/clusters/{cluster_id}/networking/private-endpoint-trusted-owners/{owner_id}": { "delete": { "operationId": "CockroachCloud_RemovePrivateEndpointTrustedOwner", "summary": "Remove a private endpoint trusted owner from a cluster", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n", "parameters": [ { "name": "cluster_id", "in": "path", "description": "cluster_id is the ID for the cluster.", "required": true, "schema": { "type": "string" } }, { "name": "owner_id", "in": "path", "description": "owner_id corresponds to the UUID of the private endpoint trusted owner\nentry.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemovePrivateEndpointTrustedOwnerResponse" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Private Endpoint Services"], "x-badges": [ { "color": "red", "label": "LIMITED ACCESS" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request DELETE \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/networking/private-endpoint-trusted-owners/{owner_id} \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] }, "get": { "operationId": "CockroachCloud_GetPrivateEndpointTrustedOwner", "summary": "Get a private endpoint trusted owner entry for a cluster", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "parameters": [ { "name": "cluster_id", "in": "path", "description": "cluster_id is the ID for the cluster.", "required": true, "schema": { "type": "string" } }, { "name": "owner_id", "in": "path", "description": "owner_id corresponds to the UUID of the private endpoint trusted owner\nentry.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPrivateEndpointTrustedOwnerResponse" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Private Endpoint Services"], "x-badges": [ { "color": "red", "label": "LIMITED ACCESS" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/networking/private-endpoint-trusted-owners/{owner_id} \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] } }, "/api/v1/clusters/{cluster_id}/nodes": { "get": { "operationId": "CockroachCloud_ListClusterNodes", "summary": "List nodes for a cluster", "description": "Sort order: Region name, node name\n\nCan be used by the following roles assigned at the organization, folder or cluster scope:\n- ORG_ADMIN\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n- CLUSTER_DEVELOPER\n", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "region_name", "in": "query", "description": "Optional filter to limit response to a single region.", "schema": { "type": "string" } }, { "name": "pagination.page", "in": "query", "schema": { "type": "string" } }, { "name": "pagination.limit", "in": "query", "schema": { "type": "integer", "format": "int32" } }, { "name": "pagination.as_of_time", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "pagination.sort_order", "in": "query", "description": " - ASC: Sort in ascending order. This is the default unless otherwise specified.\n - DESC: Sort in descending order.", "schema": { "type": "string", "enum": ["ASC", "DESC"] } } ], "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Clusters"], "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.page=SOME_STRING_VALUE&pagination.limit=SOME_INTEGER_VALUE&pagination.as_of_time=SOME_STRING_VALUE&pagination.sort_order=SOME_STRING_VALUE' \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] } }, "/api/v1/clusters/{cluster_id}/restores": { "get": { "operationId": "CockroachCloud_ListRestores", "summary": "List restore jobs", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "parameters": [ { "name": "cluster_id", "in": "path", "description": "The ID of the cluster where the restores ran or are currently running.", "required": true, "schema": { "type": "string" } }, { "name": "pagination.page", "in": "query", "schema": { "type": "string" } }, { "name": "pagination.limit", "in": "query", "schema": { "type": "integer", "format": "int32" } }, { "name": "pagination.as_of_time", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "pagination.sort_order", "in": "query", "description": " - ASC: Sort in ascending order. This is the default unless otherwise specified.\n - DESC: Sort in descending order.", "schema": { "type": "string", "enum": ["ASC", "DESC"] } }, { "name": "start_time", "in": "query", "description": "The beginning of the time range (inclusive) used to search for restores.", "schema": { "type": "string", "format": "date-time" } }, { "name": "end_time", "in": "query", "description": "The end of the time range (exclusive) used to search for restores.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListRestoresResponse" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Backup/Restore"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --url 'https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/restores?pagination.page=SOME_STRING_VALUE&pagination.limit=SOME_INTEGER_VALUE&pagination.as_of_time=SOME_STRING_VALUE&pagination.sort_order=SOME_STRING_VALUE&start_time=SOME_STRING_VALUE&end_time=SOME_STRING_VALUE' \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] } }, "/api/v1/clusters/{cluster_id}/restores/{restore_id}": { "get": { "operationId": "CockroachCloud_GetRestore", "summary": "View a restore job", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "parameters": [ { "name": "cluster_id", "in": "path", "description": "The ID of the cluster where the restore ran or is currently running.", "required": true, "schema": { "type": "string" } }, { "name": "restore_id", "in": "path", "description": "The ID of the restore.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Restore" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Backup/Restore"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/restores/{restore_id} \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] } }, "/api/v1/clusters/{cluster_id}/sql-users": { "get": { "operationId": "CockroachCloud_ListSQLUsers", "summary": "List SQL users for a cluster", "description": "Sort order: Username\n\nCan be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n- CLUSTER_DEVELOPER\n", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "pagination.page", "in": "query", "schema": { "type": "string" } }, { "name": "pagination.limit", "in": "query", "schema": { "type": "integer", "format": "int32" } }, { "name": "pagination.as_of_time", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "pagination.sort_order", "in": "query", "description": " - ASC: Sort in ascending order. This is the default unless otherwise specified.\n - DESC: Sort in descending order.", "schema": { "type": "string", "enum": ["ASC", "DESC"] } } ], "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["SQL Users"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --url 'https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/sql-users?pagination.page=SOME_STRING_VALUE&pagination.limit=SOME_INTEGER_VALUE&pagination.as_of_time=SOME_STRING_VALUE&pagination.sort_order=SOME_STRING_VALUE' \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] }, "post": { "operationId": "CockroachCloud_CreateSQLUser", "summary": "Create a new SQL user", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSQLUserBody" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["SQL Users"], "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 --json '{\"name\":\"example_username\",\"password\":\"example_password\"}'" } ] } }, "/api/v1/clusters/{cluster_id}/sql-users/{name}": { "delete": { "operationId": "CockroachCloud_DeleteSQLUser", "summary": "Delete a SQL user", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["SQL Users"], "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": { "operationId": "CockroachCloud_UpdateSQLUserPassword", "summary": "Update a SQL user's password", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSQLUserPasswordBody" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["SQL Users"], "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 --json '{\"password\":\"example_new_password\"}'" } ] } }, "/api/v1/clusters/{cluster_id}/version-deferral": { "get": { "operationId": "CockroachCloud_GetClusterVersionDeferral", "summary": "Get the version upgrade deferral policy for a cluster.", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClusterVersionDeferral" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Version Deferral"], "x-badges": [ { "color": "blue", "label": "PREVIEW" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/version-deferral \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] }, "put": { "operationId": "CockroachCloud_SetClusterVersionDeferral", "summary": "Set the version upgrade deferral policy for a cluster", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClusterVersionDeferralUpdate" } } } }, "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClusterVersionDeferral" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Version Deferral"], "x-badges": [ { "color": "blue", "label": "PREVIEW" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request PUT \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/version-deferral \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --json '{\"deferral_policy\":\"DEFERRAL_60_DAYS\"}'" } ] } }, "/api/v1/clusters/{destination_cluster_id}/restores": { "post": { "operationId": "CockroachCloud_CreateRestore", "summary": "Create a restore", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n", "parameters": [ { "name": "destination_cluster_id", "in": "path", "description": "The ID of the cluster where the backup will be restored.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRestoreBody" } } } }, "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Restore" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Backup/Restore"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request POST \\\n --url https://cockroachlabs.cloud/api/v1/clusters/{destination_cluster_id}/restores \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --json '{\"backup_id\":\"1234abcd-1234-1234-abcd-12345678abcd\",\"destination_cluster_id\":\"12345678-1234-1234-1234-123456789012\",\"objects\":[{\"database\":\"database1\",\"schema\":\"schema1\",\"table\":\"table1\"},{\"database\":\"database1\",\"schema\":\"schema1\",\"table\":\"table2\"}],\"restore_opts\":{\"into_db\":\"database2\",\"schema_only\":true},\"type\":\"TABLE\"}'" } ] } }, "/api/v1/folders": { "get": { "operationId": "CockroachCloud_ListFolders", "summary": "List folders owned by an organization", "description": "Sort order: Folder name\n\nCan be used by the following roles assigned at the organization or folder scope:\n- ORG_ADMIN\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n- CLUSTER_DEVELOPER\n- CLUSTER_CREATOR\n- FOLDER_ADMIN\n- FOLDER_MOVER\n- METRICS_VIEWER\n- CLUSTER_MONITOR\n", "parameters": [ { "name": "path", "in": "query", "description": "Optional filter to limit the response to include only results that match\nthe given absolute path to that folder. Preceding and ending \"/\" are optional.\nFor example /folder1/folder2, /folder1/folder2/, folder1/folder2, and\nfolder1/folder2/ are all equivalent. If no matching folder is found, an\nempty list is returned. Because folder paths are passed via the query\nparameters, they must be URL-encoded.", "schema": { "type": "string" } }, { "name": "pagination.page", "in": "query", "schema": { "type": "string" } }, { "name": "pagination.limit", "in": "query", "schema": { "type": "integer", "format": "int32" } }, { "name": "pagination.as_of_time", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "pagination.sort_order", "in": "query", "description": " - ASC: Sort in ascending order. This is the default unless otherwise specified.\n - DESC: Sort in descending order.", "schema": { "type": "string", "enum": ["ASC", "DESC"] } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListFoldersResponse" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Folders"], "x-badges": [ { "color": "blue", "label": "PREVIEW" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --url 'https://cockroachlabs.cloud/api/v1/folders?path=SOME_STRING_VALUE&pagination.page=SOME_STRING_VALUE&pagination.limit=SOME_INTEGER_VALUE&pagination.as_of_time=SOME_STRING_VALUE&pagination.sort_order=SOME_STRING_VALUE' \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] }, "post": { "operationId": "CockroachCloud_CreateFolder", "summary": "Create a folder", "description": "Can be used by the following roles assigned at the organization or folder scope:\n- FOLDER_ADMIN\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFolderRequest" } } } }, "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderResource" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Folders"], "x-badges": [ { "color": "blue", "label": "PREVIEW" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request POST \\\n --url https://cockroachlabs.cloud/api/v1/folders \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --json '{\"name\":\"folder_name\",\"parent_id\":\"12345678-1234-1234-1234-123456789012\"}'" } ] } }, "/api/v1/folders/{folder_id}": { "delete": { "operationId": "CockroachCloud_DeleteFolder", "summary": "Delete a folder", "description": "Can be used by the following roles assigned at the organization or folder scope:\n- FOLDER_ADMIN\n", "parameters": [ { "name": "folder_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "type": "object" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Folders"], "x-badges": [ { "color": "blue", "label": "PREVIEW" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request DELETE \\\n --url https://cockroachlabs.cloud/api/v1/folders/{folder_id} \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] }, "get": { "operationId": "CockroachCloud_GetFolder", "summary": "Get folder info for a folder", "description": "Can be used by the following roles assigned at the organization or folder scope:\n- ORG_ADMIN\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n- CLUSTER_DEVELOPER\n- CLUSTER_CREATOR\n- FOLDER_ADMIN\n- FOLDER_MOVER\n- METRICS_VIEWER\n- CLUSTER_MONITOR\n", "parameters": [ { "name": "folder_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderResource" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Folders"], "x-badges": [ { "color": "blue", "label": "PREVIEW" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --url https://cockroachlabs.cloud/api/v1/folders/{folder_id} \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] }, "patch": { "operationId": "CockroachCloud_UpdateFolder", "summary": "Update a folder", "description": "Can be used by the following roles assigned at the organization or folder scope:\n- FOLDER_ADMIN\n- FOLDER_MOVER\n", "parameters": [ { "name": "folder_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateFolderSpecification" } } } }, "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderResource" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Folders"], "x-badges": [ { "color": "blue", "label": "PREVIEW" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request PATCH \\\n --url https://cockroachlabs.cloud/api/v1/folders/{folder_id} \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --json '{\"name\":\"folder_name\",\"parent_id\":\"12345678-1234-1234-1234-123456789012\"}'" } ] } }, "/api/v1/folders/{folder_id}/contents": { "get": { "operationId": "CockroachCloud_ListFolderContents", "summary": "List contents of a folder", "description": "Set `folder_id` to 'root' to list root level contents. Sort order: Folders sorted by name, followed by Clusters sorted by name.\n\nCan be used by the following roles assigned at the organization, folder or cluster scope:\n- ORG_ADMIN\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n- CLUSTER_DEVELOPER\n- FOLDER_ADMIN\n- FOLDER_MOVER\n- METRICS_VIEWER\n- CLUSTER_MONITOR\n", "parameters": [ { "name": "folder_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "pagination.page", "in": "query", "schema": { "type": "string" } }, { "name": "pagination.limit", "in": "query", "schema": { "type": "integer", "format": "int32" } }, { "name": "pagination.as_of_time", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "pagination.sort_order", "in": "query", "description": " - ASC: Sort in ascending order. This is the default unless otherwise specified.\n - DESC: Sort in descending order.", "schema": { "type": "string", "enum": ["ASC", "DESC"] } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderResourceList" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Folders"], "x-badges": [ { "color": "blue", "label": "PREVIEW" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --url 'https://cockroachlabs.cloud/api/v1/folders/{folder_id}/contents?pagination.page=SOME_STRING_VALUE&pagination.limit=SOME_INTEGER_VALUE&pagination.as_of_time=SOME_STRING_VALUE&pagination.sort_order=SOME_STRING_VALUE' \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] } }, "/api/v1/invoices": { "get": { "operationId": "CockroachCloud_ListInvoices", "summary": "List invoices for a given organization", "description": "Sort order: invoice start date ascending\n\nCan be used by the following roles assigned at the organization scope:\n- BILLING_COORDINATOR\n- CLUSTER_ADMIN\n", "parameters": [ { "name": "status", "in": "query", "description": "Filters the response to only include invoices with the specified status.\nThis will be sent as a query parameter on the GET request.\nIf not specified, both Finalized and Draft invoices will be included.", "schema": { "type": "string", "enum": ["FINALIZED", "DRAFT"] } }, { "name": "start_time", "in": "query", "description": "start_time filters the response to invoices whose billing period started at or after this time (inclusive).\nMust be in RFC3339 format (e.g., 2024-01-01T00:00:00Z). Defaults to organization creation time if omitted.", "schema": { "type": "string", "format": "date-time" } }, { "name": "end_time", "in": "query", "description": "end_time filters the response to invoices whose billing period ended at or before this time (exclusive).\nMust be in RFC3339 format (e.g., 2024-12-31T23:59:59Z). Defaults to current time if omitted.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListInvoicesResponse" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Billing"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --url 'https://cockroachlabs.cloud/api/v1/invoices?status=SOME_STRING_VALUE&start_time=SOME_STRING_VALUE&end_time=SOME_STRING_VALUE' \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] } }, "/api/v1/invoices/{invoice_id}": { "get": { "operationId": "CockroachCloud_GetInvoice", "summary": "Get a specific invoice for an organization", "description": "Can be used by the following roles assigned at the organization scope:\n- BILLING_COORDINATOR\n- CLUSTER_ADMIN\n", "parameters": [ { "name": "invoice_id", "in": "path", "description": "invoice_id is the unique ID representing the invoice.\ninvoice_id is used to retrieve a specific\nbilling period's invoice.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Billing"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --url https://cockroachlabs.cloud/api/v1/invoices/{invoice_id} \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] } }, "/api/v1/jwt-issuers": { "get": { "operationId": "CockroachCloud_ListJWTIssuers", "summary": "List all JWT Issuers", "description": "Lists all the JWT Issuer configurations registered for the CockroachDB Cloud organization\n\nCan be used by the following roles assigned at the organization scope:\n- ORG_ADMIN\n", "parameters": [ { "name": "pagination.page", "in": "query", "schema": { "type": "string" } }, { "name": "pagination.limit", "in": "query", "schema": { "type": "integer", "format": "int32" } }, { "name": "pagination.as_of_time", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "pagination.sort_order", "in": "query", "description": " - ASC: Sort in ascending order. This is the default unless otherwise specified.\n - DESC: Sort in descending order.", "schema": { "type": "string", "enum": ["ASC", "DESC"] } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListJWTIssuersResponse" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["JWT Issuers"], "x-badges": [ { "color": "red", "label": "LIMITED ACCESS" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --url 'https://cockroachlabs.cloud/api/v1/jwt-issuers?pagination.page=SOME_STRING_VALUE&pagination.limit=SOME_INTEGER_VALUE&pagination.as_of_time=SOME_STRING_VALUE&pagination.sort_order=SOME_STRING_VALUE' \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] }, "post": { "operationId": "CockroachCloud_AddJWTIssuer", "summary": "Add a JWT Issuer", "description": "Registers a JWT Issuer with the CockroachDB Cloud to allow verifying JWTs during API authentication\n\nCan be used by the following roles assigned at the organization scope:\n- ORG_ADMIN\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddJWTIssuerRequest" } } } }, "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JWTIssuer" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["JWT Issuers"], "x-badges": [ { "color": "red", "label": "LIMITED ACCESS" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request POST \\\n --url https://cockroachlabs.cloud/api/v1/jwt-issuers \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --json '{\"audience\":\"1234567890abcd\",\"claim\":\"email\",\"identity_map\":[{\"cc_identity\":\"\\\\1\",\"token_identity\":\"/^sso_(.*)$\"}],\"issuer_url\":\"https://jwt-issuer.example.com\",\"jwks\":\"{\\\"keys\\\":[{\\\"e\\\":\\\"AQAB\\\",\\\"use\\\":\\\"sig\\\",\\\"kty\\\":\\\"RSA\\\",\\\"alg\\\":\\\"RS256\\\",\\\"n\\\":\\\"tid8bJCI5FxtvMiVHq8pRZBGIPaG9mEa1akpIC9munzxA3mWoc-KoR1TGkocu76WFthaZnPS31WJbRVChU6g4EMIg7E8Ltpxifk1PQu0qqbLcpnoI62ojsB7l_Z_lkls0NUzTuKGMMtNoJsDrL1BT0UzcnWerh2PwzDAMpfPgafWdT2IYGTx1gNLcNOWpPhDgMSQqUmIPwCmxdan4i4OMd7lJYQ1WQlN8VnQgbRgHrm1zImY6MPqho9jW3Ub5FwGbunwCDrP9a2dD_5Iwm7_lR82iB4BGlu28WxFn0fm5DgZAeAFSGKE1xblC97WrjnPh2XYTx6pxsea_Hn71VcNSQ\\\",\\\"kid\\\":\\\"9341dedeee2d1869b657fa930300082fe26b3d92\\\"}]}\"}'" } ] } }, "/api/v1/jwt-issuers/{id}": { "delete": { "operationId": "CockroachCloud_DeleteJWTIssuer", "summary": "Delete a JWT Issuer", "description": "Deletes the JWT Issuer configuration\n\nCan be used by the following roles assigned at the organization scope:\n- ORG_ADMIN\n", "parameters": [ { "name": "id", "in": "path", "description": "The unique identifier of the JWT Issuer resource", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JWTIssuer" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["JWT Issuers"], "x-badges": [ { "color": "red", "label": "LIMITED ACCESS" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request DELETE \\\n --url https://cockroachlabs.cloud/api/v1/jwt-issuers/{id} \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] }, "get": { "operationId": "CockroachCloud_GetJWTIssuer", "summary": "Get a JWT Issuer", "description": "Retrieves the JWT Issuer configuration\n\nCan be used by the following roles assigned at the organization scope:\n- ORG_ADMIN\n", "parameters": [ { "name": "id", "in": "path", "description": "The unique identifier of the JWT Issuer resource", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JWTIssuer" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["JWT Issuers"], "x-badges": [ { "color": "red", "label": "LIMITED ACCESS" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --url https://cockroachlabs.cloud/api/v1/jwt-issuers/{id} \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] }, "patch": { "operationId": "CockroachCloud_UpdateJWTIssuer", "summary": "Update a JWT Issuer", "description": "Updates the JWT Issuer configuration\n\nCan be used by the following roles assigned at the organization scope:\n- ORG_ADMIN\n", "parameters": [ { "name": "id", "in": "path", "description": "The unique identifier of the JWT Issuer resource", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateJWTIssuerBody" } } } }, "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JWTIssuer" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["JWT Issuers"], "x-badges": [ { "color": "red", "label": "LIMITED ACCESS" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request PATCH \\\n --url https://cockroachlabs.cloud/api/v1/jwt-issuers/{id} \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --json '{\"audience\":\"1234567890abcd\",\"claim\":\"email\",\"identity_map\":[{\"cc_identity\":\"\\\\1\",\"token_identity\":\"/^sso_(.*)$\"}],\"issuer_url\":\"https://jwt-issuer.example.com\",\"jwks\":\"{\\\"keys\\\":[{\\\"e\\\":\\\"AQAB\\\",\\\"use\\\":\\\"sig\\\",\\\"kty\\\":\\\"RSA\\\",\\\"alg\\\":\\\"RS256\\\",\\\"n\\\":\\\"tid8bJCI5FxtvMiVHq8pRZBGIPaG9mEa1akpIC9munzxA3mWoc-KoR1TGkocu76WFthaZnPS31WJbRVChU6g4EMIg7E8Ltpxifk1PQu0qqbLcpnoI62ojsB7l_Z_lkls0NUzTuKGMMtNoJsDrL1BT0UzcnWerh2PwzDAMpfPgafWdT2IYGTx1gNLcNOWpPhDgMSQqUmIPwCmxdan4i4OMd7lJYQ1WQlN8VnQgbRgHrm1zImY6MPqho9jW3Ub5FwGbunwCDrP9a2dD_5Iwm7_lR82iB4BGlu28WxFn0fm5DgZAeAFSGKE1xblC97WrjnPh2XYTx6pxsea_Hn71VcNSQ\\\",\\\"kid\\\":\\\"9341dedeee2d1869b657fa930300082fe26b3d92\\\"}]}\"}'" } ] } }, "/api/v1/organization": { "get": { "operationId": "CockroachCloud_GetOrganizationInfo", "summary": "Get information about the caller's organization", "description": "Can be used by the following roles assigned at the organization scope:\n- ORG_ADMIN\n- ORG_MEMBER\n", "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Organization" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Organizations"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --url https://cockroachlabs.cloud/api/v1/organization \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] } }, "/api/v1/physical-replication-streams": { "get": { "operationId": "CockroachCloud_ListPhysicalReplicationStreams", "summary": "List physical replication streams", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n- CLUSTER_DEVELOPER\n", "parameters": [ { "name": "primary_cluster_id", "in": "query", "description": "primary_cluster_id, if set, will cause only replication streams\nwith this cluster as the primary to be returned.", "schema": { "type": "string" } }, { "name": "standby_cluster_id", "in": "query", "description": "standby_cluster_id, if set, will cause only replication streams\nwith this cluster as the standby to be returned.", "schema": { "type": "string" } }, { "name": "cluster_id", "in": "query", "description": "cluster_id, if set, will cause replication streams with this\ncluster as the primary or the standby to be returned.", "schema": { "type": "string" } }, { "name": "show_completed", "in": "query", "description": "show_completed specifies whether or not replication streams in the\ncompleted state are shown.", "schema": { "type": "boolean" } }, { "name": "pagination.page", "in": "query", "schema": { "type": "string" } }, { "name": "pagination.limit", "in": "query", "schema": { "type": "integer", "format": "int32" } }, { "name": "pagination.as_of_time", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "pagination.sort_order", "in": "query", "description": " - ASC: Sort in ascending order. This is the default unless otherwise specified.\n - DESC: Sort in descending order.", "schema": { "type": "string", "enum": ["ASC", "DESC"] } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhysicalReplicationStreamList" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Physical Cluster Replication"], "x-badges": [ { "color": "blue", "label": "PREVIEW" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --url 'https://cockroachlabs.cloud/api/v1/physical-replication-streams?primary_cluster_id=SOME_STRING_VALUE&standby_cluster_id=SOME_STRING_VALUE&cluster_id=SOME_STRING_VALUE&show_completed=SOME_BOOLEAN_VALUE&pagination.page=SOME_STRING_VALUE&pagination.limit=SOME_INTEGER_VALUE&pagination.as_of_time=SOME_STRING_VALUE&pagination.sort_order=SOME_STRING_VALUE' \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] }, "post": { "operationId": "CockroachCloud_CreatePhysicalReplicationStream", "summary": "Create a physical replication stream", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePhysicalReplicationStreamRequest" } } } }, "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhysicalReplicationStream" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Physical Cluster Replication"], "x-badges": [ { "color": "blue", "label": "PREVIEW" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request POST \\\n --url https://cockroachlabs.cloud/api/v1/physical-replication-streams \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --json '{\"primary_cluster_id\":\"string\",\"standby_cluster_id\":\"string\"}'" } ] } }, "/api/v1/physical-replication-streams/{id}": { "get": { "operationId": "CockroachCloud_GetPhysicalReplicationStream", "summary": "Get a physical replication stream", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n- CLUSTER_OPERATOR_WRITER\n- CLUSTER_DEVELOPER\n", "parameters": [ { "name": "id", "in": "path", "description": "id is the ID of the replication stream to get.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhysicalReplicationStream" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Physical Cluster Replication"], "x-badges": [ { "color": "blue", "label": "PREVIEW" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --url https://cockroachlabs.cloud/api/v1/physical-replication-streams/{id} \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] }, "patch": { "operationId": "CockroachCloud_UpdatePhysicalReplicationStream", "summary": "Update a physical replication stream", "description": "Can be used by the following roles assigned at the organization, folder or cluster scope:\n- CLUSTER_ADMIN\n", "parameters": [ { "name": "id", "in": "path", "description": "id is the ID of the replication stream to update.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "spec contains the information that is being updated for the given\nreplication stream.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePhysicalReplicationStreamSpec" } } } }, "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhysicalReplicationStream" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Physical Cluster Replication"], "x-badges": [ { "color": "blue", "label": "PREVIEW" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request PATCH \\\n --url https://cockroachlabs.cloud/api/v1/physical-replication-streams/{id} \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --json '{\"failover_at\":\"2006-01-03T15:04:05Z\",\"status\":\"FAILING_OVER\"}'" } ] } }, "/api/v1/roles": { "get": { "operationId": "CockroachCloud_ListRoleGrants", "summary": "List all RoleGrants", "description": "Can be used by the following roles assigned at the organization scope:\n- ORG_ADMIN\n- CLUSTER_ADMIN\n- FOLDER_ADMIN\n", "parameters": [ { "name": "pagination.page", "in": "query", "schema": { "type": "string" } }, { "name": "pagination.limit", "in": "query", "schema": { "type": "integer", "format": "int32" } }, { "name": "pagination.as_of_time", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "pagination.sort_order", "in": "query", "description": " - ASC: Sort in ascending order. This is the default unless otherwise specified.\n - DESC: Sort in descending order.", "schema": { "type": "string", "enum": ["ASC", "DESC"] } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListRoleGrantsResponse" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Role Management"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --url 'https://cockroachlabs.cloud/api/v1/roles?pagination.page=SOME_STRING_VALUE&pagination.limit=SOME_INTEGER_VALUE&pagination.as_of_time=SOME_STRING_VALUE&pagination.sort_order=SOME_STRING_VALUE' \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] } }, "/api/v1/roles/{user_id}": { "get": { "operationId": "CockroachCloud_GetAllRolesForUser", "summary": "Get all Role Grants for a user", "description": "Can be used by the following roles assigned at the organization scope:\n- ORG_ADMIN\n- CLUSTER_ADMIN\n- FOLDER_ADMIN\n", "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAllRolesForUserResponse" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Role Management"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --url https://cockroachlabs.cloud/api/v1/roles/{user_id} \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] }, "put": { "operationId": "CockroachCloud_SetRolesForUser", "summary": "Replace the roles for a user or service account with exactly those provided", "description": "Replace the entire role set for a user or service account by providing its user_id or service_account_id.\n\nRoles that will be removed or added as a result of this call must follow the CC rules for role assignment:\nhttps://www.cockroachlabs.com/docs/cockroachcloud/authorization#organization-user-roles", "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetRolesForUserBody" } } } }, "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAllRolesForUserResponse" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Role Management"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request PUT \\\n --url https://cockroachlabs.cloud/api/v1/roles/{user_id} \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --json '{\"roles\":[{\"name\":\"CLUSTER_ADMIN\",\"resource\":{\"id\":\"example_cluster_id\",\"type\":\"CLUSTER\"}}],\"user_id\":\"12345678-1234-1234-1234-123456789012\"}'" } ] } }, "/api/v1/roles/{user_id}/{resource_type}/{resource_id}/{role_name}": { "delete": { "operationId": "CockroachCloud_RemoveUserFromRole", "summary": "Remove a role from a user or service account", "description": "Remove a single role from a user or service account by providing its user_id or service_account_id.\n\nRoles that will be removed as a result of this call must follow the CC rules for role assignment:\nhttps://www.cockroachlabs.com/docs/cockroachcloud/authorization#organization-user-roles", "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "resource_type", "in": "path", "required": true, "schema": { "type": "string", "enum": ["ORGANIZATION", "CLUSTER", "FOLDER"] } }, { "name": "resource_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "role_name", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "BILLING_COORDINATOR", "ORG_ADMIN", "ORG_MEMBER", "CLUSTER_ADMIN", "CLUSTER_OPERATOR_WRITER", "CLUSTER_DEVELOPER", "CLUSTER_CREATOR", "FOLDER_ADMIN", "FOLDER_MOVER", "METRICS_VIEWER", "CLUSTER_MONITOR", "BILLING_VIEWER" ] } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAllRolesForUserResponse" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Role Management"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request DELETE \\\n --url https://cockroachlabs.cloud/api/v1/roles/{user_id}/{resource_type}/{resource_id}/{role_name} \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] }, "post": { "operationId": "CockroachCloud_AddUserToRole", "summary": "Add a role to a user or service account", "description": "Add a single role to a user or service account by providing its user_id or service_account_id.\n\nRoles that will be added as a result of this call must follow the CC rules for role assignment:\nhttps://www.cockroachlabs.com/docs/cockroachcloud/authorization#organization-user-roles", "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "resource_type", "in": "path", "required": true, "schema": { "type": "string", "enum": ["ORGANIZATION", "CLUSTER", "FOLDER"] } }, { "name": "resource_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "role_name", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "BILLING_COORDINATOR", "ORG_ADMIN", "ORG_MEMBER", "CLUSTER_ADMIN", "CLUSTER_OPERATOR_WRITER", "CLUSTER_DEVELOPER", "CLUSTER_CREATOR", "FOLDER_ADMIN", "FOLDER_MOVER", "METRICS_VIEWER", "CLUSTER_MONITOR", "BILLING_VIEWER" ] } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAllRolesForUserResponse" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Role Management"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request POST \\\n --url https://cockroachlabs.cloud/api/v1/roles/{user_id}/{resource_type}/{resource_id}/{role_name} \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] } }, "/api/v1/service-accounts": { "get": { "operationId": "CockroachCloud_ListServiceAccounts", "summary": "List service accounts for an organization", "description": "Sort order: Service account name\n\nCan be used by the following roles assigned at the organization scope:\n- ORG_ADMIN\n- CLUSTER_ADMIN\n", "parameters": [ { "name": "pagination.page", "in": "query", "schema": { "type": "string" } }, { "name": "pagination.limit", "in": "query", "schema": { "type": "integer", "format": "int32" } }, { "name": "pagination.as_of_time", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "pagination.sort_order", "in": "query", "description": " - ASC: Sort in ascending order. This is the default unless otherwise specified.\n - DESC: Sort in descending order.", "schema": { "type": "string", "enum": ["ASC", "DESC"] } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListServiceAccountsResponse" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Service Accounts"], "x-badges": [ { "color": "blue", "label": "PREVIEW" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --url 'https://cockroachlabs.cloud/api/v1/service-accounts?pagination.page=SOME_STRING_VALUE&pagination.limit=SOME_INTEGER_VALUE&pagination.as_of_time=SOME_STRING_VALUE&pagination.sort_order=SOME_STRING_VALUE' \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] }, "post": { "operationId": "CockroachCloud_CreateServiceAccount", "summary": "Create a service account", "description": "Can be used by the following roles assigned at the organization scope:\n- ORG_ADMIN\n- CLUSTER_ADMIN\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateServiceAccountRequest" } } } }, "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceAccount" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Service Accounts"], "x-badges": [ { "color": "blue", "label": "PREVIEW" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request POST \\\n --url https://cockroachlabs.cloud/api/v1/service-accounts \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --json '{\"description\":\"\",\"name\":\"new name\",\"roles\":[{\"name\":\"CLUSTER_ADMIN\",\"resource\":{\"type\":\"ORGANIZATION\"}}]}'" } ] } }, "/api/v1/service-accounts/{id}": { "delete": { "operationId": "CockroachCloud_DeleteServiceAccount", "summary": "Delete a service account", "description": "Can be used by the following roles assigned at the organization scope:\n- ORG_ADMIN\n", "parameters": [ { "name": "id", "in": "path", "description": "the ID of the service account.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceAccount" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Service Accounts"], "x-badges": [ { "color": "blue", "label": "PREVIEW" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request DELETE \\\n --url https://cockroachlabs.cloud/api/v1/service-accounts/{id} \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] }, "get": { "operationId": "CockroachCloud_GetServiceAccount", "summary": "Get a service account by ID", "description": "Can be used by the following roles assigned at the organization scope:\n- ORG_ADMIN\n- CLUSTER_ADMIN\n", "parameters": [ { "name": "id", "in": "path", "description": "The ID of the service account.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceAccount" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Service Accounts"], "x-badges": [ { "color": "blue", "label": "PREVIEW" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --url https://cockroachlabs.cloud/api/v1/service-accounts/{id} \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] }, "patch": { "operationId": "CockroachCloud_UpdateServiceAccount", "summary": "Update a service account", "description": "To manage roles associated with a service account after creation, pass the service_account_id instead of a user_id to any [Role Management endpoint](#tag--Role-Management).\n\nCan be used by the following roles assigned at the organization scope:\n- ORG_ADMIN\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateServiceAccountSpecification" } } } }, "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceAccount" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Service Accounts"], "x-badges": [ { "color": "blue", "label": "PREVIEW" } ], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request PATCH \\\n --url https://cockroachlabs.cloud/api/v1/service-accounts/{id} \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n --json '{\"description\":\"new description\",\"name\":\"new name\"}'" } ] } }, "/api/v1/users/persons-by-email": { "get": { "operationId": "CockroachCloud_GetPersonUsersByEmail", "summary": "Search person users by email address", "description": "Can be used by the following roles assigned at the organization scope:\n- ORG_ADMIN\n- CLUSTER_ADMIN\n- FOLDER_ADMIN\n", "parameters": [ { "name": "email", "in": "query", "description": "an email address is required.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPersonUsersByEmailResponse" } } } }, "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": {} } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": {} } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } } }, "tags": ["Role Management"], "x-codeSamples": [ { "lang": "Shell + Curl", "source": "curl --request GET \\\n --url 'https://cockroachlabs.cloud/api/v1/users/persons-by-email?email=SOME_STRING_VALUE' \\\n --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'" } ] } } }, "components": { "schemas": { "AWSEndpointConnectionStatus.Type": { "type": "string", "enum": [ "PENDING", "PENDING_ACCEPTANCE", "AVAILABLE", "DELETING", "DELETED", "REJECTED", "FAILED", "EXPIRED" ] }, "AWSPrivateLinkServiceDetail": { "type": "object", "properties": { "availability_zone_ids": { "description": "availability_zone_ids are the identifiers for the availability zones\nthat the service is available in.", "type": "array", "items": { "type": "string" } }, "service_id": { "description": "service_id is the server side of the PrivateLink\nconnection. This is the same as AWSPrivateLinkEndpoint.service_id.", "type": "string" }, "service_name": { "description": "service_name is the AWS service name customers use to create endpoints\non their end.", "type": "string" } }, "required": ["service_name", "service_id", "availability_zone_ids"] }, "AddEgressRuleBody": { "type": "object", "properties": { "description": { "description": "description is text that serves to document the rules purpose.", "type": "string" }, "destination": { "description": "destination is the endpoint (or subnetwork if CIDR) to which traffic is\nallowed.", "type": "string" }, "idempotency_key": { "description": "idempotency_key uniquely identifies this request. If not set, it will be\nset by the server.", "type": "string" }, "name": { "description": "name is the name of the egress rule.", "type": "string" }, "paths": { "description": "Deprecated: This field is ignored and will be removed in the next version.\npaths are the allowed URL paths. If empty, all paths are allowed. Only\nvalid if Type=\"FQDN\".", "type": "array", "items": { "type": "string" } }, "ports": { "description": "ports are the allowed ports for TCP protocol. If Empty, all ports are\nallowed.", "type": "array", "items": { "format": "int32", "type": "integer" } }, "type": { "description": "type classifies the Destination field. Valid types include: \"FQDN\",\n\"CIDR\".", "type": "string" } }, "example": { "cluster_id": "35c4abb2-bb66-46d7-afed-25ebef5ed100", "description": "egress for GCP storage buckets", "destination": "storage.googleapis.com", "name": "roach-buckets", "ports": [443, 80], "type": "FQDN" }, "required": ["name", "type", "destination", "description"], "title": "AddEgressRuleRequest" }, "AddEgressRuleResponse": { "type": "object", "properties": { "Rule": { "$ref": "#/components/schemas/EgressRule" } }, "required": ["rule"], "title": "AddEgressRuleResponse" }, "AddJWTIssuerRequest": { "type": "object", "properties": { "audience": { "type": "string", "example": "1234567890abcd", "title": "The intended audience for consuming the JWT" }, "claim": { "type": "string", "example": "email", "title": "Used to identify the user from the external Identity Provider. Defaults to \"sub\"" }, "identity_map": { "description": "A list of mappings to map the external token identity into CockroachDB Cloud.", "type": "array", "items": { "$ref": "#/components/schemas/JWTIssuerIdentityMapEntry" } }, "issuer_url": { "type": "string", "example": "https://jwt-issuer.example.com", "title": "The URL of the server issuing JWTs" }, "jwks": { "type": "string", "example": "{\"keys\":[{\"e\":\"AQAB\",\"use\":\"sig\",\"kty\":\"RSA\",\"alg\":\"RS256\",\"n\":\"tid8bJCI5FxtvMiVHq8pRZBGIPaG9mEa1akpIC9munzxA3mWoc-KoR1TGkocu76WFthaZnPS31WJbRVChU6g4EMIg7E8Ltpxifk1PQu0qqbLcpnoI62ojsB7l_Z_lkls0NUzTuKGMMtNoJsDrL1BT0UzcnWerh2PwzDAMpfPgafWdT2IYGTx1gNLcNOWpPhDgMSQqUmIPwCmxdan4i4OMd7lJYQ1WQlN8VnQgbRgHrm1zImY6MPqho9jW3Ub5FwGbunwCDrP9a2dD_5Iwm7_lR82iB4BGlu28WxFn0fm5DgZAeAFSGKE1xblC97WrjnPh2XYTx6pxsea_Hn71VcNSQ\",\"kid\":\"9341dedeee2d1869b657fa930300082fe26b3d92\"}]}", "title": "A set of public keys (JWKS) used to verify a JWT" } }, "required": ["issuer_url", "audience"], "title": "AddJWTIssuerRequest" }, "AddPrivateEndpointConnectionBody": { "type": "object", "properties": { "endpoint_id": { "description": "endpoint_id is the id of the private endpoint associated with a cluster's\nprivate endpoint service. The private endpoint is customer-created and\nits id is generated by the cloud provider at endpoint creation time.", "type": "string" } }, "example": { "cluster_id": "35c4abb2-bb66-46d7-afed-25ebef5ed2aa", "endpoint_id": "e-65de2gf3" }, "required": ["endpoint_id"], "title": "AddPrivateEndpointConnectionRequest" }, "AddPrivateEndpointTrustedOwnerBody": { "type": "object", "properties": { "external_owner_id": { "description": "external_owner_id is the identifier of the owner within the cloud provider\nfor private endpoint connections. A wildcard character (\"*\") can be used to\ndenote all owners.", "type": "string" }, "type": { "$ref": "#/components/schemas/PrivateEndpointTrustedOwnerType.Type" } }, "example": { "external_owner_id": "012345678901", "type": "AWS_ACCOUNT_ID" }, "required": ["type", "external_owner_id"], "title": "AddPrivateEndpointTrustedOwnerRequest" }, "AddPrivateEndpointTrustedOwnerResponse": { "type": "object", "properties": { "trusted_owner": { "$ref": "#/components/schemas/PrivateEndpointTrustedOwner" } }, "required": ["trusted_owner"] }, "AllowlistEntry": { "type": "object", "properties": { "cidr_ip": { "type": "string" }, "cidr_mask": { "type": "integer", "format": "int32" }, "name": { "type": "string" }, "sql": { "type": "boolean" }, "ui": { "type": "boolean" } }, "example": { "cidr_ip": "192.168.1.1", "cidr_mask": 32, "name": "Example", "sql": true, "ui": true }, "required": ["cidr_ip", "cidr_mask", "ui", "sql"], "title": "AllowlistEntry" }, "Any": { "description": "`Any` contains an arbitrary serialized protocol buffer message along with a\nURL that describes the type of the serialized message.\n\nIn its binary encoding, an `Any` is an ordinary message; but in other wire\nforms like JSON, it has a special encoding. The format of the type URL is\ndescribed on the `type_url` field.\n\nProtobuf APIs provide utilities to interact with `Any` values:\n\n- A 'pack' operation accepts a message and constructs a generic `Any` wrapper\n around it.\n- An 'unpack' operation reads the content of an `Any` message, either into an\n existing message or a new one. Unpack operations must check the type of the\n value they unpack against the declared `type_url`.\n- An 'is' operation decides whether an `Any` contains a message of the given\n type, i.e. whether it can 'unpack' that type.\n\nThe JSON format representation of an `Any` follows one of these cases:\n\n- For types without special-cased JSON encodings, the JSON format\n representation of the `Any` is the same as that of the message, with an\n additional `@type` field which contains the type URL.\n- For types with special-cased JSON encodings (typically called 'well-known'\n types, listed in https://protobuf.dev/programming-guides/json/#any), the\n JSON format representation has a key `@type` which contains the type URL\n and a key `value` which contains the JSON-serialized value.\n\nThe text format representation of an `Any` is like a message with one field\nwhose name is the type URL in brackets. For example, an `Any` containing a\n`foo.Bar` message may be written `[type.googleapis.com/foo.Bar] { a: 2 }`.", "type": "object", "properties": { "@type": { "description": "Identifies the type of the serialized Protobuf message with a URI reference\nconsisting of a prefix ending in a slash and the fully-qualified type name.\n\nExample: type.googleapis.com/google.protobuf.StringValue\n\nThis string must contain at least one `/` character, and the content after\nthe last `/` must be the fully-qualified name of the type in canonical\nform, without a leading dot. Do not write a scheme on these URI references\nso that clients do not attempt to contact them.\n\nThe prefix is arbitrary and Protobuf implementations are expected to\nsimply strip off everything up to and including the last `/` to identify\nthe type. `type.googleapis.com/` is a common default prefix that some\nlegacy implementations require. This prefix does not indicate the origin of\nthe type, and URIs containing it are not expected to respond to any\nrequests.\n\nAll type URL strings must be legal URI references with the additional\nrestriction (for the text format) that the content of the reference\nmust consist only of alphanumeric characters, percent-encoded escapes, and\ncharacters in the following set (not including the outer backticks):\n`/-.~_!$&()*+,;=`. Despite our allowing percent encodings, implementations\nshould not unescape them to prevent confusion with existing parsers. For\nexample, `type.googleapis.com%2FFoo` should be rejected.\n\nIn the original design of `Any`, the possibility of launching a type\nresolution service at these type URLs was considered but Protobuf never\nimplemented one and considers contacting these URLs to be problematic and\na potential security issue. Do not attempt to contact type URLs.", "type": "string" } }, "additionalProperties": {} }, "ApiKey": { "type": "object", "properties": { "created_at": { "description": "the creation time of the api key.", "type": "string", "format": "date-time", "example": "2022-03-22T20:23:11.285067Z" }, "id": { "description": "the ID of the api key.", "type": "string", "example": "CCDB1_12345abcdefGHIJKLMnopq" }, "name": { "type": "string", "example": "api key name", "title": "the name of the api key" }, "service_account_id": { "description": "the ID of the service account the api key references.", "type": "string", "format": "uuid", "example": "1234abcd-1234-1234-abcd-12345678abcd" } }, "example": { "created_at": "2022-03-22T20:23:11.285067Z", "id": "CCDB1_12345abcdefGHIJKLMnopq", "name": "example name", "service_account_id": "1234abcd-1234-1234-abcd-12345678abcd" }, "required": ["id", "service_account_id", "name", "created_at"] }, "AuditLogAction": { "type": "string", "enum": [ "AUDIT_LOG_ACTION_CREATE_CLUSTER", "AUDIT_LOG_ACTION_DELETE_CLUSTER", "AUDIT_LOG_ACTION_INVITE_USER_TO_ORGANIZATION", "AUDIT_LOG_ACTION_EDIT_USER_INVITE", "AUDIT_LOG_ACTION_REVOKE_USER_INVITE", "AUDIT_LOG_ACTION_ACCEPT_USER_INVITE", "AUDIT_LOG_ACTION_ASSIGN_USER_ROLE", "AUDIT_LOG_ACTION_DELETE_USER_FROM_ORGANIZATION", "AUDIT_LOG_ACTION_CREATE_SERVICE_ACCOUNT", "AUDIT_LOG_ACTION_UPDATE_SERVICE_ACCOUNT", "AUDIT_LOG_ACTION_DELETE_SERVICE_ACCOUNT", "AUDIT_LOG_ACTION_CREATE_API_KEY", "AUDIT_LOG_ACTION_UPDATE_API_KEY", "AUDIT_LOG_ACTION_DELETE_API_KEY", "AUDIT_LOG_ACTION_UPDATE_CLUSTER", "AUDIT_LOG_ACTION_CREATE_SQL_USER", "AUDIT_LOG_ACTION_CHANGE_SQL_USER_PASSWORD", "AUDIT_LOG_ACTION_DELETE_SQL_USER", "AUDIT_LOG_ACTION_ADD_IP_ALLOWLIST", "AUDIT_LOG_ACTION_EDIT_IP_ALLOWLIST", "AUDIT_LOG_ACTION_DELETE_IP_ALLOWLIST", "AUDIT_LOG_ACTION_CREATE_VPC_PEERING", "AUDIT_LOG_ACTION_DELETE_VPC_PEERING", "AUDIT_LOG_ACTION_CREATE_PRIVATE_LINK", "AUDIT_LOG_ACTION_ACCEPT_PRIVATE_LINK", "AUDIT_LOG_ACTION_REJECT_PRIVATE_LINK", "AUDIT_LOG_ACTION_USER_LOGIN", "AUDIT_LOG_ACTION_ADD_USER_TO_ROLE", "AUDIT_LOG_ACTION_REMOVE_USER_FROM_ROLE", "AUDIT_LOG_ACTION_CREATE_USER", "AUDIT_LOG_ACTION_DELETE_USER", "AUDIT_LOG_ACTION_UPDATE_USER", "AUDIT_LOG_ACTION_CREATE_GROUP", "AUDIT_LOG_ACTION_DELETE_GROUP", "AUDIT_LOG_ACTION_UPDATE_GROUP", "AUDIT_LOG_ACTION_SET_CLIENT_CA_CERT", "AUDIT_LOG_ACTION_UPDATE_CLIENT_CA_CERT", "AUDIT_LOG_ACTION_DELETE_CLIENT_CA_CERT", "AUDIT_LOG_ACTION_CREATE_API_OIDC_CONFIG", "AUDIT_LOG_ACTION_DELETE_API_OIDC_CONFIG", "AUDIT_LOG_ACTION_UPDATE_API_OIDC_CONFIG", "AUDIT_LOG_ACTION_CREATE_FOLDER", "AUDIT_LOG_ACTION_DELETE_FOLDER", "AUDIT_LOG_ACTION_UPDATE_FOLDER", "AUDIT_LOG_ACTION_ADD_PRIVATE_ENDPOINT_TRUSTED_OWNER", "AUDIT_LOG_ACTION_REMOVE_PRIVATE_ENDPOINT_TRUSTED_OWNER", "AUDIT_LOG_ACTION_ADD_ALERT_RECIPIENT", "AUDIT_LOG_ACTION_REMOVE_ALERT_RECIPIENT", "AUDIT_LOG_ACTION_TOGGLE_ALERTS", "AUDIT_LOG_ACTION_TEST_ALERT_EMAIL", "AUDIT_LOG_ACTION_UPDATE_CMEK", "AUDIT_LOG_ACTION_REVOKE_CMEK", "AUDIT_LOG_ACTION_UPDATE_CLUSTER_LOG_EXPORT", "AUDIT_LOG_ACTION_DELETE_CLUSTER_LOG_EXPORT", "AUDIT_LOG_ACTION_UPDATE_CLUSTER_METRIC_EXPORT", "AUDIT_LOG_ACTION_DELETE_CLUSTER_METRIC_EXPORT", "AUDIT_LOG_ACTION_RESTORE_CLUSTER", "AUDIT_LOG_ACTION_UPDATE_CLUSTER_MAJOR_VERSION", "AUDIT_LOG_ACTION_ROLLBACK_CLUSTER_MAJOR_VERSION_UPDATE", "AUDIT_LOG_ACTION_FINALIZE_CLUSTER_MAJOR_VERSION_UPDATE", "AUDIT_LOG_ACTION_UPDATE_CLUSTER_VERSION_UPGRADE_DEFERRAL", "AUDIT_LOG_ACTION_SET_CLUSTER_MAINTENANCE_WINDOW", "AUDIT_LOG_ACTION_DELETE_CLUSTER_MAINTENANCE_WINDOW", "AUDIT_LOG_ACTION_SET_EGRESS_TRAFFIC_POLICY", "AUDIT_LOG_ACTION_ADD_EGRESS_RULE", "AUDIT_LOG_ACTION_EDIT_EGRESS_RULE", "AUDIT_LOG_ACTION_DELETE_EGRESS_RULE", "AUDIT_LOG_ACTION_ENABLE_CLOUD_ORG_SSO", "AUDIT_LOG_ACTION_ADD_AUTHENTICATION_METHOD", "AUDIT_LOG_ACTION_UPDATE_AUTHENTICATION_METHOD", "AUDIT_LOG_ACTION_DELETE_AUTHENTICATION_METHOD", "AUDIT_LOG_ACTION_SET_DELETE_PROTECTION", "AUDIT_LOG_ACTION_MARKETPLACE_CREATE_SUBSCRIPTION", "AUDIT_LOG_ACTION_MARKETPLACE_CANCEL_SUBSCRIPTION", "AUDIT_LOG_ACTION_ADD_JWT_ISSUER", "AUDIT_LOG_ACTION_DELETE_JWT_ISSUER", "AUDIT_LOG_ACTION_UPDATE_JWT_ISSUER", "AUDIT_LOG_ACTION_CREATE_LICENSE", "AUDIT_LOG_ACTION_UPDATE_ORGANIZATION_NAME", "AUDIT_LOG_ACTION_CREATE_LICENSES", "AUDIT_LOG_ACTION_CREATE_PLAN_MIGRATION", "AUDIT_LOG_ACTION_CANCEL_PLAN_MIGRATION", "AUDIT_LOG_ACTION_CUTOVER_PLAN_MIGRATION", "AUDIT_LOG_ACTION_CREATE_EGRESS_PRIVATE_ENDPOINT", "AUDIT_LOG_ACTION_DELETE_EGRESS_PRIVATE_ENDPOINT", "AUDIT_LOG_ACTION_UPDATE_EGRESS_PRIVATE_ENDPOINT", "AUDIT_LOG_ACTION_CREATE_PHYSICAL_REPLICATION_STREAM", "AUDIT_LOG_ACTION_FAILOVER_PHYSICAL_REPLICATION_STREAM", "AUDIT_LOG_ACTION_CANCEL_PHYSICAL_REPLICATION_STREAM", "AUDIT_LOG_ACTION_CREATE_CLUSTER_BLACKOUT_WINDOW", "AUDIT_LOG_ACTION_UPDATE_CLUSTER_BLACKOUT_WINDOW", "AUDIT_LOG_ACTION_DELETE_CLUSTER_BLACKOUT_WINDOW", "AUDIT_LOG_ACTION_START_FAULT_TOLERANCE_DEMO", "AUDIT_LOG_ACTION_END_FAULT_TOLERANCE_DEMO", "AUDIT_LOG_ACTION_UPDATE_CLUSTER_DISRUPTION", "AUDIT_LOG_ACTION_SET_CLUSTER_SETTING", "AUDIT_LOG_ACTION_EVICT_BYOC_CLUSTER", "AUDIT_LOG_ACTION_MCP_OAUTH_CONSENT", "AUDIT_LOG_ACTION_ENABLE_MFA_ENFORCEMENT", "AUDIT_LOG_ACTION_DISABLE_MFA_ENFORCEMENT", "AUDIT_LOG_ACTION_RESET_USER_MFA", "AUDIT_LOG_ACTION_ENROLL_USER_MFA", "AUDIT_LOG_ACTION_REGENERATE_RECOVERY_CODES", "AUDIT_LOG_ACTION_CREATE_MIGRATION_ASSISTANT", "AUDIT_LOG_ACTION_DELETE_MIGRATION_ASSISTANT" ] }, "AuditLogEntry": { "description": "AuditLogEntry represents an entry in the cloud event log.\nNote that this message definition should always match exactly with the\ncorresponding `AuditLogEntry` message in `console/consolepb/console.proto`.", "type": "object", "properties": { "action": { "$ref": "#/components/schemas/AuditLogAction" }, "cluster_id": { "description": "ClusterId is the ID of the cluster to which this log entry applies, if it\napplies to a single cluster.", "type": "string" }, "cluster_name": { "description": "ClusterName is the name of the cluster to which this log entry applies, if\nit applies to a single cluster.", "type": "string" }, "created_at": { "description": "CreatedAt is the time that this log entry was recorded.", "type": "string", "format": "date-time" }, "error": { "description": "Error is the error that applies to this entry if it represents a failure.", "type": "string" }, "id": { "description": "Id uniquely identifies this entry.", "type": "string" }, "metadata": { "$ref": "#/components/schemas/AuditLogMetadata" }, "payload": { "description": "Payload is a representation of the essential details relating to this\nlog entry.", "type": "string" }, "service_account_name": { "description": "ServiceAccountName is the name of the service account that triggered this\nlog entry. If it was not a service account, it will be empty.", "type": "string" }, "session_id": { "description": "SessionId is an ID that can be used to correlate this log entry with\nothers that are emitted as part of the same user session, typically for\nusers interacting through the UI. It should be treated as an opaque string\nwith no guaranteed structure.", "type": "string" }, "source": { "$ref": "#/components/schemas/AuditLogSource" }, "system_actor_name": { "$ref": "#/components/schemas/SystemActorName" }, "trace_id": { "description": "TraceId is an ID that can be used to correlate this log entry with others\nthat are emitted as part of the same process. It should be treated as an\nopaque string with no guaranteed structure.", "type": "string" }, "user_email": { "description": "UserEmail is the email address of the user that triggered this log entry.\nIf it was not a human user, it will be empty.", "type": "string" } } }, "AuditLogMetadata": { "type": "object", "properties": { "ip_address": { "type": "string" } } }, "AuditLogSource": { "type": "string", "enum": [ "AUDIT_LOG_SOURCE_CC_API", "AUDIT_LOG_SOURCE_CLI", "AUDIT_LOG_SOURCE_UI", "AUDIT_LOG_SOURCE_INTERNAL", "AUDIT_LOG_SOURCE_MCP", "AUDIT_LOG_SOURCE_SSH_GATEWAY" ] }, "Aws": { "type": "object", "properties": { "user_arn": { "type": "string", "title": "AWS IAM user ARN used by CockroachDB Cloud" } } }, "AwsCustomerCloudAccount": { "type": "object", "properties": { "arn": { "description": "The ARN string of the role that CockroachDB Cloud will assume to perform\nactions in the customer-owned AWS account. The ARN contains the account\nID so CockroachDB Cloud doesn't require it to be passed separately.", "type": "string" } }, "required": ["arn"] }, "AwsEndpointConnection": { "type": "object", "properties": { "cloud_provider": { "$ref": "#/components/schemas/CloudProvider.Type" }, "endpoint_id": { "description": "endpoint_id is the client side of the PrivateLink connection.", "type": "string" }, "external_owner_id": { "description": "external_owner_id represents the ID of the AWS account that owns the\nPrivateLink connection.", "type": "string" }, "region_name": { "description": "region_name is the cloud provider region name (i.e. us-east-1).", "type": "string" }, "service_id": { "description": "service_id is the server side of the PrivateLink\nconnection. This is the same as AWSPrivateLinkEndpoint.service_id.", "type": "string" }, "status": { "$ref": "#/components/schemas/AWSEndpointConnectionStatus.Type" } }, "required": [ "region_name", "cloud_provider", "status", "endpoint_id", "service_id" ] }, "AwsEndpointConnections": { "type": "object", "properties": { "connections": { "description": "Connections is a list of private endpoints.", "type": "array", "items": { "$ref": "#/components/schemas/AwsEndpointConnection" } } }, "required": ["connections"] }, "Azure": { "type": "object", "properties": { "app_registration_client_id": { "type": "string", "title": "Azure app registration client ID used by CockroachDB Cloud" }, "app_registration_name": { "type": "string", "title": "Azure app registration name used by CockroachDB Cloud" } } }, "AzureCustomerCloudAccount": { "type": "object", "properties": { "subscription_id": { "description": "The ID of the subscription in the customer-owned Azure tenant in which\nclusters will be created.", "type": "string" }, "tenant_id": { "description": "The ID of the customer-owned tenant in which the subscription exists.", "type": "string" } }, "required": ["subscription_id", "tenant_id"] }, "BackupConfiguration": { "type": "object", "properties": { "enabled": { "description": "Indicates whether backups are enabled.", "type": "boolean" }, "frequency_minutes": { "description": "How frequently in minutes that backups are taken, which will determine the\n[RPO](https://www.cockroachlabs.com/docs/stable/disaster-recovery-overview)\nof the cluster.", "type": "integer", "format": "int32" }, "retention_days": { "description": "The number of days backups are retained for.", "type": "integer", "format": "int32" } }, "example": { "enabled": true, "frequency_minutes": 60, "retention_days": 7 }, "required": ["enabled", "retention_days", "frequency_minutes"], "title": "BackupConfiguration" }, "BackupSummary": { "type": "object", "properties": { "as_of_time": { "description": "The point in time (in UTC) the backup restores to.", "type": "string", "format": "date-time" }, "id": { "description": "The unique identifier associated with the backup.", "type": "string" } }, "required": ["id", "as_of_time"] }, "BlackoutWindow": { "description": "BlackoutWindow schedules a period of up to 14 days for an\nADVANCED cluster to block \"high-risk\" operations that\nimpact SQL availability or require CRDB pod restarts.", "type": "object", "properties": { "cluster_id": { "description": "The cluster ID that this blackout window applies to.", "type": "string" }, "end_time": { "description": "The end time of the blackout window (UTC).\nCan be up to 14 days after the start time.\nMust not be more than three months after the current time.", "type": "string", "format": "date-time" }, "id": { "description": "The unique ID of the blackout window.", "type": "string" }, "start_time": { "description": "The start time of the blackout window (UTC).\nMust be scheduled at least 7 days in advance.", "type": "string", "format": "date-time" } }, "example": { "cluster_id": "12345678-1234-1234-1234-123456789012", "end_time": "2025-10-15T06:00:00Z", "id": "12345678-1234-1234-1234-123456789012", "start_time": "2025-10-15T00:00:00Z" }, "required": ["id", "cluster_id", "start_time", "end_time"], "title": "BlackoutWindow" }, "BuiltInFromGroups": { "type": "object", "properties": { "group_names": { "type": "array", "items": { "type": "string" } }, "role": { "$ref": "#/components/schemas/BuiltInRole" } } }, "BuiltInRole": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/OrganizationUserRole.Type" }, "resource": { "$ref": "#/components/schemas/Resource" } }, "required": ["name", "resource"] }, "CMEKClusterInfo": { "description": "CMEKClusterInfo contains the status of CMEK across an entire cluster,\nincluding within each one its regions.", "type": "object", "properties": { "region_infos": { "type": "array", "items": { "$ref": "#/components/schemas/CMEKRegionInfo" } }, "status": { "$ref": "#/components/schemas/CMEKStatus" } } }, "CMEKCustomerAction": { "description": "CMEKCustomerAction enumerates the actions a customer can take on a cluster\nthat has been enabled for CMEK.", "type": "string", "enum": ["REVOKE"] }, "CMEKKeyInfo": { "description": "CMEKKeyInfo contains the status of a customer-provided key alongside the\nspecification.", "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time" }, "spec": { "$ref": "#/components/schemas/CMEKKeySpecification" }, "status": { "$ref": "#/components/schemas/CMEKStatus" }, "updated_at": { "type": "string", "format": "date-time" }, "user_message": { "type": "string" } } }, "CMEKKeySpecification": { "description": "CMEKKeySpecification contains all the details necessary to use a customer-provided\nencryption key.\n\nThis involves the type/location of the key and the principal to authenticate as \nwhen accessing it.", "type": "object", "properties": { "auth_principal": { "type": "string" }, "type": { "$ref": "#/components/schemas/CMEKKeyType" }, "uri": { "type": "string" } } }, "CMEKKeyType": { "type": "string", "enum": ["AWS_KMS", "GCP_CLOUD_KMS", "NULL_KMS", "AZURE_KEY_VAULT"], "title": "CMEKKeyType enumerates types of customer-managed keys" }, "CMEKRegionInfo": { "description": "CMEKRegionInfo contains the status of CMEK within a region.\n\nThis includes current and past key specifications used within the region, \nas well as the status of those specifications", "type": "object", "properties": { "key_infos": { "type": "array", "items": { "$ref": "#/components/schemas/CMEKKeyInfo" } }, "region": { "type": "string" }, "status": { "$ref": "#/components/schemas/CMEKStatus" } } }, "CMEKRegionSpecification": { "description": "CMEKRegionSpecification declares the customer-provided key specification that\nshould be used in a given region.", "type": "object", "properties": { "key_spec": { "$ref": "#/components/schemas/CMEKKeySpecification" }, "region": { "type": "string" } } }, "CMEKStatus": { "description": "CMEKStatus describes the current status of CMEK for an entire CRDB cluster\nor a CMEK key within a region.\n\n - DISABLED: DISABLED corresponds to the state of a cluster or region-level key when\nCMEK has finished being disabled. By default, CMEK will be disabled for\nnew clusters.\n - DISABLING: DISABLING corresponds to the state of a cluster or region-level key when\nCMEK 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 when\nCMEK is enabled.\n - ENABLING: ENABLING corresponds to the state of a cluster or region-level key when\nCMEK 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 - ROTATING: ROTATING corresponds to the state of a cluster or region when the a new\nspec is in the process of being enabled while an existing spec is being\ndisabled.\n - ROTATE_FAILED: ROTATE_FAILED corresponds to the state of a cluster or region if there was\na failure to update from one CMEK spec to another.\n - REVOKED: REVOKED corresponds to the state of a cluster or region-level key when the\ncustomer has revoked CockroachLab's permissions for their key.\n - REVOKING: REVOKING corresponds to the state of a cluster or region-level key when\nCMEK 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.", "type": "string", "enum": [ "DISABLED", "DISABLING", "DISABLE_FAILED", "ENABLED", "ENABLING", "ENABLE_FAILED", "ROTATING", "ROTATE_FAILED", "REVOKED", "REVOKING", "REVOKE_FAILED" ] }, "ClientCACertInfo": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/ClientCACertStatus" }, "x509_pem_cert": { "type": "string" } } }, "ClientCACertStatus": { "description": " - NOT_SET: NOT_SET indicates a client CA cert is not set on the cluster.\nNew clusters won't have a client CA cert set.\n - IS_SET: IS_SET indicates a client CA cert is set on the cluster.\n - PENDING: PENDING indicates a client CA cert update is in flight on the cluster.\n - FAILED: FAILED indicates a client CA cert update was attempted, but failed.", "type": "string", "enum": ["NOT_SET", "IS_SET", "PENDING", "FAILED"] }, "CloudProvider.Type": { "description": " - GCP: The Google Cloud Platform cloud provider.\n - AWS: The Amazon Web Services cloud provider.\n - AZURE: The Azure cloud provider.", "type": "string", "enum": ["GCP", "AWS", "AZURE"] }, "CloudProviderRegion": { "type": "object", "properties": { "distance": { "description": "Distance in miles, based on client IP address.", "type": "number", "format": "float" }, "location": { "type": "string" }, "name": { "type": "string" }, "provider": { "$ref": "#/components/schemas/CloudProvider.Type" }, "serverless": { "type": "boolean" } }, "required": ["name", "location", "provider", "serverless", "distance"] }, "CloudWatchMetricExportInfo": { "type": "object", "properties": { "cluster_id": { "type": "string" }, "external_id": { "description": "external_id, if set, is included when assuming the IAM role. Supported for\nAdvanced clusters only.", "type": "string" }, "log_group_name": { "description": "log_group_name is the customized log group name.", "type": "string" }, "role_arn": { "description": "role_arn is the IAM role used to upload metric segments to the\ntarget AWS account.", "type": "string" }, "status": { "$ref": "#/components/schemas/MetricExportStatus.Type" }, "target_region": { "description": "target_region specifies the specific AWS region that the metrics will\nbe exported to.", "type": "string" }, "user_message": { "type": "string" } }, "required": ["cluster_id", "role_arn"], "title": "CloudWatchMetricExportInfo" }, "Cluster": { "type": "object", "properties": { "account_id": { "description": "account_id is a cloud provider account ID representing the CockroachDB\ncluster. This ID can be used for setting up trust relationships with cloud\nresources. For GCP clusters, this value is a project name that can be used\nto construct principal service account names for authentication.", "type": "string" }, "azure_cluster_identity_client_id": { "description": "The client ID of the Azure cluster identity associated with this cluster.\nThis field is only populated for clusters deployed on Azure and is used\nto support customer-managed encryption keys (CMEK).", "type": "string" }, "cidr_range": { "description": "cidr_range is the IPv4 range in CIDR format that will be used by the\ncluster. It is only set on GCP Advanced tier clusters and is otherwise\nempty.", "type": "string" }, "cloud_provider": { "$ref": "#/components/schemas/CloudProvider.Type" }, "cockroach_version": { "type": "string" }, "config": { "$ref": "#/components/schemas/ClusterConfig" }, "created_at": { "type": "string", "format": "date-time" }, "creator_id": { "type": "string" }, "customer_cloud_account": { "$ref": "#/components/schemas/CustomerCloudAccount" }, "delete_protection": { "$ref": "#/components/schemas/DeleteProtectionState.Type" }, "deleted_at": { "type": "string", "format": "date-time" }, "egress_traffic_policy": { "$ref": "#/components/schemas/EgressTrafficPolicy.Type" }, "id": { "type": "string" }, "labels": { "description": "labels are key-value pairs used to organize and categorize resources.", "type": "object", "additionalProperties": { "type": "string" } }, "name": { "type": "string" }, "network_visibility": { "$ref": "#/components/schemas/NetworkVisibility.Type" }, "operation_status": { "$ref": "#/components/schemas/ClusterStatus.Type" }, "parent_id": { "description": "Preview: The parent ID is a folder ID. A \"root\" valued parent ID\nrefers to a cluster at the root level.", "type": "string" }, "plan": { "$ref": "#/components/schemas/Plan.Type" }, "regions": { "type": "array", "items": { "$ref": "#/components/schemas/Region" } }, "sql_dns": { "description": "sql_dns is the DNS name of SQL interface of the cluster.", "type": "string" }, "state": { "$ref": "#/components/schemas/ClusterState.Type" }, "updated_at": { "type": "string", "format": "date-time" }, "upgrade_status": { "$ref": "#/components/schemas/ClusterUpgradeStatus.Type" } }, "example": { "account_id": "", "cidr_range": "172.28.0.0/14", "cloud_provider": "GCP", "cockroach_version": "v21.2.4", "config": { "serverless": { "routing_id": "example-cluster-1533", "upgrade_type": "AUTOMATIC", "usage_limits": { "provisioned_virtual_cpus": "2" } } }, "created_at": "2022-03-22T20:23:11.285067Z", "creator_id": "7cde0cd9-0d8a-4008-8f90-45092ce8afc1", "id": "35c4abb2-bb66-46d7-afed-25ebef5ed2aa", "is_customer_cloud_account": false, "labels": { "cost_center": "12345", "env": "prod" }, "name": "example-cluster", "operation_status": "UNSPECIFIED", "plan": "STANDARD", "regions": [ { "internal_dns": "internal-free-tier7.gcp-us-central1.crdb.io", "name": "us-central1", "node_count": 0, "private_endpoint_dns": "private-free-tier7.gcp-us-central1.crdb.io", "sql_dns": "free-tier7.gcp-us-central1.crdb.io", "ui_dns": "" } ], "state": "CREATED", "updated_at": "2022-03-22T20:23:11.879593Z", "upgrade_status": "UPGRADE_AVAILABLE" }, "required": [ "id", "name", "cockroach_version", "upgrade_status", "plan", "cloud_provider", "state", "creator_id", "operation_status", "config", "regions", "cidr_range", "labels", "is_customer_cloud_account" ] }, "ClusterConfig": { "type": "object", "properties": { "dedicated": { "$ref": "#/components/schemas/DedicatedHardwareConfig" }, "serverless": { "$ref": "#/components/schemas/ServerlessClusterConfig" } } }, "ClusterDisruptionInfo": { "type": "object", "properties": { "regional_disruptor_specifications": { "description": "regional_disruptor_specifications represents a region that is disrupted.\nIf there are no entries, it means the cluster is not disrupted.", "type": "array", "items": { "$ref": "#/components/schemas/RegionalDisruptorSpecification" } } }, "required": ["regional_disruptor_specifications"] }, "ClusterMajorVersion": { "description": "For more information about CockroachDB cluster version support, see https://www.cockroachlabs.com/docs/releases/release-support-policy.html", "type": "object", "properties": { "allowed_upgrades": { "type": "array", "items": { "type": "string" } }, "release_type": { "$ref": "#/components/schemas/ReleaseType.Type" }, "support_end": { "type": "string", "format": "date-time" }, "support_status": { "$ref": "#/components/schemas/ClusterMajorVersionSupportStatus.Type" }, "version": { "type": "string" } }, "required": [ "version", "support_status", "support_end", "release_type", "allowed_upgrades" ] }, "ClusterMajorVersionSupportStatus.Type": { "type": "string", "enum": ["UNSUPPORTED", "SUPPORTED", "PREVIEW"] }, "ClusterState.Type": { "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.", "type": "string", "enum": ["CREATING", "CREATED", "CREATION_FAILED", "DELETED", "LOCKED"] }, "ClusterStatus.Type": { "type": "string", "enum": [ "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", "CRDB_LOG_EXPORT_OPERATION_RUNNING", "CRDB_LOG_EXPORT_OPERATION_FAILED", "CRDB_CLUSTER_DISRUPTION_RUNNING", "CRDB_CLUSTER_DISRUPTION_FAILED", "CRDB_REPAVE_RUNNING", "CRDB_REPAVE_FAILED", "CRDB_CUSTOM_CLIENT_CA_RUNNING", "CRDB_CUSTOM_CLIENT_CA_FAILED", "DEDICATED_FULL_CLUSTER_RESTORE_RUNNING", "DEDICATED_FULL_CLUSTER_RESTORE_FAILED" ] }, "ClusterUpgradeStatus.Type": { "description": " - FINALIZED: The cluster is running the latest available CockroachDB version, and all upgrades have been finalized.\n - MAJOR_UPGRADE_RUNNING: An major version upgrade is currently in progress.\n - UPGRADE_AVAILABLE: An upgrade is available. If preview builds are enabled for the parent organization, this could indicate that a preview upgrade is available.\n - PENDING_FINALIZATION: An upgrade is complete, but pending finalization. Upgrades are automatically finalized after 72 hours. For more information, see https://www.cockroachlabs.com/docs/stable/upgrade-cockroach-version.html\n - ROLLBACK_RUNNING: A rollback operation is currently in progress.", "type": "string", "enum": [ "FINALIZED", "MAJOR_UPGRADE_RUNNING", "UPGRADE_AVAILABLE", "PENDING_FINALIZATION", "ROLLBACK_RUNNING" ] }, "ClusterVersionDeferral": { "description": "ClusterVersionDeferral specifies whether automatic patch version upgrades are applied\nimmediately or deferred. If upgrades are deferred, the cluster will be automatically\nupgraded to each patch version after the specified number of days (30, 60, or 90)\nafter the version is released to CockroachDB Cloud.", "type": "object", "properties": { "deferral_policy": { "$ref": "#/components/schemas/ClusterVersionDeferralPolicy.Type" }, "deferred_until": { "type": "string", "format": "date-time", "title": "The calculated date and time after which the cluster will be eligible for the next patch upgrade,\nbased on the deferral policy and the patch version's release date.\nThe patch will be applied in a maintenance window available after the deferral date.\nThis field will be null if:\n- The deferral policy is NOT_DEFERRED (immediate eligibility upon patch release)\n- There is no pending patch version available\n- The cluster is already on the latest patch version\n- Version release date information is unavailable" } }, "example": { "deferral_policy": "DEFERRAL_60_DAYS", "deferred_until": "2025-12-15T00:00:00Z" }, "required": ["deferral_policy"], "title": "ClusterVersionDeferral" }, "ClusterVersionDeferralPolicy.Type": { "description": " - NOT_DEFERRED: automatic patch version upgrades are applied immediately after release.\n - DEFERRAL_60_DAYS: automatic patch version upgrades are applied in a maintenance window at\nleast 60 days after the patch version release date.\n - FIXED_DEFERRAL: Deprecated: FIXED_DEFERRAL is equivalent to DEFERRAL_60_DAYS. It will be\nremoved in a future version.\n - DEFERRAL_30_DAYS: automatic patch version upgrades are applied in a maintenance window at\nleast 30 days after the patch version release date.\n - DEFERRAL_90_DAYS: automatic patch version upgrades are applied in a maintenance window at\nleast 90 days after the patch version release date.", "type": "string", "enum": [ "NOT_DEFERRED", "DEFERRAL_60_DAYS", "FIXED_DEFERRAL", "DEFERRAL_30_DAYS", "DEFERRAL_90_DAYS" ] }, "ClusterVersionDeferralUpdate": { "type": "object", "properties": { "deferral_policy": { "$ref": "#/components/schemas/ClusterVersionDeferralPolicy.Type" }, "deferred_until": { "description": "Deprecated: This field is ignored and will be removed in a future version.", "type": "string", "format": "date-time" } }, "example": { "deferral_policy": "DEFERRAL_60_DAYS" }, "required": ["deferral_policy"], "title": "ClusterVersionDeferralUpdate" }, "CockroachCloudServicePrincipals": { "type": "object", "properties": { "aws": { "$ref": "#/components/schemas/Aws" }, "azure": { "$ref": "#/components/schemas/Azure" }, "gcp": { "$ref": "#/components/schemas/Gcp" } } }, "ConnectionStringParameters": { "description": "Individual parameters used to create a connection string.", "type": "object", "properties": { "Database": { "type": "string" }, "Host": { "type": "string" }, "Port": { "type": "string" }, "Username": { "type": "string" } }, "required": ["Host", "Port", "Database"] }, "CreateApiKeyRequest": { "type": "object", "properties": { "name": { "description": "The name of the api key.", "type": "string", "example": "example name" }, "service_account_id": { "description": "The ID of the service account to create the api key for.", "type": "string", "format": "uuid", "example": "1234abcd-1234-1234-abcd-12345678abcd" } }, "example": { "name": "example name", "service_account_id": "1234abcd-1234-1234-abcd-12345678abcd" }, "required": ["name", "service_account_id"] }, "CreateApiKeyResponse": { "type": "object", "properties": { "api_key": { "$ref": "#/components/schemas/ApiKey" }, "secret": { "description": "The full api key. This is the value that would be passed in the\nAuthorization header. It is not stored by the backend and is therefore not\nrecoverable if lost.", "type": "string", "format": "password", "example": "CCDB1_12345abcdefGHIJKLMnopq_NkdXLI9d81Mnx3djs45iwPfgtnaRv0XCh0Z9047K" } }, "required": ["api_key", "secret"] }, "CreateBlackoutWindowBody": { "type": "object", "properties": { "end_time": { "description": "The end time of the blackout window (UTC).\nCan be up to 14 days after the start time.\nMust not be more than three months after the current time.", "type": "string", "format": "date-time" }, "start_time": { "description": "The start time of the blackout window (UTC).\nMust be scheduled at least 7 days in advance.", "type": "string", "format": "date-time" } }, "example": { "cluster_id": "12345678-1234-1234-1234-123456789012", "end_time": "2025-10-15T06:00:00Z", "start_time": "2025-10-15T00:00:00Z" }, "required": ["start_time", "end_time"], "title": "CreateBlackoutWindowRequest" }, "CreateClusterRequest": { "type": "object", "properties": { "name": { "description": "Name must be 6-20 characters in length and can include numbers,\nlowercase letters, and dashes (but no leading or trailing dashes).", "type": "string" }, "provider": { "$ref": "#/components/schemas/CloudProvider.Type" }, "spec": { "$ref": "#/components/schemas/CreateClusterSpecification" } }, "example": { "name": "test-cluster", "plan": "STANDARD", "provider": "GCP", "spec": { "serverless": { "regions": ["us-central1"], "usage_limits": { "provisioned_virtual_cpus": "2" } } } }, "required": ["name", "provider", "spec"], "title": "CreateClusterRequest" }, "CreateClusterSpecification": { "type": "object", "properties": { "customer_cloud_account": { "$ref": "#/components/schemas/CustomerCloudAccount" }, "dedicated": { "$ref": "#/components/schemas/DedicatedClusterCreateSpecification" }, "delete_protection": { "$ref": "#/components/schemas/DeleteProtectionState.Type" }, "labels": { "description": "labels are key-value pairs used to organize and categorize resources.", "type": "object", "additionalProperties": { "type": "string" } }, "parent_id": { "description": "Preview: The parent ID is a folder ID. An empty string or \"root\"\nwill create a cluster at the root level.", "type": "string" }, "plan": { "$ref": "#/components/schemas/Plan.Type" }, "serverless": { "$ref": "#/components/schemas/ServerlessClusterCreateSpecification" } } }, "CreateDatabaseBody": { "type": "object", "properties": { "name": { "type": "string" } }, "example": { "name": "example_database_name" }, "required": ["name"], "title": "CreateDatabaseRequest" }, "CreateEgressPrivateEndpointBody": { "type": "object", "properties": { "region": { "description": "region represents the region that the endpoint will be created in.", "type": "string" }, "target_service_identifier": { "description": "target_service_identifier represents the identifier of the target service.\nUser-visible in CRL and CSP consoles as the \"thing\" the user is telling us to connect to,\ni.e. Service Name for AWS, Service Attachment for GCP, or ARN for AWS MSK.", "type": "string" }, "target_service_type": { "$ref": "#/components/schemas/EgressPrivateEndpointTargetServiceType.Type" } }, "example": { "region": "us-east-1", "target_service_identifier": "arn:aws:s3:::example-bucket", "target_service_type": "MSK_SASL_IAM" }, "required": [ "region", "target_service_identifier", "target_service_type" ], "title": "CreateEgressPrivateEndpointRequest" }, "CreateFolderRequest": { "type": "object", "properties": { "labels": { "description": "labels are key-value pairs used to organize and categorize resources.", "type": "object", "additionalProperties": { "type": "string" } }, "name": { "type": "string" }, "parent_id": { "description": "The parent ID is a folder ID. An empty string or \"root\"\nwill create a folder at the root level.", "type": "string" } }, "example": { "name": "folder_name", "parent_id": "12345678-1234-1234-1234-123456789012" }, "required": ["name"], "title": "CreateFolderRequest" }, "CreateGroupRequest": { "type": "object", "properties": { "displayName": { "type": "string" }, "externalId": { "type": "string" }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/ScimResource" } }, "schemas": { "type": "array", "items": { "type": "string" } } }, "example": { "displayName": "Test SCIM", "members": [], "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"] }, "required": ["schemas", "displayName"], "title": "CreateGroupRequest" }, "CreatePhysicalReplicationStreamRequest": { "type": "object", "properties": { "primary_cluster_id": { "description": "primary_cluster_id is the ID of the cluster that is being\nreplicated.", "type": "string" }, "standby_cluster_id": { "description": "standby_cluster_id is the ID of the cluster that data is being replicated to.", "type": "string" } }, "required": ["primary_cluster_id", "standby_cluster_id"] }, "CreateRestoreBody": { "type": "object", "properties": { "backup_id": { "description": "The ID of the backup from which data will be restored.\nIf backup_id is not set, the restore will use the latest\navailable backup from source_cluster_id.", "type": "string" }, "objects": { "description": "The list of objects to restore. Required when type is DATABASE\nor TABLE.", "type": "array", "items": { "$ref": "#/components/schemas/RestoreItem" } }, "restore_opts": { "$ref": "#/components/schemas/RestoreOpts" }, "source_cluster_id": { "description": "The ID of the cluster containing the backup to be restored.", "type": "string" }, "type": { "$ref": "#/components/schemas/RestoreType.Type" } }, "example": { "backup_id": "1234abcd-1234-1234-abcd-12345678abcd", "destination_cluster_id": "12345678-1234-1234-1234-123456789012", "objects": [ { "database": "database1", "schema": "schema1", "table": "table1" }, { "database": "database1", "schema": "schema1", "table": "table2" } ], "restore_opts": { "into_db": "database2", "schema_only": true }, "type": "TABLE" }, "required": ["type"] }, "CreateSQLUserBody": { "type": "object", "properties": { "name": { "type": "string" }, "password": { "type": "string" } }, "example": { "name": "example_username", "password": "example_password" }, "required": ["name", "password"], "title": "CreateSQLUserRequest" }, "CreateServiceAccountRequest": { "type": "object", "properties": { "description": { "description": "description of the service account.", "type": "string" }, "name": { "description": "name of the service account.", "type": "string" }, "roles": { "description": "roles that are assigned to the service account.", "type": "array", "items": { "$ref": "#/components/schemas/BuiltInRole" } } }, "example": { "description": "", "name": "new name", "roles": [ { "name": "CLUSTER_ADMIN", "resource": { "type": "ORGANIZATION" } } ] }, "required": ["name", "description", "roles"] }, "CreateUserRequest": { "type": "object", "properties": { "active": { "type": "boolean" }, "displayName": { "type": "string" }, "emails": { "type": "array", "items": { "$ref": "#/components/schemas/ScimEmail" } }, "externalId": { "type": "string" }, "name": { "$ref": "#/components/schemas/ScimName" }, "schemas": { "type": "array", "items": { "type": "string" } }, "userName": { "type": "string" } }, "example": { "active": true, "displayName": "Carl Roach", "emails": [ { "primary": true, "type": "work", "value": "croach@example.com" } ], "externalId": "11ujl29u0le5T6Aj10h9", "name": { "familyName": "Roach", "givenName": "Carl" }, "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], "userName": "croach@example.com" }, "required": ["schemas", "emails"], "title": "CreateUserRequest" }, "CreateUserResponse": { "description": "Response when creating a new user via SCIM 2.0", "type": "object", "properties": { "active": { "type": "boolean" }, "displayName": { "type": "string" }, "emails": { "type": "array", "items": { "$ref": "#/components/schemas/ScimEmail" } }, "externalId": { "type": "string" }, "groups": { "type": "array", "items": { "$ref": "#/components/schemas/ScimResource" } }, "id": { "type": "string" }, "meta": { "$ref": "#/components/schemas/ScimMetadata" }, "name": { "$ref": "#/components/schemas/ScimName" }, "schemas": { "type": "array", "items": { "type": "string" } }, "userName": { "type": "string" } }, "required": ["schemas", "id"], "title": "CreateUserResponse" }, "Currency.Type": { "type": "string", "enum": ["USD", "CRDB_CLOUD_CREDITS"] }, "CurrencyAmount": { "type": "object", "properties": { "amount": { "description": "amount is the quantity of currency. Internally, currency amounts are tracked\nand stored using an arbitrary-precision decimal representation, but are serialized\nas 64-bit floating point numbers. There may be minor rounding discrepancies\nwhen parsed as a 32-bit float.", "type": "number", "format": "double" }, "currency": { "$ref": "#/components/schemas/Currency.Type" } } }, "CustomerCloudAccount": { "type": "object", "properties": { "aws": { "$ref": "#/components/schemas/AwsCustomerCloudAccount" }, "azure": { "$ref": "#/components/schemas/AzureCustomerCloudAccount" }, "gcp": { "$ref": "#/components/schemas/GcpCustomerCloudAccount" } } }, "Database": { "type": "object", "properties": { "name": { "type": "string" }, "table_count": { "type": "string", "format": "int64" } }, "required": ["name"], "title": "Database" }, "DatadogMetricExportInfo": { "type": "object", "properties": { "api_key": { "description": "api_key is the last 4 digits of a Datadog API key.", "type": "string" }, "cluster_id": { "type": "string" }, "site": { "$ref": "#/components/schemas/DatadogSite.Type" }, "status": { "$ref": "#/components/schemas/MetricExportStatus.Type" }, "user_message": { "type": "string" } }, "required": ["cluster_id", "site"], "title": "DatadogMetricExportInfo" }, "DatadogSite.Type": { "type": "string", "enum": ["US1", "US3", "US5", "US1_GOV", "EU1"] }, "DedicatedClusterCreateSpecification": { "type": "object", "properties": { "cidr_range": { "description": "cidr_range is the IPv4 range in CIDR format that will be used by the\ncluster. This is supported only on GCP, and must have a subnet mask no larger\nthan /19. Defaults to \"172.28.0.0/14\".", "type": "string" }, "cockroach_version": { "description": "The CockroachDB major version for the cluster. i.e. v24.1 The latest\nversion is used if omitted. The version passed must be one of the currently\nsupported versions.", "type": "string" }, "hardware": { "$ref": "#/components/schemas/DedicatedHardwareCreateSpecification" }, "network_visibility": { "$ref": "#/components/schemas/NetworkVisibility.Type" }, "region_machine_specs": { "description": "region_machine_specs configures a machine type per region, producing a\ncluster whose regions may use different machine types. Keys are region\ncodes (matching region_nodes) and values select a machine type by\nmachine_type or num_virtual_cpus. When set, every region in region_nodes\nmust have a corresponding entry, and hardware.machine_spec must be\nomitted (the two fields are mutually exclusive). hardware.storage_gib\nand hardware.disk_iops continue to apply cluster-wide.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/DedicatedMachineTypeSpecification" } }, "region_nodes": { "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.", "type": "object", "additionalProperties": { "format": "int32", "type": "integer" } }, "restrict_egress_traffic": { "description": "Preview: restrict_egress_traffic if set, results in an egress traffic policy of\ndefault-deny at creation time.", "type": "boolean" }, "supports_cluster_virtualization": { "type": "boolean", "title": "supports_cluster_virtualization specifies whether an Advanced\ncluster is started with a virtual cluster architecture. This field\nis restricted to Limited Access usage; see our documentation for\ndetails:\nhttps://www.cockroachlabs.com/docs/stable/cluster-virtualization-overview" } }, "required": ["region_nodes", "hardware"] }, "DedicatedClusterUpdateSpecification": { "type": "object", "properties": { "cmek_region_specs": { "description": "This field should contain the CMEK specs for newly added regions. If a\nCMEK spec is provided for an existing region, the request is invalid and\nwill fail.", "type": "array", "items": { "$ref": "#/components/schemas/CMEKRegionSpecification" } }, "hardware": { "$ref": "#/components/schemas/DedicatedHardwareUpdateSpecification" }, "region_machine_specs": { "description": "region_machine_specs updates machine types per region. Only regions named\nin this map are affected; unnamed regions retain their current machine\ntype. Use this to add a new region with a distinct machine type or to\nresize an existing region independently of others. Mutually exclusive\nwith hardware.machine_spec.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/DedicatedMachineTypeSpecification" } }, "region_nodes": { "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.", "type": "object", "additionalProperties": { "format": "int32", "type": "integer" } } } }, "DedicatedHardwareConfig": { "type": "object", "properties": { "disk_iops": { "description": "disk_iops is the number of disk I/O operations per second that are\npermitted on each node in the cluster. This value reflects the\nactual provisioned IOPS, which may differ from the value specified\nduring cluster creation or update. Only AWS clusters support\nuser-specified IOPS; for GCP and Azure clusters, IOPS is\ndetermined by the cloud provider based on disk size. A value of\nzero indicates the cloud provider-specific default.", "type": "integer", "format": "int32" }, "machine_type": { "description": "machine_type is the machine type identifier within the given cloud\nprovider, ex. m5.xlarge, n2-standard-4.", "type": "string" }, "memory_gib": { "description": "memory_gib is the memory GiB per node in the cluster.", "type": "number", "format": "float" }, "num_virtual_cpus": { "description": "num_virtual_cpus is the number of virtual CPUs per node in the cluster.", "type": "integer", "format": "int32" }, "storage_gib": { "description": "storage_gib is the number of storage GiB per node in the cluster.", "type": "integer", "format": "int32" } }, "required": [ "machine_type", "num_virtual_cpus", "storage_gib", "memory_gib", "disk_iops" ] }, "DedicatedHardwareCreateSpecification": { "description": "Exactly one of machine_spec or DedicatedClusterCreateSpecification.region_machine_specs must be provided. For the standard (non-limited-access) cluster creation flow, machine_spec is effectively required; it may only be omitted by callers using the limited-access region_machine_specs field.", "type": "object", "properties": { "disk_iops": { "description": "disk_iops is the number of disk I/O operations per second that are\npermitted on each node in an AWS cluster. Set to zero or omit this\nfield to use the cloud provider-specific default based on machine\ntype and storage size. The value returned in the response may differ\nfrom the requested value. For GCP and Azure clusters, this value is\nignored and the cloud provider default is used.", "type": "integer", "format": "int32" }, "machine_spec": { "$ref": "#/components/schemas/DedicatedMachineTypeSpecification" }, "storage_gib": { "description": "storage_gib is the number of storage GiB per node in the cluster.\nZero indicates default to the lowest storage GiB available given machine specs.", "type": "integer", "format": "int32" } }, "required": ["storage_gib"] }, "DedicatedHardwareUpdateSpecification": { "type": "object", "properties": { "disk_iops": { "description": "disk_iops is the number of disk I/O operations per second that are\npermitted on each node in an AWS cluster. Set to zero or omit this\nfield to use the cloud provider-specific default based on machine\ntype and storage size. The value returned in the response may differ\nfrom the requested value. For GCP and Azure clusters, this value is\nignored and the cloud provider default is used.", "type": "integer", "format": "int32" }, "machine_spec": { "$ref": "#/components/schemas/DedicatedMachineTypeSpecification" }, "storage_gib": { "description": "storage_gib is the number of storage GiB per node in the cluster.", "type": "integer", "format": "int32" } } }, "DedicatedMachineTypeSpecification": { "type": "object", "properties": { "machine_type": { "description": "machine_type is the machine type identifier within the given cloud\nprovider, ex. m5.xlarge, n2-standard-4.", "type": "string" }, "num_virtual_cpus": { "description": "num_virtual_cpus may be used to automatically select a machine type\naccording to the desired number of vCPUs.", "type": "integer", "format": "int32" } } }, "DeleteEgressRuleResponse": { "type": "object", "properties": { "Rule": { "$ref": "#/components/schemas/EgressRule" } }, "required": ["rule"], "title": "DeleteEgressRuleResponse" }, "DeleteMetricExportResponse": { "type": "object", "properties": { "cluster_id": { "type": "string" }, "status": { "$ref": "#/components/schemas/MetricExportStatus.Type" } }, "required": ["cluster_id"], "title": "DeleteMetricExportResponse" }, "DeleteProtectionState.Type": { "type": "string", "enum": ["ENABLED", "DISABLED"] }, "EditDatabaseBody": { "type": "object", "properties": { "name": { "type": "string" }, "new_name": { "type": "string" } }, "example": { "name": "example_database_name", "new_name": "example_new_database_name" }, "required": ["new_name", "name"], "title": "UpdateDatabaseRequest" }, "EditEgressRuleBody": { "type": "object", "properties": { "description": { "description": "description is text that serves to document the rules purpose.", "type": "string" }, "destination": { "description": "destination is a CIDR range or fully-qualified domain name to which\noutgoing traffic should be allowed. This field is required.", "type": "string" }, "idempotency_key": { "description": "idempotency_key uniquely identifies this request. If not set, it will be\nset by the server.", "type": "string" }, "paths": { "description": "Deprecated: This field is ignored and will be removed in the next version.\npaths are the allowed URL paths. If empty, all paths are allowed. Only\nvalid if Type=\"FQDN\".", "type": "array", "items": { "type": "string" } }, "ports": { "description": "ports are the allowed ports for TCP protocol. If empty, all ports are\nallowed.", "type": "array", "items": { "format": "int32", "type": "integer" } }, "type": { "description": "type is the destination type of this rule. Example values are\nFQDN or CIDR. This field is required.", "type": "string" } }, "example": { "cluster_id": "35c4abb2-bb66-46d7-afed-25ebef5ed100", "ports": [443, 80], "rule_id": "35c4abb2-bb66-46d7-afed-25ebef5ed2aa" }, "title": "EditEgressRuleRequest" }, "EditEgressRuleResponse": { "type": "object", "properties": { "Rule": { "$ref": "#/components/schemas/EgressRule" } }, "required": ["rule"], "title": "EditEgressRuleResponse" }, "EgressPrivateEndpoint": { "type": "object", "properties": { "domain_names": { "description": "domain_names are the domain names associated with the egress private endpoint.", "type": "array", "items": { "type": "string" } }, "domain_names_state": { "$ref": "#/components/schemas/EgressPrivateEndpointDomainNamesState.Type" }, "endpoint_address": { "type": "string", "title": "endpoint_address is the cloud-provider generated address (either\nIP address or DNS name) through which the endpoint is accessible" }, "endpoint_connection_id": { "description": "endpoint_connection_id is the cloud-specific id for egress private endpoints.\nThis connection ID is visible in CRL and CSP consoles as \"VPC endpoint ID\" and\nis used to uniquely identify the endpoint in external configurations.", "type": "string" }, "id": { "description": "A generated ID that uniquely identifies the egress_private_endpoint\nfor use with the CockroachDB Cloud API. This ID is generic and not specific\nto the cloud provider.", "type": "string" }, "region": { "description": "region represents the cloud region that the endpoint was created in.", "type": "string" }, "state": { "$ref": "#/components/schemas/EgressPrivateEndpointState.Type" }, "target_service_identifier": { "description": "target_service_identifier represents the identifier of the target service.\nUser-visible in CRL and CSP consoles as the \"thing\" the user is telling us to connect to,\ni.e. Service Name for AWS, Service Attachment for GCP, or ARN for AWS MSK.", "type": "string" }, "target_service_type": { "$ref": "#/components/schemas/EgressPrivateEndpointTargetServiceType.Type" } }, "required": [ "id", "endpoint_connection_id", "region", "target_service_identifier", "target_service_type", "endpoint_address", "state", "domain_names" ], "title": "EgressPrivateEndpoint" }, "EgressPrivateEndpointDomainNamesState.Type": { "type": "string", "enum": ["EMPTY", "PENDING", "AVAILABLE", "FAILED"], "title": "- EMPTY: EMPTY indicates that there are no egress private endpoint domain names on the cluster\n - PENDING: PENDING indicates that the domain names are currently being applied on the cluster\n - AVAILABLE: AVAILABLE indicates that the domain names have been applied on the cluster\n - FAILED: FAILED indicates that the domain names have failed to apply on the cluster" }, "EgressPrivateEndpointState.Type": { "type": "string", "enum": [ "PENDING", "PENDING_ACCEPTANCE", "AVAILABLE", "DELETING", "DELETED", "REJECTED", "FAILED", "EXPIRED" ] }, "EgressPrivateEndpointTargetServiceType.Type": { "type": "string", "enum": [ "PRIVATE_SERVICE", "MSK_SASL_SCRAM", "MSK_SASL_IAM", "MSK_TLS" ], "title": "- PRIVATE_SERVICE: PRIVATE_SERVICE represents any private service, such as a GCP service attachment, or an AWS VPC endpoint service.\n - MSK_SASL_SCRAM: MSK_SASL_SCRAM represents the managed Kafka service in AWS, with SASL/SCRAM auth\n - MSK_SASL_IAM: MSK_SASL_IAM represents the managed Kafka service in AWS, with SASL/IAM auth\n - MSK_TLS: MSK_TLS represents the managed Kafka service in AWS, with TLS auth" }, "EgressRule": { "description": "EgressRule represents a network egress rule.", "type": "object", "properties": { "cluster_id": { "description": "cluster_id identifies the cluster to which this egress rule applies.", "type": "string" }, "created_at": { "description": "created_at is the time at which the time at which the egress rule was\ncreated.", "type": "string", "format": "date-time" }, "crl_managed": { "description": "crl_managed indicates this egress rule is managed by CockroachDB Cloud\nservices. This field is set by the server.", "type": "boolean" }, "description": { "description": "description is a longer that serves to document the rules purpose.", "type": "string" }, "destination": { "description": "destination is the endpoint (or subnetwork if CIDR) to which traffic is\nallowed.", "type": "string" }, "id": { "description": "id uniquely identifies this egress rule.", "type": "string" }, "name": { "description": "name is the name of the egress rule.", "type": "string" }, "paths": { "description": "Deprecated: This field is ignored and will be removed in the next version.\npaths are the allowed URL paths. Only valid if Type=\"FQDN\".", "type": "array", "items": { "type": "string" } }, "ports": { "description": "ports are the allowed ports for TCP protocol. If Empty, all ports are\nallowed.", "type": "array", "items": { "format": "int32", "type": "integer" } }, "state": { "description": "state indicates the state of the egress rule.", "type": "string" }, "type": { "description": "type classifies the destination field. Valid types include: \"FQDN\",\n\"CIDR\".", "type": "string" } }, "required": [ "name", "id", "cluster_id", "type", "state", "crl_managed", "destination", "description" ], "title": "EgressRule" }, "EgressTrafficPolicy.Type": { "description": " - UNSPECIFIED: UNSPECIFIED signifies the egress traffic policy is unspecified.\n - ERROR: ERROR signifies there has been an internal server error during\nan update to the egress traffic policy.\n - ALLOW_ALL: ALLOW_ALL signifies all outbound connections from CockroachDB are allowed.\n - DEFAULT_DENY: DEFAULT_DENY signifies that CockroachDB can only initiate network\nconnections to destinations explicitly allowed by the user or CockroachDB\nCloud operators.\n - UPDATING: UPDATING signifies the egress traffic policy is updating.", "type": "string", "enum": [ "UNSPECIFIED", "ERROR", "ALLOW_ALL", "DEFAULT_DENY", "UPDATING" ] }, "EnableCMEKSpecBody": { "type": "object", "properties": { "region_specs": { "type": "array", "items": { "$ref": "#/components/schemas/CMEKRegionSpecification" } } }, "example": { "region_specs": [ { "key_spec": { "auth_principal": "arn:aws:iam::account:role/role-name-with-path", "type": "AWS_KMS", "uri": "arn:aws:kms:us-west-2:111122223333:key/id-of-kms-key" }, "region": "us-central1" } ] }, "required": ["region_specs"], "title": "CMEKClusterSpecification" }, "EnableCloudWatchMetricExportBody": { "type": "object", "properties": { "external_id": { "description": "external_id to include when assuming the IAM role specified by role_arn.\nOptional. A specific value may be required by the role's trust policy.\nOnly supported for Advanced clusters. If provided for a Standard cluster,\nthe request is rejected.", "type": "string" }, "log_group_name": { "description": "log_group_name is the customized log group name.", "type": "string" }, "role_arn": { "description": "role_arn is the IAM role used to upload metric segments to the\ntarget AWS account.", "type": "string" }, "target_region": { "description": "target_region specifies the specific AWS region that the metrics will\nbe exported to.", "type": "string" } }, "example": { "external_id": "example_external_id", "log_group_name": "example", "role_arn": "arn:aws:iam::account:role/ExampleRole", "target_region": "us-east-1" }, "required": ["role_arn"], "title": "EnableCloudWatchMetricExportRequest" }, "EnableDatadogMetricExportBody": { "type": "object", "properties": { "api_key": { "description": "api_key is a Datadog API key.", "type": "string" }, "site": { "$ref": "#/components/schemas/DatadogSite.Type" } }, "example": { "api_key": "datadog_api_key", "site": "US1" }, "required": ["site", "api_key"], "title": "EnableDatadogMetricExportRequest" }, "EnableLogExportBody": { "type": "object", "properties": { "auth_principal": { "type": "string", "title": "auth_principal is used in different contexts based on integration.\nCloudWatch: AWS Role ARN that identifies a role\nthat the cluster account can assume to write to CloudWatch\nGCP Cloud Logging: GCP Project ID that the cluster service account\nhas permissions to write to for cloud logging.\nAzure Log Analytics: CustomerID or WorkspaceID" }, "aws_external_id": { "description": "aws_external_id to include when assuming the IAM role specified by role_arn.\nOptional. A specific value may be required by the role's trust policy.\nOnly supported for Advanced clusters on AWS. If provided for a Standard cluster,\nthe request is rejected.", "type": "string" }, "azure_shared_key": { "description": "The primary or the secondary connected sources client authentication key.\nThis is used to export logs to Azure Log Analytics.", "type": "string" }, "groups": { "description": "groups is a collection of log group configurations that allows the\ncustomer to define collections of CRDB log channels that are aggregated\nseparately at the target sink.", "type": "array", "items": { "$ref": "#/components/schemas/LogExportGroup" } }, "log_name": { "description": "log_name is an identifier for the logs in the customer's log sink.", "type": "string" }, "omitted_channels": { "description": "omitted_channels is a list of channels that the user does not want to\nexport logs for.", "type": "array", "items": { "type": "string" } }, "redact": { "description": "redact allows the customer to set a default redaction policy for\nlogs before they are exported to the target sink. If a group config\nomits a redact flag and this one is set to `true`, then that group\nwill receive redacted logs.", "type": "boolean" }, "region": { "description": "region allows the customer to override the destination region for\nall logs for a cluster.", "type": "string" }, "type": { "$ref": "#/components/schemas/LogExportType" } }, "example": { "auth_principal": "my-gcp-project-id", "groups": [ { "channels": ["OPS", "HEALTH"], "log_name": "devops", "min_level": "WARNING" } ], "log_name": "default", "omitted_channels": ["SESSIONS", "SQL_PERF"], "redact": true, "shared_key": "shared-key", "type": "GCP_CLOUD_LOGGING" }, "required": ["type", "log_name", "auth_principal"], "title": "EnableLogExportRequest" }, "FolderResource": { "description": "FolderResource describes a resource, and includes info about its lineage (parent/ancestors).", "type": "object", "properties": { "labels": { "description": "labels are key-value pairs used to organize and categorize resources.", "type": "object", "additionalProperties": { "type": "string" } }, "name": { "description": "name is the resource's name.", "type": "string" }, "organization_id": { "description": "organization_id is the id of the organization this resource belongs to.", "type": "string" }, "parent_id": { "description": "parent_id is the id of the resource's parent folder.\n\"root\" represents a root level resource.", "type": "string" }, "path": { "description": "path contains the ids and names of ancestors that make up the resource's lineage.", "type": "array", "items": { "$ref": "#/components/schemas/PathSegment" } }, "resource_id": { "description": "resource_id is the resource's id.", "type": "string" }, "resource_type": { "$ref": "#/components/schemas/FolderResourceType.Type" } }, "required": [ "resource_id", "resource_type", "parent_id", "organization_id", "name", "path", "labels" ], "title": "FolderResource" }, "FolderResourceList": { "description": "FolderResourceList contains a list of resources.", "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/KeysetPaginationResponse" }, "resources": { "type": "array", "items": { "$ref": "#/components/schemas/FolderResource" } } } }, "FolderResourceType.Type": { "type": "string", "enum": ["FOLDER", "CLUSTER"] }, "Gcp": { "type": "object", "properties": { "service_account_email": { "type": "string", "title": "GCP service account email used by CockroachDB Cloud" } } }, "GcpCustomerCloudAccount": { "type": "object", "properties": { "service_account_email": { "description": "The customer-owned GCP service account email. This is the principal\nthat will be impersonated by CockroachDB Cloud to perform actions in\nthe customer-owned GCP project. The service account email contains\nthe project ID, so CockroachDB Cloud doesn't require it to be passed\nseparately.", "type": "string" } }, "required": ["service_account_email"] }, "GetAllRolesForUserResponse": { "type": "object", "properties": { "group_roles": { "type": "array", "items": { "$ref": "#/components/schemas/BuiltInFromGroups" } }, "roles": { "type": "array", "items": { "$ref": "#/components/schemas/BuiltInRole" } } } }, "GetConnectionStringResponse": { "type": "object", "properties": { "connection_string": { "description": "connection_string contains the full connection string with parameters formatted inline.", "type": "string" }, "params": { "$ref": "#/components/schemas/ConnectionStringParameters" } }, "required": ["connection_string", "params"] }, "GetEgressRuleResponse": { "type": "object", "properties": { "rule": { "$ref": "#/components/schemas/EgressRule" } }, "required": ["rule"], "title": "GetEgressRuleResponse" }, "GetGroup2Body": { "type": "object", "properties": { "attributes": { "type": "string" }, "excludedAttributes": { "type": "string" } }, "title": "GetGroupRequest" }, "GetGroupsRequest": { "type": "object", "properties": { "attributes": { "type": "string" }, "count": { "description": "The maximum number of resources to return. If omitted, defaults to 20.\nIf set to 0, the response will contain no resources but will include metadata such as\n`totalResults`, complying with [RFC 7644, Section 3.4.2.4: Pagination](https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2.4).", "type": "integer", "format": "int32" }, "excludedAttributes": { "type": "string" }, "filter": { "type": "string" }, "startIndex": { "description": "The 1-based index of the first resource to return in the response.\nIf omitted or less than 1, defaults to 1. This behavior complies with [RFC 7644, Section 3.4.2.4: Pagination](https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2.4).", "type": "integer", "format": "int32" } }, "title": "GetGroupsRequest" }, "GetGroupsResponse": { "type": "object", "properties": { "Resources": { "type": "array", "items": { "$ref": "#/components/schemas/ScimGroup" } }, "itemsPerPage": { "type": "integer", "format": "int32" }, "schemas": { "type": "array", "items": { "type": "string" } }, "startIndex": { "type": "integer", "format": "int32" }, "totalResults": { "type": "integer", "format": "int32" } }, "required": ["schemas", "totalResults"], "title": "GetGroupsResponse" }, "GetPersonUsersByEmailResponse": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/PersonUserInfo" } }, "required": ["users"] }, "GetPrivateEndpointTrustedOwnerResponse": { "type": "object", "properties": { "trusted_owner": { "$ref": "#/components/schemas/PrivateEndpointTrustedOwner" } }, "required": ["trusted_owner"] }, "GetResourceTypesResponse": { "type": "object", "properties": { "Resources": { "type": "array", "items": { "$ref": "#/components/schemas/ScimResourceType" } }, "itemsPerPage": { "type": "integer", "format": "int32" }, "schemas": { "type": "array", "items": { "type": "string" } }, "startIndex": { "type": "integer", "format": "int32" }, "totalResults": { "type": "integer", "format": "int32" } }, "required": ["schemas", "totalResults"], "title": "GetResourceTypesResponse" }, "GetSchemasResponse": { "type": "object", "properties": { "Resources": { "type": "array", "items": { "$ref": "#/components/schemas/ScimSchema" } }, "itemsPerPage": { "type": "integer", "format": "int32" }, "schemas": { "type": "array", "items": { "type": "string" } }, "startIndex": { "type": "integer", "format": "int32" }, "totalResults": { "type": "integer", "format": "int32" } }, "required": ["schemas", "totalResults"], "title": "GetSchemasResponse" }, "GetServiceProviderConfigResponse": { "type": "object", "properties": { "authenticationSchemes": { "type": "array", "items": { "$ref": "#/components/schemas/ScimAuthenticationScheme" } }, "bulk": { "$ref": "#/components/schemas/ScimBulkSupport" }, "changePassword": { "$ref": "#/components/schemas/ScimChangePasswordSupport" }, "etag": { "$ref": "#/components/schemas/ScimEtagSupport" }, "filter": { "$ref": "#/components/schemas/ScimFilterSupport" }, "meta": { "$ref": "#/components/schemas/ScimMetadata" }, "schemas": { "type": "array", "items": { "type": "string" } }, "sort": { "$ref": "#/components/schemas/ScimSortSupport" } }, "required": [ "schemas", "bulk", "filter", "changePassword", "sort", "etag", "authenticationSchemes" ], "title": "GetServiceProviderConfigResponse" }, "GetUser2Body": { "type": "object", "properties": { "attributes": { "type": "string" }, "excludedAttributes": { "type": "string" } }, "title": "GetUserRequest" }, "GetUsersRequest": { "type": "object", "properties": { "attributes": { "type": "string" }, "count": { "description": "The maximum number of resources to return. If omitted, defaults to 20.\nIf set to 0, the response will contain no resources but will include metadata such as\n`totalResults`, complying with [RFC 7644, Section 3.4.2.4: Pagination](https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2.4).", "type": "integer", "format": "int32" }, "excludedAttributes": { "type": "string" }, "filter": { "type": "string" }, "startIndex": { "description": "The 1-based index of the first resource to return in the response.\nIf omitted or less than 1, defaults to 1. This behavior complies with [RFC 7644, Section 3.4.2.4: Pagination](https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2.4).", "type": "integer", "format": "int32" } }, "title": "GetUsersRequest" }, "GetUsersResponse": { "type": "object", "properties": { "Resources": { "type": "array", "items": { "$ref": "#/components/schemas/ScimUser" } }, "itemsPerPage": { "type": "integer", "format": "int32" }, "schemas": { "type": "array", "items": { "type": "string" } }, "startIndex": { "type": "integer", "format": "int32" }, "totalResults": { "type": "integer", "format": "int32" } }, "required": ["schemas", "totalResults"], "title": "GetUsersResponse" }, "Invoice": { "description": "Invoice message represents the details and the total charges associated with\none billing period, which starts at the beginning of the month and ends at\nthe beginning of the next month.\n\nThe message also includes details about each invoice item.", "type": "object", "properties": { "adjustments": { "description": "adjustments is a list of credits or costs that adjust the value of the\ninvoice (e.g. a Serverless Free Credit or Premium Support adjustment).\nUnlike line items, adjustments are not tied to a particular cluster.", "type": "array", "items": { "$ref": "#/components/schemas/InvoiceAdjustment" } }, "balances": { "description": "balances are the amounts of currency left at the time of the invoice.", "type": "array", "items": { "$ref": "#/components/schemas/CurrencyAmount" } }, "folder_resources": { "description": "Preview: FolderResources is a list of resources in the organization and their folder\npaths.", "type": "array", "items": { "$ref": "#/components/schemas/FolderResource" } }, "invoice_id": { "description": "invoice_id is the unique ID representing the invoice.", "type": "string" }, "invoice_items": { "description": "invoice_items are sorted by the cluster name.", "type": "array", "items": { "$ref": "#/components/schemas/InvoiceItem" } }, "period_end": { "description": "period_end is the end of the billing period (exclusive).", "type": "string", "format": "date-time" }, "period_start": { "description": "period_start is the start of the billing period (inclusive).", "type": "string", "format": "date-time" }, "status": { "$ref": "#/components/schemas/InvoiceStatus.Type" }, "totals": { "description": "totals is a list of the total amounts per currency.", "type": "array", "items": { "$ref": "#/components/schemas/CurrencyAmount" } } }, "required": [ "invoice_id", "totals", "period_start", "period_end", "invoice_items", "balances" ] }, "InvoiceAdjustment": { "type": "object", "properties": { "amount": { "$ref": "#/components/schemas/CurrencyAmount" }, "name": { "description": "name identifies the adjustment.", "type": "string" } }, "required": ["name", "amount"] }, "InvoiceItem": { "type": "object", "properties": { "cluster": { "$ref": "#/components/schemas/Cluster" }, "line_items": { "description": "line_items contain all the relevant line items from the Metronome invoice.", "type": "array", "items": { "$ref": "#/components/schemas/LineItem" } }, "totals": { "description": "totals is a list of the total amounts of line items per currency.", "type": "array", "items": { "$ref": "#/components/schemas/CurrencyAmount" } } }, "required": ["cluster", "totals", "line_items"] }, "InvoiceStatus.Type": { "type": "string", "enum": ["FINALIZED", "DRAFT"] }, "JWTIssuer": { "type": "object", "properties": { "audience": { "type": "string", "example": "1234567890abcd", "title": "The intended audience for consuming the JWT" }, "claim": { "type": "string", "example": "email", "title": "Used to identify the user from the external Identity Provider. Defaults to \"sub\"" }, "id": { "type": "string", "format": "uuid", "example": "1234abcd-1234-1234-abcd-12345678abcd", "title": "The unique identifier of the JWT Issuer resource" }, "identity_map": { "type": "array", "items": { "$ref": "#/components/schemas/JWTIssuerIdentityMapEntry" }, "title": "A list of mappings to map the external token identity into CockroachDB Cloud" }, "issuer_url": { "type": "string", "example": "https://jwt-issuer.example.com", "title": "The URL of the server issuing JWTs" }, "jwks": { "type": "string", "example": "{\"keys\":[{\"e\":\"AQAB\",\"use\":\"sig\",\"kty\":\"RSA\",\"alg\":\"RS256\",\"n\":\"tid8bJCI5FxtvMiVHq8pRZBGIPaG9mEa1akpIC9munzxA3mWoc-KoR1TGkocu76WFthaZnPS31WJbRVChU6g4EMIg7E8Ltpxifk1PQu0qqbLcpnoI62ojsB7l_Z_lkls0NUzTuKGMMtNoJsDrL1BT0UzcnWerh2PwzDAMpfPgafWdT2IYGTx1gNLcNOWpPhDgMSQqUmIPwCmxdan4i4OMd7lJYQ1WQlN8VnQgbRgHrm1zImY6MPqho9jW3Ub5FwGbunwCDrP9a2dD_5Iwm7_lR82iB4BGlu28WxFn0fm5DgZAeAFSGKE1xblC97WrjnPh2XYTx6pxsea_Hn71VcNSQ\",\"kid\":\"9341dedeee2d1869b657fa930300082fe26b3d92\"}]}", "title": "A set of public keys (JWKS) used to verify a JWT" } }, "required": ["id", "issuer_url", "audience"], "title": "JWTIssuer" }, "JWTIssuerIdentityMapEntry": { "type": "object", "properties": { "cc_identity": { "description": "Specifies how to map the fetched token identity to an identity in CockroachDB Cloud. In case of a regular\nexpression for token_identity, this must contain a \\1 placeholder for the matched content. Note that you will need\nto escape the backslash in the string as in the example usage (\\\\\\\\1).\nThe mapped identity must match with either a user email address or a service account ID.", "type": "string", "example": "\\1" }, "token_identity": { "description": "Specifies how to fetch external identity from the token claim. A regular expression must start\nwith a forward slash. The regular expression must be in RE2 compatible syntax. For further details, please see\nhttps://github.com/google/re2/wiki/Syntax.", "type": "string", "example": "/^sso_(.*)$" } }, "required": ["token_identity", "cc_identity"], "title": "JWTIssuerIdentityMapEntry" }, "KeysetPaginationResponse": { "type": "object", "properties": { "next_page": { "type": "string" }, "previous_page": { "type": "string" } } }, "LineItem": { "type": "object", "properties": { "description": { "description": "description contains the details of the line item (i.e t3 micro).", "type": "string" }, "quantity": { "description": "quantity is the number of the specific line items used.", "type": "number", "format": "double" }, "quantity_unit": { "$ref": "#/components/schemas/QuantityUnit.Type" }, "total": { "$ref": "#/components/schemas/CurrencyAmount" }, "unit_cost": { "description": "unit_cost is the cost per unit of line item.", "type": "number", "format": "double" } }, "required": [ "description", "quantity", "unit_cost", "total", "quantity_unit" ] }, "ListAllowlistEntriesResponse": { "type": "object", "properties": { "allowlist": { "type": "array", "items": { "$ref": "#/components/schemas/AllowlistEntry" } }, "pagination": { "$ref": "#/components/schemas/KeysetPaginationResponse" }, "propagating": { "type": "boolean" } }, "required": ["allowlist", "propagating"], "title": "ListAllowlistEntriesResponse" }, "ListApiKeysResponse": { "type": "object", "properties": { "api_keys": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } }, "pagination": { "$ref": "#/components/schemas/KeysetPaginationResponse" } }, "required": ["api_keys"] }, "ListAuditLogsResponse": { "type": "object", "properties": { "entries": { "description": "entries is the contiguous list of audit log entries matching the\npagination request, sorted in the order requested.", "type": "array", "items": { "$ref": "#/components/schemas/AuditLogEntry" } }, "next_starting_from": { "description": "next_starting_from is the timestamp the caller should use to continue\npaginating in the same direction. If the timestamp is unset, it means\nthat there are no more entries in the direction of the request, and\nthere never will be.", "type": "string", "format": "date-time" } } }, "ListAvailableRegionsResponse": { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/KeysetPaginationResponse" }, "regions": { "type": "array", "items": { "$ref": "#/components/schemas/CloudProviderRegion" } } }, "required": ["regions"] }, "ListBackupsResponse": { "type": "object", "properties": { "backups": { "type": "array", "items": { "$ref": "#/components/schemas/BackupSummary" } }, "pagination": { "$ref": "#/components/schemas/KeysetPaginationResponse" } }, "required": ["backups"] }, "ListBlackoutWindowsResponse": { "type": "object", "properties": { "blackout_windows": { "type": "array", "items": { "$ref": "#/components/schemas/BlackoutWindow" } }, "pagination": { "$ref": "#/components/schemas/KeysetPaginationResponse" } }, "title": "ListBlackoutWindowsResponse" }, "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"] }, "ListDatabasesResponse": { "type": "object", "properties": { "databases": { "type": "array", "items": { "$ref": "#/components/schemas/Database" } }, "pagination": { "$ref": "#/components/schemas/KeysetPaginationResponse" } }, "required": ["databases"], "title": "ListDatabasesResponse" }, "ListEgressPrivateEndpointsResponse": { "type": "object", "properties": { "egress_private_endpoints": { "description": "egress_private_endpoints are the egress private endpoints associated with the given cluster.", "type": "array", "items": { "$ref": "#/components/schemas/EgressPrivateEndpoint" } }, "pagination": { "$ref": "#/components/schemas/KeysetPaginationResponse" } }, "required": ["egress_private_endpoints"], "title": "ListEgressPrivateEndpointsResponse" }, "ListEgressRulesResponse": { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/KeysetPaginationResponse" }, "rules": { "description": "rules are the egress rules associated with the given CockroachDB cluster.", "type": "array", "items": { "$ref": "#/components/schemas/EgressRule" } } }, "title": "ListEgressRulesResponse" }, "ListFoldersResponse": { "type": "object", "properties": { "folders": { "type": "array", "items": { "$ref": "#/components/schemas/FolderResource" } }, "pagination": { "$ref": "#/components/schemas/KeysetPaginationResponse" } }, "required": ["folders"] }, "ListInvoicesResponse": { "type": "object", "properties": { "invoices": { "description": "invoices are sorted by period_start time.", "type": "array", "items": { "$ref": "#/components/schemas/Invoice" } } }, "required": ["invoices"] }, "ListJWTIssuersResponse": { "type": "object", "properties": { "jwt_issuers": { "type": "array", "items": { "$ref": "#/components/schemas/JWTIssuer" }, "title": "The list of JWT Issuer resources" }, "pagination": { "$ref": "#/components/schemas/KeysetPaginationResponse" } }, "title": "ListJWTIssuersResponse" }, "ListMajorClusterVersionsResponse": { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/KeysetPaginationResponse" }, "versions": { "type": "array", "items": { "$ref": "#/components/schemas/ClusterMajorVersion" } } }, "required": ["versions"] }, "ListPrivateEndpointTrustedOwnersResponse": { "type": "object", "properties": { "trusted_owners": { "description": "trusted_owners describes the private endpoint trusted owner entries for the\nrequested cluster.", "type": "array", "items": { "$ref": "#/components/schemas/PrivateEndpointTrustedOwner" } } } }, "ListRestoresResponse": { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/KeysetPaginationResponse" }, "restores": { "type": "array", "items": { "$ref": "#/components/schemas/Restore" } } }, "required": ["restores"] }, "ListRoleGrantsResponse": { "type": "object", "properties": { "grants": { "type": "array", "items": { "$ref": "#/components/schemas/UserRoleGrants" } }, "pagination": { "$ref": "#/components/schemas/KeysetPaginationResponse" }, "user_group_grants": { "type": "array", "items": { "$ref": "#/components/schemas/UserGroupRoleGrant" } } } }, "ListSQLUsersResponse": { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/KeysetPaginationResponse" }, "users": { "type": "array", "items": { "$ref": "#/components/schemas/SQLUser" } } }, "required": ["users"] }, "ListServiceAccountsResponse": { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/KeysetPaginationResponse" }, "service_accounts": { "type": "array", "items": { "$ref": "#/components/schemas/ServiceAccount" } } }, "required": ["service_accounts"] }, "LogExportClusterInfo": { "description": "LogExportClusterInfo contains a package of information that fully\ndescribes both the intended state of the log export configuration for\na specific cluster but also some metadata around its deployment\nstatus, any error messages, and some timestamps.", "type": "object", "properties": { "cluster_id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "spec": { "$ref": "#/components/schemas/LogExportClusterSpecification" }, "status": { "$ref": "#/components/schemas/LogExportStatus" }, "updated_at": { "type": "string", "format": "date-time" }, "user_message": { "type": "string" } } }, "LogExportClusterSpecification": { "description": "LogExportClusterSpecification contains all the data necessary to\nconfigure log export for an individual cluster. Users would supply\nthis data via the API and also receive it back when inspecting the\nstate of their log export configuration.", "type": "object", "properties": { "auth_principal": { "description": "auth_principal is either the AWS Role ARN that identifies a role\nthat the cluster account can assume to write to CloudWatch or the\nGCP Project ID that the cluster service account has permissions to\nwrite to for cloud logging.", "type": "string" }, "aws_external_id": { "description": "aws_external_id, if set, is included when assuming the IAM role. Supported for\nAdvanced clusters on AWS only.", "type": "string" }, "azure_shared_key": { "description": "The primary or the secondary connected sources client authentication key.\nThis is used to export logs to Azure Log Analytics.", "type": "string" }, "groups": { "description": "groups is a collection of log group configurations to customize\nwhich CRDB channels get aggregated into different groups at the\ntarget sink. Unconfigured channels will be sent to the default\nlocations via the settings above.", "type": "array", "items": { "$ref": "#/components/schemas/LogExportGroup" } }, "log_name": { "description": "log_name is an identifier for the logs in the customer's log sink.", "type": "string" }, "omitted_channels": { "description": "omitted_channels is a list of channels that the user does not want to\nexport logs for.", "type": "array", "items": { "type": "string" } }, "redact": { "description": "redact controls whether logs are redacted before forwarding to\ncustomer sinks. By default they are not redacted.", "type": "boolean" }, "region": { "description": "region controls whether all logs are sent to a specific region in\nthe customer sink. By default, logs will remain their region of\norigin depending on the cluster node's region.", "type": "string" }, "type": { "$ref": "#/components/schemas/LogExportType" } } }, "LogExportGroup": { "description": "LogExportGroup contains an export configuration for a single\nlog group which can route logs for a subset of CRDB channels.", "type": "object", "properties": { "channels": { "description": "channels is a list of CRDB log channels to include in this\ngroup.", "type": "array", "items": { "type": "string" } }, "enable_sending_queue": { "description": "enable_sending_queue enables the sending queue for logs in this\ngroup. Only one group can have enable_sending_queue enabled.", "type": "boolean" }, "log_name": { "description": "log_name is the name of the group, reflected in the log sink.", "type": "string" }, "min_level": { "$ref": "#/components/schemas/LogLevel.Type" }, "redact": { "description": "redact is a boolean that governs whether this log group\nshould aggregate redacted logs. Redaction settings will\ninherit from the cluster log export defaults if unset.", "type": "boolean" } }, "required": ["log_name", "channels"] }, "LogExportStatus": { "description": "LogExportStatus encodes the possible states that a configuration can\nbe in as it is created, deployed, and disabled.", "type": "string", "enum": [ "DISABLED", "DISABLING", "DISABLE_FAILED", "ENABLED", "ENABLING", "ENABLE_FAILED", "CREDENTIALS_ERROR" ] }, "LogExportType": { "description": "LogExportType encodes the cloud selection that we're exporting to\nalong with the cloud logging platform.\n\nCurrently, each cloud has a single logging platform.", "type": "string", "enum": ["AWS_CLOUDWATCH", "GCP_CLOUD_LOGGING", "AZURE_LOG_ANALYTICS"] }, "LogLevel.Type": { "description": " - UNSPECIFIED: The unspecified log level includes all logs.\n - WARNING: The WARNING severity is used for situations which may require\nspecial handling, where normal operation is expected to resume\nautomatically.\n - ERROR: The ERROR severity is used for situations that require special\nhandling, where normal operation could not proceed as expected.\nOther operations can continue mostly unaffected.\n - FATAL: The FATAL severity is used for situations that require an\nimmediate, hard server shutdown. A report is also sent to\ntelemetry if telemetry is enabled.", "type": "string", "enum": ["UNSPECIFIED", "WARNING", "ERROR", "FATAL"] }, "MaintenanceWindow": { "description": "MaintenanceWindowSpec specifies a weekly recurring maintenance window for an\nADVANCED cluster.", "type": "object", "properties": { "offset_duration": { "description": "OffsetDuration is the duration from the start of a week (Monday 00:00 UTC)\nthat this maintenance window will start after.\n\nMust be less than 1 week.", "type": "string" }, "window_duration": { "description": "WindowDuration is the duration of the maintenance window.\n\nMust be at least 6 hours and less than 1 week.", "type": "string" } }, "example": { "offset_duration": "172800s", "window_duration": "21600s" }, "required": ["offset_duration", "window_duration"], "title": "MaintenanceWindow" }, "MetricExportStatus.Type": { "type": "string", "enum": ["NOT_DEPLOYED", "DISABLING", "ENABLING", "ENABLED", "ERROR"] }, "NetworkVisibility.Type": { "type": "string", "enum": ["PUBLIC", "PRIVATE"] }, "Node": { "type": "object", "properties": { "name": { "type": "string" }, "region_name": { "type": "string" }, "status": { "$ref": "#/components/schemas/NodeStatus.Type" } }, "required": ["name", "region_name", "status"] }, "NodeStatus.Type": { "type": "string", "enum": ["LIVE", "NOT_READY"] }, "OperatingSystemType": { "type": "string", "enum": ["MAC", "LINUX", "WINDOWS"] }, "Organization": { "type": "object", "properties": { "cockroach_cloud_service_principals": { "$ref": "#/components/schemas/CockroachCloudServicePrincipals" }, "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string" }, "label": { "type": "string" }, "name": { "type": "string" } }, "required": ["id", "label", "name", "created_at"] }, "OrganizationUserRole.Type": { "description": " - FOLDER_ADMIN: Preview: A folder admin role.\n - FOLDER_MOVER: Preview: A folder mover role.", "type": "string", "enum": [ "BILLING_COORDINATOR", "ORG_ADMIN", "ORG_MEMBER", "CLUSTER_ADMIN", "CLUSTER_OPERATOR_WRITER", "CLUSTER_DEVELOPER", "CLUSTER_CREATOR", "FOLDER_ADMIN", "FOLDER_MOVER", "METRICS_VIEWER", "CLUSTER_MONITOR", "BILLING_VIEWER" ] }, "PatchGroupBody": { "type": "object", "properties": { "Operations": { "type": "array", "items": { "$ref": "#/components/schemas/ScimOperations" } }, "schemas": { "description": "A list of one or more URIs identifying SCIM schemas that define the structure\nof the attributes in the request. The only supported schema at this time is\n\"urn:ietf:params:scim:api:messages:2.0:PatchOp\".", "type": "array", "items": { "type": "string" } } }, "example": { "Operations": [ { "op": "replace", "path": "displayName", "value": "Updated Group Name" }, { "op": "replace", "path": "externalId", "value": "ext-123" }, { "op": "remove", "path": "members" }, { "op": "add", "path": "externalId", "value": "new-external-id" }, { "op": "add", "path": "members", "value": [ { "value": "45a35c27-23d3-4d03-c4c5-9043c09e7175" } ] } ], "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"] }, "required": ["schemas", "Operations"], "title": "PatchGroupRequest" }, "PatchUserBody": { "type": "object", "properties": { "Operations": { "type": "array", "items": { "$ref": "#/components/schemas/ScimOperations" } }, "schemas": { "description": "A list of one or more URIs identifying SCIM schemas that define the structure\nof the attributes in the request. The only supported schema at this time is\n\"urn:ietf:params:scim:api:messages:2.0:PatchOp\".", "type": "array", "items": { "type": "string" } } }, "example": { "Operations": [ { "op": "replace", "path": "userName", "value": "newUserName" }, { "op": "replace", "value": { "displayName": "New Name", "emails": [ { "primary": true, "value": "new@example.com" } ] } }, { "op": "remove", "path": "externalId" } ], "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"] }, "required": ["schemas", "Operations"], "title": "PatchUserRequest" }, "PathSegment": { "type": "object", "properties": { "id": { "description": "id is a folder id.", "type": "string" }, "name": { "description": "name is a folder name.", "type": "string" } } }, "PersonUserInfo": { "type": "object", "properties": { "email": { "description": "email is an email address.", "type": "string" }, "id": { "description": "id is the user id.", "type": "string" } }, "required": ["id"], "title": "person_user_info contains information about a person" }, "PhysicalReplicationStream": { "type": "object", "properties": { "activated_at": { "description": "activated_at is the crdb system time at which failover is\nfinalized. This may differ from the time for which failover was\nrequested. This field will be present when a replication stream is\nin the COMPLETED state.", "type": "string", "format": "date-time" }, "canceled_at": { "description": "canceled_at is the timestamp at which the replication stream was canceled.", "type": "string", "format": "date-time" }, "created_at": { "description": "created_at is the timestamp at which the replication stream was\ncreated.", "type": "string", "format": "date-time" }, "failover_at": { "description": "failover_at is the time for which failover is requested. If the user\nsets the status to 'FAILING_OVER' but omits failover_at, the failover\ntime will default to the latest consistent replicated time.\nOtherwise, the user can pick a time up to one hour in the future to\nschedule a failover, or a time in the past to restore the cluster to\na recent state. This field will be present if the user has\nrequested failover at a future time.", "type": "string", "format": "date-time" }, "id": { "description": "id is the UUID of the replication stream.", "type": "string" }, "primary_cluster_id": { "description": "primary_cluster_id is the ID of the cluster that is being replicated.", "type": "string" }, "replicated_time": { "description": "replicated_time is the timestamp indicating the point up to which\ndata has been replicated. The window between replicated_time and\nthe actual time is known as replication lag. This field will be\npresent when a replication stream is in the REPLICATING state.", "type": "string", "format": "date-time" }, "replication_lag_seconds": { "description": "replication_lag_seconds is the replication lag (current time minus\nreplicated time) in seconds. This field will be present when a\nreplication stream is in the REPLICATING state.", "type": "integer", "format": "int32" }, "retained_time": { "description": "retained_time is the timestamp indicating the lower bound that the\nreplication stream can failover to. This field will be present\nwhen a replication stream is in the REPLICATING state.", "type": "string", "format": "date-time" }, "standby_cluster_id": { "description": "standby_cluster_id is the ID of the standby cluster that data is being\nreplicated to.", "type": "string" }, "status": { "$ref": "#/components/schemas/ReplicationStreamStatus.Type" } }, "example": { "activation_at": "2006-01-03T15:04:15Z", "created_at": "2006-01-02T15:04:05Z", "failover_at": "2006-01-03T15:04:05Z", "id": "00000000-0000-0000-0000-000000000001", "primary_cluster_id": "00000000-0000-0000-0000-000000000002", "replicated_time": "2006-01-03T15:04:04Z", "retained_time": "2006-01-02T15:04:06Z", "standby_cluster_id": "00000000-0000-0000-0000-000000000003", "status": "COMPLETED" }, "required": [ "id", "status", "primary_cluster_id", "standby_cluster_id", "created_at" ] }, "PhysicalReplicationStreamList": { "type": "object", "properties": { "pagination": { "$ref": "#/components/schemas/KeysetPaginationResponse" }, "physical_replication_streams": { "description": "physical_replication_streams is a list of PhysicalReplicationStreams.", "type": "array", "items": { "$ref": "#/components/schemas/PhysicalReplicationStream" } } }, "required": ["physical_replication_streams"] }, "Plan.Type": { "description": " - BASIC: The Basic plan includes essential operational features, is available in\nselect regions, and offers on-demand capacity, making it ideal for small\nteams with unpredictable workloads.\n - STANDARD: The Standard plan includes standard enterprise security and monitoring\nfeatures, is available in all supported regions, and offers provisioned\npricing, making it the default choice for most CockroachDB production\nworkloads.\n - ADVANCED: The Advanced plan is ideal for workloads with stringent isolation,\ncompliance, and security requirements such as CMEK, PCI and HIPAA-readiness,\nand support for dedicated hardware. Customers are advised to have their\naccount team and/or Cockroach Labs Support \ninvolved when provisioning Advanced clusters.", "type": "string", "enum": ["BASIC", "STANDARD", "ADVANCED"] }, "PrivateEndpointConnection": { "type": "object", "properties": { "cloud_provider": { "$ref": "#/components/schemas/CloudProvider.Type" }, "endpoint_id": { "description": "endpoint_id is the id of the private endpoint associated with this\nconnection. The private endpoint is customer-created and its id is\ngenerated by the cloud provider at endpoint creation time.", "type": "string" }, "endpoint_service_id": { "description": "endpoint_service_id is the id of the private endpoint service associated\nwith this connection.", "type": "string" }, "external_owner_id": { "description": "external_owner_id uniquely identifies the owner of the private endpoint\nconnection cloud resource. This idenfier is the AWS account id\nowning the PrivateLink connection. This field is only valid on AWS clusters.", "type": "string" }, "region_name": { "description": "region_name is the cloud provider region name (e.g. us-east-1).", "type": "string" }, "service_name": { "description": "service_name is the name of the private endpoints service that this connection\ncorresponds to.", "type": "string" }, "status": { "$ref": "#/components/schemas/PrivateEndpointConnectionStatus" } }, "example": { "cloud": "AWS", "cloud_provider": "AWS", "endpoint_id": "2w543-45643-323fd", "endpoint_service_id": "34t-4t446-876bm", "region": "us-east-1", "service_name": "com.vpc-serv1", "status": "STATUS_AVAILABLE" }, "required": [ "region", "cloud_provider", "status", "endpoint_id", "endpoint_service_id", "service_name" ] }, "PrivateEndpointConnectionStatus": { "description": "PrivateEndpointConnectionStatus enumerates the possible statuses\nfor the private endpoints connection.\n\n - STATUS_STALE: Indicates that the endpoint was deleted outside of CockroachDB Cloud. Delete the endpoint\nthrough the Cloud API or Console to manually remove the connection entry.", "type": "string", "enum": [ "STATUS_PENDING", "STATUS_PENDING_ACCEPTANCE", "STATUS_AVAILABLE", "STATUS_DELETING", "STATUS_DELETED", "STATUS_REJECTED", "STATUS_FAILED", "STATUS_EXPIRED", "STATUS_STALE" ] }, "PrivateEndpointConnections": { "type": "object", "properties": { "connections": { "description": "Connections is a list of private endpoints.", "type": "array", "items": { "$ref": "#/components/schemas/PrivateEndpointConnection" } } }, "required": ["connections"] }, "PrivateEndpointService": { "type": "object", "properties": { "availability_zone_ids": { "description": "availability_zone_ids are the unique identifiers for the availability\nzones in which this service is available. Note these identifiers\nare unique even across typical cloud provider boundaries, for example\nAWS accounts or organizations. In AWS, availability zone ids for us-east-1\nare use1-az1, use1-az2, use1-az3.", "type": "array", "items": { "type": "string" } }, "aws": { "$ref": "#/components/schemas/AWSPrivateLinkServiceDetail" }, "cloud_provider": { "$ref": "#/components/schemas/CloudProvider.Type" }, "endpoint_service_id": { "description": "endpoint_service_id uniquely identifies this private endpoint service. This\nis the cloud provider generated id for the service.", "type": "string" }, "name": { "description": "name is the name of the private endpoints service.", "type": "string" }, "region_name": { "description": "region_name is the cloud provider region name (e.g. us-east-1).", "type": "string" }, "status": { "$ref": "#/components/schemas/PrivateEndpointServiceStatus.Type" } }, "required": [ "region_name", "cloud_provider", "status", "name", "endpoint_service_id", "availability_zone_ids" ] }, "PrivateEndpointServiceStatus.Type": { "type": "string", "enum": [ "CREATING", "AVAILABLE", "CREATE_FAILED", "DELETING", "DELETE_FAILED" ] }, "PrivateEndpointServices": { "type": "object", "properties": { "services": { "description": "services contains a list of all cluster related services.", "type": "array", "items": { "$ref": "#/components/schemas/PrivateEndpointService" } } }, "required": ["services"] }, "PrivateEndpointTrustedOwner": { "description": "PrivateEndpointTrustedOwner represents a trusted owner entry for private\nendpoint connections.", "type": "object", "properties": { "cluster_id": { "description": "cluster_id identifies the cluster to which this trusted owner entry applies.", "type": "string" }, "created_at": { "description": "created_at is the time at which the entry was created.", "type": "string", "format": "date-time" }, "external_owner_id": { "description": "external_owner_id is the identifier of the owner within the cloud provider\nfor private endpoint connections. A wildcard character (\"*\") can be used to\ndenote all owners.", "type": "string" }, "id": { "description": "id is a UUID that uniquely identifies this trusted owner entry.", "type": "string" }, "type": { "$ref": "#/components/schemas/PrivateEndpointTrustedOwnerType.Type" } }, "required": [ "id", "cluster_id", "type", "external_owner_id", "created_at" ], "title": "PrivateEndpointTrustedOwner" }, "PrivateEndpointTrustedOwnerType.Type": { "description": " - AWS_ACCOUNT_ID: AWS_ACCOUNT_ID represents the 12-digit AWS account number.", "type": "string", "enum": ["AWS_ACCOUNT_ID"] }, "PrometheusMetricExportInfo": { "type": "object", "properties": { "cluster_id": { "type": "string" }, "status": { "$ref": "#/components/schemas/MetricExportStatus.Type" }, "targets": { "description": "targets is a map of ports exposing metrics to regions.", "type": "object", "additionalProperties": { "type": "string" } }, "user_message": { "type": "string" } }, "required": ["cluster_id"], "title": "PrometheusMetricExportInfo" }, "QuantityUnit.Type": { "type": "string", "enum": ["HOURS", "REQUEST_UNITS", "GIB", "GIB_HOURS", "VCPU_HOURS"] }, "Region": { "type": "object", "properties": { "disk_iops": { "description": "disk_iops is the provisioned disk I/O operations per second for nodes\nin this region. Only meaningful for Advanced clusters on AWS; for GCP\nand Azure the cloud provider chooses based on disk size.", "type": "integer", "format": "int32" }, "internal_dns": { "description": "internal_dns is the internal DNS name of the cluster within the cloud\nprovider's network. It is used to connect to the cluster with AWS\nPrivateLink, Azure Private Link, and GCP VPC Peering, but not GCP Private\nService Connect.", "type": "string" }, "machine_type": { "description": "machine_type is the machine type identifier within the cloud provider\nfor nodes in this region (e.g. m5.xlarge, n2-standard-4). May differ\nacross regions in a heterogeneous Advanced cluster. Only populated for\nAdvanced clusters.", "type": "string" }, "name": { "type": "string" }, "node_count": { "description": "node_count will be 0 for Serverless clusters.", "type": "integer", "format": "int32" }, "num_virtual_cpus": { "description": "num_virtual_cpus is the number of virtual CPUs per node in this region,\nderived from machine_type. Only populated for Advanced clusters.", "type": "integer", "format": "int32" }, "primary": { "description": "primary is true only for the primary region in a Multi Region Serverless cluster.", "type": "boolean" }, "private_endpoint_dns": { "description": "private_endpoint_dns is the DNS name of the cluster which is used to\nconnect to the cluster with GCP Private Service Connect.", "type": "string" }, "s3_vpc_endpoint_id": { "description": "s3_vpc_endpoint_id is the ID of the AWS S3 VPC gateway endpoint\nassociated with this cluster region. This can be used to configure\nS3 bucket policies that restrict access to traffic from this\nVPC endpoint. Only populated for Advanced clusters on AWS.", "type": "string" }, "sql_dns": { "description": "sql_dns is the DNS name of SQL interface of the cluster. It is used to connect to the cluster with IP allowlisting.", "type": "string" }, "ui_dns": { "description": "ui_dns is the DNS name used when connecting to the DB Console for the cluster.", "type": "string" } }, "required": [ "name", "sql_dns", "ui_dns", "node_count", "internal_dns", "private_endpoint_dns" ] }, "RegionalDisruptorSpecification": { "description": "RegionalDisruptorSpecification represents how a region is disrupted. To\nreduce ambiguity, a RegionalDisruptorSpecification should not represent a\nhealthy cluster - there should be at least some disrupted pods.", "type": "object", "properties": { "azs": { "type": "array", "items": { "type": "string" }, "title": "azs represents each availability zone that should be disrupted. The AZs for\na cluster can be found in the db-console under the Advanced Debug -\nLocalities section. The AZ should not include the cloud provider name\nprefix. (i.e. us-east1-a)" }, "is_whole_region": { "description": "is_whole_region denotes whether the whole region should be disrupted. If a\nspecific pod or az is passed, this value should be false.", "type": "boolean" }, "pods": { "description": "pods represents each individual CRDB pod name that should be disrupted.\nPod names can be found using the\n[ListClusterNodes api](https://www.cockroachlabs.com/docs/api/cloud/v1#get-/api/v1/clusters/-cluster_id-/nodes).", "type": "array", "items": { "type": "string" } }, "region_code": { "description": "region_code is the cloud provider specific region code of the region. (i.e\nus-east1 for gcp, us-east-1 for aws, eastus for azure). Region names for\neach node the cluster can be found using the\n[ListClusterNodes api](https://www.cockroachlabs.com/docs/api/cloud/v1#get-/api/v1/clusters/-cluster_id-/nodes).", "type": "string" } }, "required": ["region_code", "is_whole_region"] }, "ReleaseType.Type": { "type": "string", "enum": ["REGULAR", "INNOVATION"] }, "RemovePrivateEndpointTrustedOwnerResponse": { "type": "object", "properties": { "trusted_owner": { "$ref": "#/components/schemas/PrivateEndpointTrustedOwner" } }, "required": ["trusted_owner"] }, "ReplicationStreamStatus.Type": { "description": "status describes the desired status of the replication stream.\n\n - STARTING: signifies that a stream is starting\n - REPLICATING: during an update request, status 'REPLICATING' is allowed to transition to 'FAILING_OVER' or 'CANCELED'.\nOther status transitions are not supported.\n - FAILING_OVER: used to trigger a failover, or to signify that a failover is occurring.\n - COMPLETED: signifies that a failover is complete.\n - CANCELED: signifies that a stream is canceled.", "type": "string", "enum": [ "STARTING", "REPLICATING", "FAILING_OVER", "COMPLETED", "CANCELED" ] }, "Resource": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "$ref": "#/components/schemas/ResourceType.Type" } }, "required": ["type"] }, "ResourceType.Type": { "description": " - ORGANIZATION: An organization.\n - CLUSTER: A cluster resource.\n - FOLDER: Preview: A folder resource.", "type": "string", "enum": ["ORGANIZATION", "CLUSTER", "FOLDER"] }, "Restore": { "type": "object", "properties": { "backup_end_time": { "description": "The timestamp at which the backup data was captured.", "type": "string", "format": "date-time" }, "backup_id": { "description": "The ID of the backup used for this restore job.", "type": "string" }, "client_error_code": { "description": "Error code from the restore job, only populated if it has failed.", "type": "integer", "format": "int32" }, "client_error_message": { "description": "Error message from the restore job, only populated if it has failed.", "type": "string" }, "completed_at": { "description": "The timestamp at which the restore job completed.", "type": "string", "format": "date-time" }, "completion_percent": { "description": "The percentage of the restore job that has been completed.\nThe value ranges from 0 to 1.", "type": "number", "format": "float" }, "crdb_job_id": { "description": "The CockroachDB internal job ID for the restore job.", "type": "string" }, "created_at": { "description": "The time at which the restore job was initiated.", "type": "string", "format": "date-time" }, "destination_cluster_name": { "description": "The name of the cluster to which the restore is being applied.", "type": "string" }, "id": { "description": "The unique identifier associated with the restore.", "type": "string" }, "objects": { "description": "The list of database objects (databases, tables) that were restored.", "type": "array", "items": { "$ref": "#/components/schemas/RestoreItem" } }, "restore_opts": { "$ref": "#/components/schemas/RestoreOpts" }, "source_cluster_name": { "description": "The name of the cluster from which the backup was taken.", "type": "string" }, "status": { "$ref": "#/components/schemas/RestoreStatus.Type" }, "type": { "$ref": "#/components/schemas/RestoreType.Type" } }, "example": { "backup_end_time": "2025-07-09T14:00:00Z", "backup_id": "1234abcd-1234-1234-abcd-12345678abcd", "completion_percent": 0, "created_at": "2025-07-09T15:04:05Z", "destination_cluster_name": "dest-cluster", "id": "abcd1234-5678-90ab-cdef-1234567890ab", "objects": [ { "database": "mydb", "schema": "public", "table": "users" } ], "source_cluster_name": "src-cluster", "status": "PENDING", "type": "TABLE" }, "required": [ "id", "backup_id", "status", "created_at", "type", "completion_percent", "source_cluster_name", "destination_cluster_name", "backup_end_time" ] }, "RestoreItem": { "type": "object", "properties": { "database": { "type": "string" }, "schema": { "type": "string" }, "table": { "type": "string" } }, "required": ["database"] }, "RestoreOpts": { "type": "object", "properties": { "into_db": { "description": "Specifies the target database to restore the table into during a\ntable restore job. If not set, the table will be restored\ninto the database it belonged to in the source backup.", "type": "string" }, "new_db_name": { "description": "Specifies the name of the database to create during a\ndatabase restore job. If not set, the name defaults to\nthe original database name from the source cluster.", "type": "string" }, "schema_only": { "description": "If set, only the schema will be restored and no user data will\nbe included.", "type": "boolean" }, "skip_localities_check": { "description": "Allows the restore job to continue in the event that there\nare mismatched localities between the backup and target cluster.\nUseful when restoring multi-region tables to a cluster missing\nsome localities.", "type": "boolean" }, "skip_missing_foreign_keys": { "description": "Allows a table to be restored even if it has foreign key\nconstraints referencing rows that no longer exist in the target\ncluster.", "type": "boolean" }, "skip_missing_sequences": { "type": "boolean", "title": "Allows a table to be restored even if it contains a column whose\n`DEFAULT` value depends on a sequence.\n(See https://www.cockroachlabs.com/docs/stable/show-sequences)" }, "skip_missing_views": { "description": "Allows the job to skip restoring views that cannot be\nrestored because their dependencies are not included in the\ncurrent restore job.", "type": "boolean" } } }, "RestoreStatus.Type": { "type": "string", "enum": ["PENDING", "SUCCESS", "FAILED"] }, "RestoreType.Type": { "type": "string", "enum": ["CLUSTER", "DATABASE", "TABLE"] }, "SQLUser": { "type": "object", "properties": { "name": { "type": "string" } }, "required": ["name"] }, "ScimAuthenticationScheme": { "type": "object", "properties": { "description": { "type": "string" }, "documentationUri": { "type": "string" }, "name": { "type": "string" }, "primary": { "type": "boolean" }, "specUri": { "type": "string" }, "type": { "type": "string" } }, "required": ["name", "description", "type"], "title": "ScimAuthenticationScheme" }, "ScimBulkSupport": { "type": "object", "properties": { "maxOperations": { "type": "integer", "format": "int32" }, "maxPayloadSize": { "type": "integer", "format": "int32" }, "supported": { "type": "boolean" } }, "required": ["supported", "maxOperations", "maxPayloadSize"], "title": "ScimBulkSupport" }, "ScimChangePasswordSupport": { "type": "object", "properties": { "supported": { "type": "boolean" } }, "required": ["supported"], "title": "ScimChangePasswordSupport" }, "ScimEmail": { "type": "object", "properties": { "display": { "type": "string" }, "primary": { "type": "boolean" }, "type": { "type": "string" }, "value": { "type": "string" } }, "required": ["value"] }, "ScimEtagSupport": { "type": "object", "properties": { "maxResults": { "type": "integer", "format": "int32" }, "supported": { "type": "boolean" } }, "required": ["supported"], "title": "ScimEtagSupport" }, "ScimFilterSupport": { "type": "object", "properties": { "maxResults": { "type": "integer", "format": "int32" }, "supported": { "type": "boolean" } }, "required": ["supported", "maxResults"], "title": "ScimFilterSupport" }, "ScimGroup": { "description": "SCIM 2.0 Group Resource", "type": "object", "properties": { "displayName": { "type": "string" }, "externalId": { "type": "string" }, "id": { "type": "string" }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/ScimResource" } }, "meta": { "$ref": "#/components/schemas/ScimMetadata" }, "schemas": { "type": "array", "items": { "type": "string" } } }, "required": ["schemas", "id", "displayName"], "title": "ScimGroup" }, "ScimMetadata": { "type": "object", "properties": { "created": { "type": "string" }, "lastModified": { "type": "string" }, "location": { "type": "string" }, "resourceType": { "type": "string" } }, "title": "meta" }, "ScimName": { "type": "object", "properties": { "familyName": { "type": "string" }, "givenName": { "type": "string" } }, "title": "name" }, "ScimOperations": { "type": "object", "properties": { "op": { "type": "string" }, "path": { "type": "string" }, "value": {} }, "required": ["op"] }, "ScimResource": { "type": "object", "properties": { "display": { "type": "string" }, "ref": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" } }, "title": "SCIM" }, "ScimResourceType": { "type": "object", "properties": { "description": { "type": "string" }, "endpoint": { "type": "string" }, "id": { "type": "string" }, "meta": { "$ref": "#/components/schemas/ScimMetadata" }, "name": { "type": "string" }, "schema": { "type": "string" }, "schemas": { "type": "array", "items": { "type": "string" } } }, "required": ["name", "endpoint", "schema"], "title": "ScimResourceType" }, "ScimSchema": { "type": "object", "properties": { "attributes": { "type": "array", "items": { "$ref": "#/components/schemas/ScimSchemaAttribute" } }, "description": { "type": "string" }, "id": { "type": "string" }, "meta": { "$ref": "#/components/schemas/ScimMetadata" }, "name": { "type": "string" } }, "required": ["id"], "title": "ScimSchema" }, "ScimSchemaAttribute": { "type": "object", "properties": { "canonicalValues": { "type": "array", "items": { "type": "string" } }, "caseExact": { "type": "boolean" }, "description": { "type": "string" }, "multiValued": { "type": "boolean" }, "mutability": { "type": "string" }, "name": { "type": "string" }, "referenceTypes": { "type": "array", "items": { "type": "string" } }, "required": { "type": "boolean" }, "returned": { "type": "string" }, "subAttributes": { "type": "array", "items": { "$ref": "#/components/schemas/ScimSchemaAttribute" } }, "type": { "type": "string" }, "uniqueness": { "type": "string" } } }, "ScimSortSupport": { "type": "object", "properties": { "supported": { "type": "boolean" } }, "required": ["supported"], "title": "ScimSortSupport" }, "ScimUser": { "description": "SCIM 2.0 User Resource", "type": "object", "properties": { "active": { "type": "boolean" }, "displayName": { "type": "string" }, "emails": { "type": "array", "items": { "$ref": "#/components/schemas/ScimEmail" } }, "externalId": { "type": "string" }, "groups": { "type": "array", "items": { "$ref": "#/components/schemas/ScimResource" } }, "id": { "type": "string" }, "meta": { "$ref": "#/components/schemas/ScimMetadata" }, "name": { "$ref": "#/components/schemas/ScimName" }, "schemas": { "type": "array", "items": { "type": "string" } }, "userName": { "type": "string" } }, "required": ["schemas", "id"], "title": "ScimUser" }, "SearchGroupBody": { "type": "object", "properties": { "attributes": { "type": "string" }, "excludedAttributes": { "type": "string" } }, "title": "GetGroupRequest" }, "SearchUserBody": { "type": "object", "properties": { "attributes": { "type": "string" }, "excludedAttributes": { "type": "string" } }, "title": "GetUserRequest" }, "ServerlessClusterConfig": { "type": "object", "properties": { "routing_id": { "description": "routing_id is used to identify the cluster in a connection string.", "type": "string" }, "upgrade_type": { "$ref": "#/components/schemas/UpgradeType.Type" }, "usage_limits": { "$ref": "#/components/schemas/UsageLimits" } }, "required": ["routing_id", "upgrade_type"] }, "ServerlessClusterCreateSpecification": { "type": "object", "properties": { "primary_region": { "description": "Preview: Specify which region should be made the primary region.\nThis is only applicable to multi-region Serverless clusters.\nThis field is required if you create the cluster in more than\none region.", "type": "string" }, "regions": { "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.", "type": "array", "items": { "type": "string" } }, "upgrade_type": { "$ref": "#/components/schemas/UpgradeType.Type" }, "usage_limits": { "$ref": "#/components/schemas/UsageLimits" }, "with_empty_ip_allowlist": { "description": "WithEmptyIPAllowlist creates a cluster with no entries in the IP Allowlist.\nBy default, Serverless clusters have one IP allowlist entry that opens the cluster to any IP.\nSet this property to true to ensure the cluster is closed to public traffic by default.", "type": "boolean" } }, "required": ["regions"] }, "ServerlessClusterUpdateSpecification": { "type": "object", "properties": { "primary_region": { "description": "Specify which region should be made the primary region.\nThis is only applicable to multi-region Serverless clusters.\nThis field is required if the regions field contains more than one region.", "type": "string" }, "regions": { "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. If this field is provided, the cluster's\nregions will be changed to match this list.\nRegions cannot currently be removed.", "type": "array", "items": { "type": "string" } }, "upgrade_type": { "$ref": "#/components/schemas/UpgradeType.Type" }, "usage_limits": { "$ref": "#/components/schemas/UsageLimits" } } }, "ServiceAccount": { "description": "A service account is an identity scoped to an organization that\nrepresents a non-human user.", "type": "object", "properties": { "created_at": { "description": "created_at represents the creation time of the service account.", "type": "string", "format": "date-time" }, "creator_name": { "description": "creator_name is the name of user that created the service account.", "type": "string" }, "description": { "description": "description of the service account.", "type": "string" }, "group_roles": { "description": "roles that the service account has inherited via a group.", "type": "array", "items": { "$ref": "#/components/schemas/BuiltInFromGroups" } }, "id": { "description": "The ID of the service account.", "type": "string" }, "name": { "description": "name of the service account.", "type": "string" }, "roles": { "description": "roles that are assigned to the service account.", "type": "array", "items": { "$ref": "#/components/schemas/BuiltInRole" } } }, "example": { "created_at": "2022-03-22T20:23:11.285067Z", "creator_name": "creator", "description": "", "group_roles": [], "id": "12345678-1234-1234-1234-123456789012", "name": "SA Name", "roles": [ { "name": "CLUSTER_ADMIN", "resource": { "type": "ORGANIZATION" } } ] }, "required": [ "id", "name", "description", "creator_name", "created_at", "roles", "group_roles" ], "title": "ServiceAccount" }, "SetAWSEndpointConnectionStatus.Type": { "description": " - AVAILABLE: accept/verify the connection on the service side.\n - REJECTED: reject the connection on the service side.", "type": "string", "enum": ["AVAILABLE", "REJECTED"] }, "SetAwsEndpointConnectionStateBody": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/SetAWSEndpointConnectionStatus.Type" } }, "example": { "status": "AVAILABLE" }, "required": ["status"], "title": "SetAwsEndpointConnectionStateRequest" }, "SetClientCACertBody": { "type": "object", "properties": { "x509_pem_cert": { "type": "string" } }, "example": { "x509_pem_cert": "-----BEGIN CERTIFICATE-----..." }, "required": ["x509_pem_cert"], "title": "SetClientCACertRequest" }, "SetEgressTrafficPolicyBody": { "type": "object", "properties": { "allow_all": { "description": "allow_all, if true results in unrestricted egress traffic. If false, egress\ntraffic is set to default-deny and is managed via the Egress Rule\nManagement API.", "type": "boolean" }, "idempotency_key": { "description": "idempotency_key uniquely identifies this request. If not set, it will be\nset by the server.", "type": "string" } }, "required": ["allow_all"], "title": "SetEgressTrafficPolicyRequest" }, "SetRolesForUserBody": { "type": "object", "properties": { "roles": { "type": "array", "items": { "$ref": "#/components/schemas/BuiltInRole" } } }, "example": { "roles": [ { "name": "CLUSTER_ADMIN", "resource": { "id": "example_cluster_id", "type": "CLUSTER" } } ], "user_id": "12345678-1234-1234-1234-123456789012" }, "required": ["roles"] }, "Status": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32" }, "details": { "type": "array", "items": { "$ref": "#/components/schemas/Any" } }, "message": { "type": "string" } } }, "SystemActorName": { "description": "SystemActorName identifies a system process that triggered an audit log\nentry when the action was not initiated by a human user or service account.", "type": "string", "enum": ["SYSTEM_ACTOR_NAME_SYSTEM"] }, "UpdateApiKeySpecification": { "type": "object", "properties": { "name": { "description": "name of the api key.", "type": "string", "example": "new name" } }, "example": { "name": "new name" } }, "UpdateBackupConfigurationSpec": { "type": "object", "properties": { "enabled": { "description": "Indicates whether backups are enabled.", "type": "boolean" }, "frequency_minutes": { "description": "How frequently in minutes that backups are taken, which will determine the\n[RPO](https://www.cockroachlabs.com/docs/stable/disaster-recovery-overview)\nof the cluster. Valid values are [5, 10, 15, 30, 60, 240, 1440].", "type": "integer", "format": "int32" }, "retention_days": { "description": "The number of days to retain backups for. Can only be set once, further\nchanges require opening a support ticket. Valid values are [2, 7, 30, 90,\n365].", "type": "integer", "format": "int32" } }, "example": { "enabled": true, "frequency_minutes": 60, "retention_days": 7 } }, "UpdateBlackoutWindowBody": { "type": "object", "properties": { "end_time": { "description": "Optional new UTC end time for the blackout window.\nCan be up to 14 days after the start time.\nMust not be more than three months after the current time.", "type": "string", "format": "date-time" }, "start_time": { "description": "Optional new UTC start time for the blackout window.\nMust be scheduled at least 7 days in advance.", "type": "string", "format": "date-time" } }, "example": { "blackout_window_id": "12345678-1234-1234-1234-123456789012", "cluster_id": "12345678-1234-1234-1234-123456789012", "end_time": "2025-10-15T06:00:00Z", "start_time": "2025-10-15T00:00:00Z" }, "title": "UpdateBlackoutWindowRequest" }, "UpdateCMEKSpecBody": { "type": "object", "properties": { "region_specs": { "type": "array", "items": { "$ref": "#/components/schemas/CMEKRegionSpecification" } } }, "example": { "region_specs": [ { "key_spec": { "auth_principal": "arn:aws:iam::account:role/role-name-with-path", "type": "AWS_KMS", "uri": "arn:aws:kms:us-west-2:111122223333:key/id-of-kms-key" }, "region": "us-central1" } ] }, "required": ["region_specs"], "title": "CMEKClusterSpecification" }, "UpdateCMEKStatusBody": { "type": "object", "properties": { "action": { "$ref": "#/components/schemas/CMEKCustomerAction" } }, "example": { "action": "REVOKE" }, "required": ["action"], "title": "UpdateCMEKStatusRequest" }, "UpdateClientCACertBody": { "type": "object", "properties": { "x509_pem_cert": { "type": "string" } }, "example": { "x509_pem_cert": "-----BEGIN CERTIFICATE-----..." }, "title": "UpdateClientCACertRequest" }, "UpdateClusterDisruptionBody": { "type": "object", "properties": { "regional_disruptor_specifications": { "description": "regional_disruptor_specifications specify how regions are to be\ndisrupted. Any Cluster region that is not specified here will not be\ndisrupted. A cluster region that was previously disrupted but is not listed\nhere will be removed from disruption. To stop all disruptions, set this\nto an empty list or omit it from the request.", "type": "array", "items": { "$ref": "#/components/schemas/RegionalDisruptorSpecification" } } } }, "UpdateClusterSpecification": { "type": "object", "properties": { "cockroach_version": { "description": "The desired CockroachDB major version for the cluster. It can be used to\norchestrate version changes. Setting the version to a later version will\ninitiate an upgrade to that version. After an upgrade is initiated but\nbefore it's finalized, setting the version back to the previous version\nwill initiate a rollback.", "type": "string" }, "dedicated": { "$ref": "#/components/schemas/DedicatedClusterUpdateSpecification" }, "delete_protection": { "$ref": "#/components/schemas/DeleteProtectionState.Type" }, "labels": { "description": "labels are key-value pairs used to organize and categorize resources.\nIf the labels field is included in the request: Any existing labels on the cluster\nthat are not included will be removed, and any new labels specified will be added.\nIf the labels field is omitted from the request entirely, all existing labels will\nremain unchanged.", "type": "object", "additionalProperties": { "type": "string" } }, "parent_id": { "description": "Preview: The parent ID is a folder ID. An empty string or \"root\"\nrepresents the root level.", "type": "string" }, "plan": { "$ref": "#/components/schemas/Plan.Type" }, "serverless": { "$ref": "#/components/schemas/ServerlessClusterUpdateSpecification" }, "upgrade_status": { "$ref": "#/components/schemas/ClusterUpgradeStatus.Type" } }, "example": { "dedicated": { "hardware": { "machine_spec": { "num_virtual_cpus": 8 } }, "region_nodes": { "us-central1": 5, "us-west1": 3 } } } }, "UpdateEgressPrivateEndpointBody": { "type": "object", "properties": { "domain_names": { "description": "domain_names are the domain names to associate with the egress private endpoint.", "type": "array", "items": { "type": "string" } } }, "example": { "domain_names": ["example.com", "api.example.com"] }, "required": ["domain_names"], "title": "UpdateEgressPrivateEndpointRequest" }, "UpdateEgressPrivateEndpointDomainNamesBody": { "type": "object", "properties": { "domain_names": { "description": "domain_names are the domain names to associate with the egress private endpoint.", "type": "array", "items": { "type": "string" } } }, "example": { "domain_names": ["example.com", "api.example.com"] }, "required": ["domain_names"], "title": "UpdateEgressPrivateEndpointRequest" }, "UpdateFolderSpecification": { "description": "Set `parent_id` to empty string '' or 'root' to move a folder to the root level.", "type": "object", "properties": { "labels": { "description": "labels are key-value pairs used to organize and categorize resources.\nIf the labels field is included in the request: Any existing labels on the folder\nthat are not included will be removed, and any new labels specified will be added.\nIf the labels field is omitted from the request entirely, all existing labels will\nremain unchanged.", "type": "object", "additionalProperties": { "type": "string" } }, "name": { "type": "string" }, "parent_id": { "type": "string" } }, "example": { "name": "folder_name", "parent_id": "12345678-1234-1234-1234-123456789012" } }, "UpdateGroupBody": { "type": "object", "properties": { "displayName": { "type": "string" }, "externalId": { "type": "string" }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/ScimResource" } }, "schemas": { "type": "array", "items": { "type": "string" } } }, "example": { "displayName": "Test SCIM", "id": "23a35c27-23d3-4c03-b4c5-6443c09e7173", "members": [ { "display": "croach@example.com", "value": "45a35c27-23d3-4d03-c4c5-9043c09e7175" } ], "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"] }, "required": ["schemas", "displayName"], "title": "UpdateGroupRequest" }, "UpdateJWTIssuerBody": { "type": "object", "properties": { "audience": { "type": "string", "example": "1234567890abcd", "title": "The intended audience for consuming the JWT" }, "claim": { "type": "string", "example": "email", "title": "Used to identify the user from the external Identity Provider. Defaults to \"sub\"" }, "identity_map": { "type": "array", "items": { "$ref": "#/components/schemas/JWTIssuerIdentityMapEntry" }, "title": "A list of mappings to map the external token identity into CockroachDB Cloud" }, "issuer_url": { "type": "string", "example": "https://jwt-issuer.example.com", "title": "The URL of the server issuing JWTs" }, "jwks": { "type": "string", "example": "{\"keys\":[{\"e\":\"AQAB\",\"use\":\"sig\",\"kty\":\"RSA\",\"alg\":\"RS256\",\"n\":\"tid8bJCI5FxtvMiVHq8pRZBGIPaG9mEa1akpIC9munzxA3mWoc-KoR1TGkocu76WFthaZnPS31WJbRVChU6g4EMIg7E8Ltpxifk1PQu0qqbLcpnoI62ojsB7l_Z_lkls0NUzTuKGMMtNoJsDrL1BT0UzcnWerh2PwzDAMpfPgafWdT2IYGTx1gNLcNOWpPhDgMSQqUmIPwCmxdan4i4OMd7lJYQ1WQlN8VnQgbRgHrm1zImY6MPqho9jW3Ub5FwGbunwCDrP9a2dD_5Iwm7_lR82iB4BGlu28WxFn0fm5DgZAeAFSGKE1xblC97WrjnPh2XYTx6pxsea_Hn71VcNSQ\",\"kid\":\"9341dedeee2d1869b657fa930300082fe26b3d92\"}]}", "title": "A set of public keys (JWKS) used to verify a JWT" } }, "title": "UpdateJWTIssuerRequest" }, "UpdatePhysicalReplicationStreamSpec": { "type": "object", "properties": { "failover_at": { "description": "failover_at is the crdb system time at which failover occurs. If the user\nsets the status to 'FAILING_OVER' but omits failover_at, the failover time\nwill default to the latest consistent replicated time. Otherwise, the user\ncan pick a time up to one hour in the future to schedule a failover, or a\ntime in the past to restore the cluster to a recent state. If the\ntime is in the past, the API will make a best-effort attempt to\nvalidate that the time is not earlier than the retained time. In\nthis case, if the retained time is updated in between validation\nand failover execution and the failover time becomes invalid, the\nstream will failover to the retained time. failover_at is not required\nwhen updating the status to 'CANCELED'.", "type": "string", "format": "date-time" }, "status": { "$ref": "#/components/schemas/ReplicationStreamStatus.Type" } }, "example": { "failover_at": "2006-01-03T15:04:05Z", "status": "FAILING_OVER" } }, "UpdateSQLUserPasswordBody": { "type": "object", "properties": { "password": { "type": "string" } }, "example": { "password": "example_new_password" }, "required": ["password"], "title": "UpdateSQLUserPasswordRequest" }, "UpdateServiceAccountSpecification": { "type": "object", "properties": { "description": { "description": "description of the service account.", "type": "string" }, "name": { "description": "name of the service account.", "type": "string" } }, "example": { "description": "new description", "name": "new name" } }, "UpdateUserBody": { "type": "object", "properties": { "active": { "type": "boolean" }, "displayName": { "type": "string" }, "emails": { "type": "array", "items": { "$ref": "#/components/schemas/ScimEmail" } }, "externalId": { "type": "string" }, "name": { "$ref": "#/components/schemas/ScimName" }, "schemas": { "type": "array", "items": { "type": "string" } }, "userName": { "type": "string" } }, "example": { "active": true, "emails": [ { "display": "croach@example.com", "primary": true, "type": "work", "value": "croach@example.com" } ], "name": { "familyName": "Roach", "givenName": "Carl" }, "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"] }, "title": "UpdateUserRequest" }, "UpgradeType.Type": { "type": "string", "enum": ["MANUAL", "AUTOMATIC"] }, "UsageLimits": { "type": "object", "properties": { "provisioned_virtual_cpus": { "description": "provisioned_virtual_cpus is the maximum number of vCPUs that the cluster\ncan use. Once this limit is reached, operation latency may increase due to\nthrottling. It is an error for this to be zero.", "type": "string", "format": "int64" }, "request_unit_limit": { "description": "request_unit_limit is the maximum number of request units that the cluster\ncan consume during the month. If this limit is exceeded, then the cluster\nis disabled until the limit is increased, or until the beginning of the\nnext month when more free request units are granted. It is an error for\nthis to be zero.", "type": "string", "format": "int64" }, "storage_mib_limit": { "description": "storage_mib_limit is the maximum number of Mebibytes of storage that the\ncluster can have at any time during the month. If this limit is exceeded,\nthen the cluster is throttled; only one SQL connection is allowed at a\ntime, with the expectation that it is used to delete data to reduce storage\nusage. It is an error for this to be zero.", "type": "string", "format": "int64" } } }, "UserGroupRoleGrant": { "type": "object", "properties": { "group_roles": { "type": "array", "items": { "$ref": "#/components/schemas/BuiltInFromGroups" } }, "user_id": { "type": "string" } } }, "UserRoleGrants": { "type": "object", "properties": { "roles": { "type": "array", "items": { "$ref": "#/components/schemas/BuiltInRole" } }, "user_id": { "type": "string" } }, "example": { "roles": [ { "name": "CLUSTER_ADMIN", "resource": { "id": "example_cluster_id", "type": "CLUSTER" } } ], "user_id": "12345678-1234-1234-1234-123456789012" }, "required": ["user_id", "roles"] } }, "requestBodies": {}, "securitySchemes": { "Bearer": { "type": "http", "scheme": "bearer" } } }, "tags": [ { "name": "SCIM" }, { "name": "Organizations" }, { "name": "Clusters" }, { "name": "Cluster Disruption" }, { "name": "SQL Users" }, { "name": "SQL Privilege Grants" }, { "name": "Databases" }, { "name": "Customer-managed Encryption Keys" }, { "name": "Client CA Certificates" }, { "name": "Cluster SSO" }, { "name": "Log Export" }, { "name": "Metric Export" }, { "name": "Audit Logs" }, { "name": "IP Allowlists" }, { "name": "Egress Rules" }, { "name": "Billing" }, { "name": "Maintenance Windows" }, { "name": "Blackout Windows" }, { "name": "Role Management" }, { "name": "Service Accounts" }, { "name": "API Keys" }, { "name": "Folders" }, { "name": "Version Deferral" }, { "name": "JWT Issuers" }, { "name": "OpenID Connect Configuration" }, { "name": "Private Endpoint Services" }, { "name": "PCI" }, { "name": "Physical Cluster Replication" }, { "name": "Plan Migrations" }, { "name": "Backup/Restore" }, { "name": "Egress Private Endpoints" }, { "name": "Multifactor Authentication" } ], "externalDocs": { "description": "Use the CockroachDB Cloud API", "url": "https://www.cockroachlabs.com/docs/cockroachcloud/cloud-api.html" }, "security": [ { "Bearer": [] } ] }