Cockroach Labs Nodes API

openapi: 3.2.0
info:
  title: CockroachDB Cluster Nodes API
  description: The CockroachDB Cluster API is a REST API hosted by all nodes of a CockroachDB cluster that provides programmatic access to cluster status, node information, session data, range details, and alerting rules.
  version: 2.0.0
  contact:
    name: Cockroach Labs Support
    url: https://support.cockroachlabs.com
  termsOfService: https://www.cockroachlabs.com/cloud-terms-and-conditions/
servers:
- url: https://localhost:8080
  description: CockroachDB node HTTP port. Replace localhost with the host and 8080 with the configured --http-port of the target node.
security:
- sessionAuth: []
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:
  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.
    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).
    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.
    Error:
      type: object
      description: Standard error response returned by the Cluster API.
      properties:
        error:
          type: string
          description: Human-readable description of the error.
    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).
    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'
    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.
  parameters:
    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
    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
  responses:
    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'
    Forbidden:
      description: The authenticated user does not have admin privileges required to access this endpoint.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    sessionAuth:
      type: apiKey
      in: header
      name: X-Cockroach-API-Session
      description: Session token obtained from the /api/v2/login/ endpoint. Include this header with all authenticated requests.
externalDocs:
  description: CockroachDB Cluster API Documentation
  url: https://www.cockroachlabs.com/docs/stable/cluster-api