openapi: 3.1.0
info:
  title: CockroachDB Cloud APIKeys Clusters 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/
servers:
- url: https://cockroachlabs.cloud
  description: CockroachDB Cloud Production Server
security:
- bearerAuth: []
tags:
- name: Clusters
  description: Create, list, retrieve, update, and delete CockroachDB Serverless and Dedicated clusters within an organization.
paths:
  /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'
components:
  schemas:
    AvailableRegion:
      type: object
      description: A cloud provider region available for cluster deployment.
      properties:
        name:
          type: string
          description: Cloud region identifier.
        provider:
          type: string
          description: Cloud provider the region belongs to.
        serverless:
          type: boolean
          description: Whether this region supports Serverless clusters.
    DedicatedClusterConfig:
      type: object
      description: Configuration specific to CockroachDB Dedicated clusters.
      properties:
        machine_type:
          type: string
          description: Machine type used for cluster nodes.
        num_virtual_cpus:
          type: integer
          description: Number of virtual CPUs per node.
        storage_gib:
          type: integer
          description: Storage capacity per node in gibibytes.
        memory_gib:
          type: number
          description: Memory per node in gibibytes.
        disk_iops:
          type: integer
          description: Disk IOPS allocated per node.
    PaginationResponse:
      type: object
      description: Pagination metadata included in list responses.
      properties:
        next:
          type: string
          description: Token or cursor for retrieving the next page of results.
        last:
          type: string
          description: Token or cursor for the last page of results.
        time:
          type: string
          format: date-time
          description: Server time at which the paginated query was executed.
    Cluster:
      type: object
      description: Represents a CockroachDB Cloud cluster, which is an instance of CockroachDB running in one or more cloud regions on Serverless or Dedicated infrastructure.
      required:
      - id
      - name
      - cloud_provider
      - state
      - operation_status
      - plan
      - regions
      - cockroach_version
      - creator_id
      properties:
        id:
          type: string
          description: Unique identifier of the cluster.
        name:
          type: string
          description: Human-readable name of the cluster.
        cloud_provider:
          type: string
          description: Cloud infrastructure provider hosting the cluster.
          enum:
          - GCP
          - AWS
          - AZURE
        cockroach_version:
          type: string
          description: Version of CockroachDB running on the cluster.
        plan:
          type: string
          description: Service tier of the cluster.
          enum:
          - DEDICATED
          - SERVERLESS
        state:
          type: string
          description: Overall state of the cluster.
        operation_status:
          type: string
          description: Current operational status of the cluster.
        regions:
          type: array
          description: Cloud provider regions where the cluster is deployed.
          items:
            $ref: '#/components/schemas/Region'
        config:
          $ref: '#/components/schemas/ClusterConfig'
        creator_id:
          type: string
          description: Identifier of the user who created the cluster.
        created_at:
          type: string
          format: date-time
          description: Timestamp when the cluster was created.
        updated_at:
          type: string
          format: date-time
          description: Timestamp of the most recent modification.
        deleted_at:
          type: string
          format: date-time
          description: Timestamp when the cluster was deleted, if applicable.
        sql_dns:
          type: string
          description: DNS hostname for SQL connections to the cluster.
        upgrade_status:
          type: string
          description: Status of any in-progress version upgrade.
        account_id:
          type: string
          description: Cloud provider account ID associated with the cluster.
        parent_id:
          type: string
          description: ID of the folder containing this cluster, if any.
        labels:
          type: object
          description: Key-value labels for resource organization.
          additionalProperties:
            type: string
        delete_protection:
          type: string
          description: Whether delete protection is enabled on the cluster.
        egress_traffic_policy:
          type: string
          description: Policy governing outbound traffic from the cluster.
        network_visibility:
          type: string
          description: Network accessibility configuration of the cluster.
    ServerlessClusterConfig:
      type: object
      description: Configuration specific to CockroachDB Serverless clusters.
      properties:
        spend_limit:
          type: integer
          description: Monthly spend limit in US cents. 0 means no limit.
        routing_id:
          type: string
          description: Unique routing identifier for the serverless cluster.
        usage_limits:
          type: object
          description: Usage-based limits for request units and storage.
    ListClusterNodesResponse:
      type: object
      description: Paginated list of nodes in a cluster.
      properties:
        nodes:
          type: array
          description: Array of node objects.
          items:
            $ref: '#/components/schemas/ClusterNode'
        pagination:
          $ref: '#/components/schemas/PaginationResponse'
    Error:
      type: object
      description: Standard error response returned by the API.
      properties:
        code:
          type: integer
          description: HTTP status code of the error.
        message:
          type: string
          description: Human-readable description of the error.
        details:
          type: array
          description: Additional detail objects providing error context.
          items:
            type: object
    ClusterNode:
      type: object
      description: Represents an individual node within a CockroachDB cluster.
      properties:
        name:
          type: string
          description: Node name or identifier.
        region_name:
          type: string
          description: Cloud region the node is deployed in.
        status:
          type: string
          description: Current operational status of the node.
    GetConnectionStringResponse:
      type: object
      description: Connection string for a cluster.
      properties:
        connection_string:
          type: string
          description: Formatted connection string for the cluster.
    UpdateClusterSpecification:
      type: object
      description: Specification for modifying an existing cluster's configuration.
      properties:
        dedicated:
          type: object
          description: Updated dedicated cluster configuration fields.
        serverless:
          type: object
          description: Updated serverless cluster configuration fields.
        cockroach_version:
          type: string
          description: Target CockroachDB version for the upgrade.
    CreateClusterRequest:
      type: object
      description: Request body for creating a new CockroachDB Cloud cluster.
      required:
      - name
      - provider
      - spec
      properties:
        name:
          type: string
          description: Name for the new cluster.
          maxLength: 40
        provider:
          type: string
          description: Cloud provider to host the cluster.
          enum:
          - GCP
          - AWS
          - AZURE
        spec:
          type: object
          description: Cluster specification, either a ServerlessClusterCreateSpecification or DedicatedClusterCreateSpecification.
        regions:
          type: array
          description: List of regions to deploy the cluster in.
          items:
            type: string
        parent_id:
          type: string
          description: Folder ID to place the cluster in, if applicable.
    Region:
      type: object
      description: A geographic region where the cluster or its nodes are deployed.
      required:
      - name
      properties:
        name:
          type: string
          description: Cloud provider region identifier (e.g. us-east-1).
        sql_dns:
          type: string
          description: DNS hostname for SQL connections routed to this region.
        node_count:
          type: integer
          description: Number of nodes in this region.
    ClusterConfig:
      type: object
      description: Configuration settings for a CockroachDB cluster.
      properties:
        serverless:
          $ref: '#/components/schemas/ServerlessClusterConfig'
        dedicated:
          $ref: '#/components/schemas/DedicatedClusterConfig'
    ListAvailableRegionsResponse:
      type: object
      description: Paginated list of available cloud regions.
      properties:
        regions:
          type: array
          description: Array of available region objects.
          items:
            $ref: '#/components/schemas/AvailableRegion'
        pagination:
          $ref: '#/components/schemas/PaginationResponse'
    ListMajorClusterVersionsResponse:
      type: object
      description: List of available major CockroachDB versions.
      properties:
        versions:
          type: array
          description: Array of version objects.
          items:
            type: object
            properties:
              version:
                type: string
                description: Major version string.
    ListClustersResponse:
      type: object
      description: Paginated list of clusters in the organization.
      properties:
        clusters:
          type: array
          description: Array of cluster objects.
          items:
            $ref: '#/components/schemas/Cluster'
        pagination:
          $ref: '#/components/schemas/PaginationResponse'
  parameters:
    paginationAsOfTime:
      name: pagination.as_of_time
      in: query
      description: RFC3339 timestamp to return results as they were at a specific point in time (time-travel query).
      schema:
        type: string
        format: date-time
    paginationPage:
      name: pagination.page
      in: query
      description: Page number for paginated results, starting from 1.
      schema:
        type: string
    showInactive:
      name: show_inactive
      in: query
      description: If true, inactive clusters are included in the response.
      schema:
        type: boolean
    paginationLimit:
      name: pagination.limit
      in: query
      description: Maximum number of results to return per page.
      schema:
        type: integer
        format: int32
        minimum: 1
        maximum: 500
    paginationSortOrder:
      name: pagination.sort_order
      in: query
      description: Sort direction for paginated results. Accepted values are ASC and DESC.
      schema:
        type: string
        enum:
        - ASC
        - DESC
    clusterId:
      name: cluster_id
      in: path
      required: true
      description: Unique identifier of the CockroachDB Cloud cluster.
      schema:
        type: string
  responses:
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication credentials are missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: The request body or parameters are invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication. Generate a token in the CockroachDB Cloud Console under Organization Settings > API Access.
externalDocs:
  description: CockroachDB Cloud API Documentation
  url: https://www.cockroachlabs.com/docs/cockroachcloud/cloud-api