openapi: 3.1.0
info:
  title: CockroachDB Cloud APIKeys Nodes 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: Nodes
  description: Retrieve information about all nodes in the cluster, including their status, address, locality, and operational metrics.
paths:
  /api/v2/nodes/:
    get:
      operationId: ListNodes
      summary: List nodes
      description: Returns information about all nodes in the cluster, including each node's address, build information, locality, store metrics, and operational status. Requires admin-level authentication.
      tags:
      - Nodes
      parameters:
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: List of cluster nodes returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListNodesResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
components:
  parameters:
    offset:
      name: offset
      in: query
      description: Number of results to skip before returning data. Used for offset-based pagination.
      schema:
        type: integer
        format: int32
        minimum: 0
    limit:
      name: limit
      in: query
      description: Maximum number of results to return in a single response.
      schema:
        type: integer
        format: int32
        minimum: 1
        maximum: 1000
  schemas:
    BuildInfo:
      type: object
      description: Build and version metadata for the CockroachDB binary on a node.
      properties:
        go_version:
          type: string
          description: Go runtime version used to build CockroachDB.
        tag:
          type: string
          description: Git tag of the CockroachDB release.
        time:
          type: string
          description: Build timestamp.
        revision:
          type: string
          description: Git revision hash of the build.
        cgo_compiler:
          type: string
          description: CGO compiler version used in the build.
        platform:
          type: string
          description: Target platform for the build (e.g. linux amd64).
        distribution:
          type: string
          description: CockroachDB distribution type (e.g. CCL or OSS).
        type:
          type: string
          description: Build type (e.g. release or development).
        channel:
          type: string
          description: Release channel the binary belongs to.
    Address:
      type: object
      description: Network address of a CockroachDB node.
      properties:
        network_field:
          type: string
          description: Network protocol (e.g. tcp).
        address_field:
          type: string
          description: Host and port of the node (e.g. 10.0.0.1:26257).
    NodeStatus:
      type: object
      description: Status and metadata for a single node in the CockroachDB cluster, including address, build details, locality, store information, and activity metrics.
      properties:
        desc:
          $ref: '#/components/schemas/NodeDescriptor'
        build_info:
          $ref: '#/components/schemas/BuildInfo'
        started_at:
          type: integer
          format: int64
          description: Unix nanosecond timestamp when the node process started.
        updated_at:
          type: integer
          format: int64
          description: Unix nanosecond timestamp of the most recent status update.
        metrics:
          type: object
          description: Map of metric name to value for this node, covering CPU, memory, disk, network, and SQL throughput metrics.
          additionalProperties:
            type: number
        store_statuses:
          type: array
          description: Status objects for each store (disk) on this node.
          items:
            type: object
        args:
          type: array
          description: Command-line arguments the node process was started with.
          items:
            type: string
        env:
          type: array
          description: Environment variables set in the node process.
          items:
            type: string
        activity:
          type: object
          description: Per-node activity metrics including bytes sent and received.
    Locality:
      type: object
      description: Geographic or topological locality tiers assigned to the node, used for zone configuration and replica placement.
      properties:
        tiers:
          type: array
          description: Ordered list of locality tiers from most general to most specific.
          items:
            type: object
            properties:
              key:
                type: string
                description: Locality tier key (e.g. region, zone, rack).
              value:
                type: string
                description: Locality tier value (e.g. us-east-1, us-east-1a).
    Error:
      type: object
      description: Standard error response returned by the Cluster API.
      properties:
        error:
          type: string
          description: Human-readable description of the error.
    ListNodesResponse:
      type: object
      description: List of nodes in the CockroachDB cluster with pagination metadata.
      properties:
        nodes:
          type: array
          description: Array of node status objects.
          items:
            $ref: '#/components/schemas/NodeStatus'
        next:
          type: integer
          description: Offset value to use to retrieve the next page of results. Absent when there are no more results.
    NodeDescriptor:
      type: object
      description: Identifies and locates a specific node within the CockroachDB cluster.
      properties:
        node_id:
          type: integer
          format: int32
          description: Numeric identifier of the node.
        address:
          $ref: '#/components/schemas/Address'
        attrs:
          type: object
          description: Node attribute key-value pairs used for zone configuration.
        locality:
          $ref: '#/components/schemas/Locality'
        server_version:
          type: object
          description: CockroachDB server version running on this node.
        build_tag:
          type: string
          description: Build tag string for the CockroachDB binary.
        started_at:
          type: integer
          format: int64
          description: Unix nanosecond timestamp when the node started.
        cluster_name:
          type: string
          description: Name of the cluster this node belongs to.
        sql_address:
          $ref: '#/components/schemas/Address'
  responses:
    Forbidden:
      description: The authenticated user does not have admin privileges required to access this endpoint.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication is required. The X-Cockroach-API-Session header is missing or the session has expired.
      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