CockroachDB Cloud API

openapi: 3.1.0
info:
  title: CockroachDB Cloud API
  description: >-
    The CockroachDB Cloud API is a REST interface that provides programmatic
    access to manage the lifecycle of clusters within a CockroachDB Cloud
    organization. It enables developers and operators to create, configure,
    scale, and delete CockroachDB Serverless and Dedicated clusters without
    using the web console. The API supports cluster provisioning, node
    management, network authorization, customer-managed encryption keys,
    backup and restore, log and metric export, role management, and folder
    organization. Authentication is handled via bearer tokens, and the API is
    rate-limited to 10 requests per second per user.
  version: '2024-09-16'
  contact:
    name: Cockroach Labs Support
    url: https://support.cockroachlabs.com
  termsOfService: https://www.cockroachlabs.com/cloud-terms-and-conditions/
externalDocs:
  description: CockroachDB Cloud API Documentation
  url: https://www.cockroachlabs.com/docs/cockroachcloud/cloud-api
servers:
  - url: https://cockroachlabs.cloud
    description: CockroachDB Cloud Production Server
tags:
  - name: APIKeys
    description: >-
      Manage API keys for programmatic access, including creation, retrieval,
      listing, updating, and deletion.
  - name: AuditLogs
    description: >-
      Retrieve audit log events for the organization to support compliance and
      security investigations.
  - name: BackupRestore
    description: >-
      Manage cluster backups, backup configurations, and restore operations for
      CockroachDB clusters.
  - name: Billing
    description: >-
      Retrieve invoices and billing information for the CockroachDB Cloud
      organization.
  - name: Clusters
    description: >-
      Create, list, retrieve, update, and delete CockroachDB Serverless and
      Dedicated clusters within an organization.
  - name: CMEK
    description: >-
      Manage customer-managed encryption keys (CMEK) for encrypting cluster
      data at rest using customer-controlled keys.
  - name: Databases
    description: >-
      Manage databases within a CockroachDB cluster, including creation,
      listing, updating, and deletion.
  - name: EgressRules
    description: >-
      Configure egress traffic rules and egress private endpoints for outbound
      cluster network traffic.
  - name: Folders
    description: >-
      Organize clusters and other resources into hierarchical folder structures
      within the organization.
  - name: IPAllowlists
    description: >-
      Configure IP allowlist entries to control network access to a cluster.
  - name: JWTIssuers
    description: >-
      Manage JWT issuer configurations for external identity provider
      integrations.
  - name: LogExport
    description: >-
      Configure log export to external destinations such as AWS CloudWatch or
      GCP Cloud Logging.
  - name: MaintenanceWindows
    description: >-
      Configure maintenance windows and blackout periods for cluster upgrade
      scheduling.
  - name: MetricExport
    description: >-
      Configure metric export integrations including AWS CloudWatch, Datadog,
      and Prometheus.
  - name: Organizations
    description: >-
      Retrieve information about the caller's CockroachDB Cloud organization.
  - name: PrivateEndpoints
    description: >-
      Manage private endpoint services and connections for secure VPC-level
      access to clusters.
  - name: RoleManagement
    description: >-
      Manage role-based access control, including assigning and removing roles
      for users across organization, folder, and cluster scopes.
  - name: ServiceAccounts
    description: >-
      Manage service accounts used for machine-to-machine authentication within
      the organization.
  - name: SQLUsers
    description: >-
      Manage SQL users for a cluster, including creating users, listing users,
      and updating SQL user passwords.
  - name: VersionDeferral
    description: >-
      Manage cluster version deferral policies to delay automatic CockroachDB
      version upgrades.
security:
  - bearerAuth: []
paths:
  /api/v1/organization:
    get:
      operationId: GetOrganizationInfo
      summary: Get organization information
      description: >-
        Retrieves information about the caller's CockroachDB Cloud organization,
        including organization ID and name. Requires ORG_ADMIN or ORG_MEMBER
        role at organization scope.
      tags:
        - Organizations
      responses:
        '200':
          description: Organization information retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Organization'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /api/v1/clusters:
    get:
      operationId: ListClusters
      summary: List clusters
      description: >-
        Returns a list of clusters in the organization. Inactive clusters can
        optionally be included using the showInactive query parameter. Supports
        pagination via page, limit, asOfTime, and sortOrder parameters.
      tags:
        - Clusters
      parameters:
        - $ref: '#/components/parameters/showInactive'
        - $ref: '#/components/parameters/paginationPage'
        - $ref: '#/components/parameters/paginationLimit'
        - $ref: '#/components/parameters/paginationAsOfTime'
        - $ref: '#/components/parameters/paginationSortOrder'
      responses:
        '200':
          description: List of clusters returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListClustersResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: CreateCluster
      summary: Create a cluster
      description: >-
        Creates and initializes a new CockroachDB Serverless or Dedicated
        cluster within the organization. The request body specifies cluster
        configuration including cloud provider, regions, hardware, and plan type.
      tags:
        - Clusters
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateClusterRequest'
      responses:
        '200':
          description: Cluster created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cluster'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/clusters/{cluster_id}:
    get:
      operationId: GetCluster
      summary: Get a cluster
      description: >-
        Retrieves comprehensive information about a specific cluster identified
        by cluster_id, including its configuration, state, regions, version, and
        operational status.
      tags:
        - Clusters
      parameters:
        - $ref: '#/components/parameters/clusterId'
      responses:
        '200':
          description: Cluster information retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cluster'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: UpdateCluster
      summary: Update a cluster
      description: >-
        Modifies the configuration of an existing cluster, including scaling
        compute and storage resources, updating the CockroachDB version, or
        changing cluster settings. Only the fields specified in the request body
        are updated.
      tags:
        - Clusters
      parameters:
        - $ref: '#/components/parameters/clusterId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateClusterSpecification'
      responses:
        '200':
          description: Cluster updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cluster'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: DeleteCluster
      summary: Delete a cluster
      description: >-
        Permanently deletes a cluster and all of its data. This operation cannot
        be undone. The cluster must not have delete protection enabled.
      tags:
        - Clusters
      parameters:
        - $ref: '#/components/parameters/clusterId'
      responses:
        '200':
          description: Cluster deleted successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cluster'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/clusters/{cluster_id}/connection-string:
    get:
      operationId: GetConnectionString
      summary: Get connection string
      description: >-
        Returns a formatted generic connection string for connecting to a
        cluster. Optionally scoped to a specific database, SQL user, and
        operating system format.
      tags:
        - Clusters
      parameters:
        - $ref: '#/components/parameters/clusterId'
        - name: database
          in: query
          description: Name of the database to connect to.
          schema:
            type: string
        - name: sql_user
          in: query
          description: SQL username to include in the connection string.
          schema:
            type: string
        - name: os
          in: query
          description: >-
            Operating system for which to format the connection string.
            Accepted values are MAC, LINUX, WINDOWS.
          schema:
            type: string
            enum: [MAC, LINUX, WINDOWS]
      responses:
        '200':
          description: Connection string returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetConnectionStringResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/clusters/{cluster_id}/nodes:
    get:
      operationId: ListClusterNodes
      summary: List cluster nodes
      description: >-
        Returns a list of nodes for the specified cluster, optionally filtered
        by region name. Supports pagination.
      tags:
        - Clusters
      parameters:
        - $ref: '#/components/parameters/clusterId'
        - name: region_name
          in: query
          description: Filter nodes by the name of the cloud provider region.
          schema:
            type: string
        - $ref: '#/components/parameters/paginationPage'
        - $ref: '#/components/parameters/paginationLimit'
        - $ref: '#/components/parameters/paginationAsOfTime'
        - $ref: '#/components/parameters/paginationSortOrder'
      responses:
        '200':
          description: List of cluster nodes returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListClusterNodesResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/clusters/available-regions:
    get:
      operationId: ListAvailableRegions
      summary: List available regions
      description: >-
        Returns a list of regions available for cluster or node creation,
        optionally filtered by cloud provider and whether serverless clusters
        are supported.
      tags:
        - Clusters
      parameters:
        - name: provider
          in: query
          description: >-
            Cloud provider to filter regions by. Accepted values are GCP, AWS,
            AZURE.
          schema:
            type: string
            enum: [GCP, AWS, AZURE]
        - name: serverless
          in: query
          description: >-
            If true, only return regions that support serverless clusters.
          schema:
            type: boolean
        - $ref: '#/components/parameters/paginationPage'
        - $ref: '#/components/parameters/paginationLimit'
      responses:
        '200':
          description: Available regions returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListAvailableRegionsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/cluster-versions:
    get:
      operationId: ListMajorClusterVersions
      summary: List major cluster versions
      description: >-
        Returns a list of available major CockroachDB cluster versions that can
        be used when creating or upgrading clusters.
      tags:
        - Clusters
      parameters:
        - $ref: '#/components/parameters/paginationPage'
        - $ref: '#/components/parameters/paginationLimit'
      responses:
        '200':
          description: Available cluster versions returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListMajorClusterVersionsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/clusters/{cluster_id}/databases:
    get:
      operationId: ListDatabases
      summary: List databases
      description: >-
        Returns a list of databases for the specified cluster. Supports
        pagination via page, limit, asOfTime, and sortOrder parameters.
      tags:
        - Databases
      parameters:
        - $ref: '#/components/parameters/clusterId'
        - $ref: '#/components/parameters/paginationPage'
        - $ref: '#/components/parameters/paginationLimit'
        - $ref: '#/components/parameters/paginationAsOfTime'
        - $ref: '#/components/parameters/paginationSortOrder'
      responses:
        '200':
          description: List of databases returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListDatabasesResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: CreateDatabase
      summary: Create a database
      description: >-
        Creates a new database within the specified cluster. Requires
        CLUSTER_ADMIN role at organization, folder, or cluster scope.
      tags:
        - Databases
      parameters:
        - $ref: '#/components/parameters/clusterId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDatabaseRequest'
      responses:
        '200':
          description: Database created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Database'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/clusters/{cluster_id}/databases/{name}:
    patch:
      operationId: EditDatabase
      summary: Update a database
      description: >-
        Updates the configuration of an existing database within the specified
        cluster. Requires CLUSTER_ADMIN role.
      tags:
        - Databases
      parameters:
        - $ref: '#/components/parameters/clusterId'
        - $ref: '#/components/parameters/databaseName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateDatabaseRequest'
      responses:
        '200':
          description: Database updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Database'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: DeleteDatabase
      summary: Delete a database
      description: >-
        Deletes a database from the specified cluster by name. Requires
        CLUSTER_ADMIN role at organization, folder, or cluster scope.
      tags:
        - Databases
      parameters:
        - $ref: '#/components/parameters/clusterId'
        - $ref: '#/components/parameters/databaseName'
      responses:
        '200':
          description: Database deleted successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Database'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/clusters/{cluster_id}/sql-users:
    get:
      operationId: ListSQLUsers
      summary: List SQL users
      description: >-
        Returns a list of SQL users for the specified cluster. Accessible to
        users with CLUSTER_ADMIN, CLUSTER_OPERATOR_WRITER, or CLUSTER_DEVELOPER
        roles.
      tags:
        - SQLUsers
      parameters:
        - $ref: '#/components/parameters/clusterId'
        - $ref: '#/components/parameters/paginationPage'
        - $ref: '#/components/parameters/paginationLimit'
        - $ref: '#/components/parameters/paginationAsOfTime'
        - $ref: '#/components/parameters/paginationSortOrder'
      responses:
        '200':
          description: List of SQL users returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSQLUsersResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: CreateSQLUser
      summary: Create a SQL user
      description: >-
        Creates a new SQL user for the specified cluster. Requires CLUSTER_ADMIN
        role at organization, folder, or cluster scope.
      tags:
        - SQLUsers
      parameters:
        - $ref: '#/components/parameters/clusterId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSQLUserRequest'
      responses:
        '200':
          description: SQL user created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SQLUser'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/clusters/{cluster_id}/sql-users/{name}:
    delete:
      operationId: DeleteSQLUser
      summary: Delete a SQL user
      description: >-
        Deletes a SQL user from the specified cluster by username. Requires
        CLUSTER_ADMIN role.
      tags:
        - SQLUsers
      parameters:
        - $ref: '#/components/parameters/clusterId'
        - $ref: '#/components/parameters/sqlUserName'
      responses:
        '200':
          description: SQL user deleted successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SQLUser'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/clusters/{cluster_id}/sql-users/{name}/password:
    put:
      operationId: UpdateSQLUserPassword
      summary: Update SQL user password
      description: >-
        Updates the password for the specified SQL user on the given cluster.
        Requires CLUSTER_ADMIN role at organization, folder, or cluster scope.
      tags:
        - SQLUsers
      parameters:
        - $ref: '#/components/parameters/clusterId'
        - $ref: '#/components/parameters/sqlUserName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSQLUserPasswordRequest'
      responses:
        '200':
          description: SQL user password updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SQLUser'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/api-keys:
    get:
      operationId: ListApiKeys
      summary: List API keys
      description: >-
        Returns a list of API keys in the organization, optionally filtered by
        service account ID. Accessible to users with ORG_ADMIN or CLUSTER_ADMIN
        roles.
      tags:
        - APIKeys
      parameters:
        - name: service_account_id
          in: query
          description: Filter API keys by the associated service account ID.
          schema:
            type: string
        - $ref: '#/components/parameters/paginationPage'
        - $ref: '#/components/parameters/paginationLimit'
        - $ref: '#/components/parameters/paginationAsOfTime'
        - $ref: '#/components/parameters/paginationSortOrder'
      responses:
        '200':
          description: List of API keys returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListApiKeysResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: CreateApiKey
      summary: Create an API key
      description: >-
        Creates a new API key associated with a service account. Requires
        ORG_ADMIN role. The secret is only returned in the response to this
        create request and cannot be retrieved again.
      tags:
        - APIKeys
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateApiKeyRequest'
      responses:
        '200':
          description: API key created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateApiKeyResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/api-keys/{id}:
    get:
      operationId: GetApiKey
      summary: Get an API key
      description: >-
        Retrieves details of a specific API key by ID. Accessible to users with
        ORG_ADMIN or CLUSTER_ADMIN roles.
      tags:
        - APIKeys
      parameters:
        - $ref: '#/components/parameters/resourceId'
      responses:
        '200':
          description: API key retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKey'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: UpdateApiKey
      summary: Update an API key
      description: >-
        Updates the metadata of an existing API key. Requires ORG_ADMIN role.
      tags:
        - APIKeys
      parameters:
        - $ref: '#/components/parameters/resourceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateApiKeySpecification'
      responses:
        '200':
          description: API key updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKey'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: DeleteApiKey
      summary: Delete an API key
      description: >-
        Permanently deletes an API key by ID, revoking all access using that
        key. Requires ORG_ADMIN role.
      tags:
        - APIKeys
      parameters:
        - $ref: '#/components/parameters/resourceId'
      responses:
        '200':
          description: API key deleted successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKey'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/service-accounts:
    get:
      operationId: ListServiceAccounts
      summary: List service accounts
      description: >-
        Returns a list of service accounts in the organization. Supports
        pagination.
      tags:
        - ServiceAccounts
      parameters:
        - $ref: '#/components/parameters/paginationPage'
        - $ref: '#/components/parameters/paginationLimit'
        - $ref: '#/components/parameters/paginationAsOfTime'
        - $ref: '#/components/parameters/paginationSortOrder'
      responses:
        '200':
          description: List of service accounts returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListServiceAccountsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: CreateServiceAccount
      summary: Create a service account
      description: >-
        Creates a new service account for machine-to-machine authentication.
        Requires ORG_ADMIN role.
      tags:
        - ServiceAccounts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateServiceAccountRequest'
      responses:
        '200':
          description: Service account created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceAccount'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/service-accounts/{id}:
    get:
      operationId: GetServiceAccount
      summary: Get a service account
      description: >-
        Retrieves details of a specific service account by ID.
      tags:
        - ServiceAccounts
      parameters:
        - $ref: '#/components/parameters/resourceId'
      responses:
        '200':
          description: Service account retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceAccount'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: UpdateServiceAccount
      summary: Update a service account
      description: >-
        Updates the name or description of an existing service account. Requires
        ORG_ADMIN role.
      tags:
        - ServiceAccounts
      parameters:
        - $ref: '#/components/parameters/resourceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateServiceAccountSpecification'
      responses:
        '200':
          description: Service account updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceAccount'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: DeleteServiceAccount
      summary: Delete a service account
      description: >-
        Permanently deletes a service account by ID. All associated API keys
        are also revoked. Requires ORG_ADMIN role.
      tags:
        - ServiceAccounts
      parameters:
        - $ref: '#/components/parameters/resourceId'
      responses:
        '200':
          description: Service account deleted successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceAccount'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/folders:
    get:
      operationId: ListFolders
      summary: List folders
      description: >-
        Returns a list of folders in the organization, optionally filtered by
        path. Supports pagination.
      tags:
        - Folders
      parameters:
        - name: path
          in: query
          description: Filter folders by path prefix.
          schema:
            type: string
        - $ref: '#/components/parameters/paginationPage'
        - $ref: '#/components/parameters/paginationLimit'
        - $ref: '#/components/parameters/paginationAsOfTime'
        - $ref: '#/components/parameters/paginationSortOrder'
      responses:
        '200':
          description: List of folders returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListFoldersResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: CreateFolder
      summary: Create a folder
      description: >-
        Creates a new folder for organizing clusters and resources within the
        organization. Requires FOLDER_ADMIN role.
      tags:
        - Folders
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFolderRequest'
      responses:
        '200':
          description: Folder created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Folder'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/folders/{folder_id}:
    get:
      operationId: GetFolder
      summary: Get a folder
      description: >-
        Retrieves details of a specific folder by its ID.
      tags:
        - Folders
      parameters:
        - $ref: '#/components/parameters/folderId'
      responses:
        '200':
          description: Folder retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Folder'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: UpdateFolder
      summary: Update a folder
      description: >-
        Updates the name or parent of an existing folder. Requires FOLDER_ADMIN
        or FOLDER_MOVER role.
      tags:
        - Folders
      parameters:
        - $ref: '#/components/parameters/folderId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateFolderSpecification'
      responses:
        '200':
          description: Folder updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Folder'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: DeleteFolder
      summary: Delete a folder
      description: >-
        Permanently deletes a folder by ID. Requires FOLDER_ADMIN role. The
        folder must be empty before deletion.
      tags:
        - Folders
      parameters:
        - $ref: '#/components/parameters/folderId'
      responses:
        '200':
          description

# --- truncated at 32 KB (117 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cockroach-labs/refs/heads/main/openapi/cockroach-labs-cloud-api-openapi.yml