openapi: 3.1.0
info:
title: CockroachDB Cluster 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. It is
available on the same HTTP port used by the DB Console, defaulting to
port 8080, and exposes endpoints under the /api/v2 base path. The API
enables monitoring and troubleshooting workflows using any HTTP-capable
tooling. Authentication requires requesting a session token via the
/api/v2/login/ endpoint and passing it with subsequent requests using the
X-Cockroach-API-Session header.
version: '2.0.0'
contact:
name: Cockroach Labs Support
url: https://support.cockroachlabs.com
termsOfService: https://www.cockroachlabs.com/cloud-terms-and-conditions/
externalDocs:
description: CockroachDB Cluster API Documentation
url: https://www.cockroachlabs.com/docs/stable/cluster-api
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.
tags:
- name: Auth
description: >-
Authenticate to the Cluster API by creating and terminating API sessions.
Session tokens are passed via the X-Cockroach-API-Session header on
subsequent requests.
- name: Health
description: >-
Check the health and readiness of individual CockroachDB nodes. The
health endpoint can report whether the node is live and fully operational
for accepting SQL connections.
- name: Nodes
description: >-
Retrieve information about all nodes in the cluster, including their
status, address, locality, and operational metrics.
- name: Ranges
description: >-
List and inspect range information for the cluster, including hot ranges
by node and detailed information for specific range IDs.
- name: Rules
description: >-
Retrieve alerting rules templates for use with Prometheus-compatible
alerting systems.
- name: Sessions
description: >-
List active SQL sessions across all nodes of the cluster, with optional
filtering by username.
security:
- sessionAuth: []
paths:
/api/v2/login/:
post:
operationId: Login
summary: Create a session
description: >-
Creates an authenticated API session by supplying valid SQL username
and password credentials. Returns a session token in the
X-Cockroach-API-Session response header. This token must be included
as the X-Cockroach-API-Session header on all subsequent requests to
authenticated endpoints.
tags:
- Auth
security: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/LoginRequest'
responses:
'200':
description: >-
Session created successfully. The session token is returned in the
X-Cockroach-API-Session response header.
headers:
X-Cockroach-API-Session:
description: Session token to use for authenticating subsequent requests.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/LoginResponse'
'401':
$ref: '#/components/responses/Unauthorized'
/api/v2/logout/:
post:
operationId: Logout
summary: Terminate a session
description: >-
Terminates a previously established API session, invalidating the
session token. The X-Cockroach-API-Session header must be included
with the session token to revoke.
tags:
- Auth
responses:
'200':
description: Session terminated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/LogoutResponse'
'401':
$ref: '#/components/responses/Unauthorized'
/api/v2/health/:
get:
operationId: Health
summary: Check node health
description: >-
Reports the health of the CockroachDB node. When the optional ready
parameter is set to true, the endpoint also verifies that the node is
fully operational and ready to accept SQL connections. Returns HTTP 200
if healthy, or HTTP 500 if not ready. This endpoint does not require
authentication.
tags:
- Health
security: []
parameters:
- name: ready
in: query
description: >-
If true, checks whether the node is fully ready to accept SQL
connections in addition to being live.
schema:
type: boolean
responses:
'200':
description: Node is healthy and, if ready was requested, fully operational.
content:
application/json:
schema:
$ref: '#/components/schemas/HealthResponse'
'500':
description: Node is not ready to accept SQL connections.
content:
application/json:
schema:
$ref: '#/components/schemas/HealthResponse'
/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'
/api/v2/nodes/{node_id}/ranges/:
get:
operationId: ListNodeRanges
summary: List ranges for a node
description: >-
Returns information about ranges stored on the specified node. If a
list of range IDs is provided via the ranges query parameter, only
information about those specific ranges is returned. Requires admin
authentication.
tags:
- Ranges
parameters:
- $ref: '#/components/parameters/nodeId'
- name: ranges
in: query
description: >-
Comma-separated list of range IDs to filter results. If omitted,
all ranges on the node are returned.
schema:
type: string
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
responses:
'200':
description: Range information for the node returned successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/ListNodeRangesResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
/api/v2/ranges/hot/:
get:
operationId: ListHotRanges
summary: List hot ranges
description: >-
Returns information about hot ranges across the cluster, ranked by
query activity. Optionally filter by node ID to return only hot ranges
on a specific node. Requires admin authentication.
tags:
- Ranges
parameters:
- name: node_id
in: query
description: >-
Filter hot ranges by the ID of the node to query. If omitted,
hot ranges across all nodes are returned.
schema:
type: integer
format: int32
- $ref: '#/components/parameters/limit'
- name: start
in: query
description: Pagination cursor for the starting position in the result set.
schema:
type: integer
format: int32
responses:
'200':
description: Hot ranges returned successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/ListHotRangesResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
/api/v2/ranges/{range_id}/:
get:
operationId: GetRange
summary: Get a range
description: >-
Retrieves detailed information about a specific range identified by
range_id, including replica placement, lease holder, and statistics.
Requires admin authentication.
tags:
- Ranges
parameters:
- $ref: '#/components/parameters/rangeId'
responses:
'200':
description: Range information returned successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/RangeResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
/api/v2/sessions/:
get:
operationId: ListSessions
summary: List sessions
description: >-
Returns a list of all active SQL sessions across all nodes of the
cluster. Optionally filter by username to return only sessions for
a specific SQL user. Supports pagination via limit and start parameters.
Requires admin authentication.
tags:
- Sessions
parameters:
- name: username
in: query
description: Filter sessions by SQL username.
schema:
type: string
- $ref: '#/components/parameters/limit'
- name: start
in: query
description: Pagination cursor for the starting position in the result set.
schema:
type: integer
format: int32
responses:
'200':
description: List of active sessions returned successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/ListSessionsResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
/api/v2/rules/:
get:
operationId: GetAlertingRules
summary: Get alerting rules
description: >-
Returns a Prometheus-compatible alerting rules template that can be
used to configure alerting for CockroachDB cluster health and
performance metrics. This endpoint does not require authentication.
tags:
- Rules
security: []
responses:
'200':
description: Alerting rules template returned successfully.
content:
application/yaml:
schema:
type: string
description: >-
YAML-formatted Prometheus alerting rules template for
monitoring CockroachDB cluster health.
components:
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.
parameters:
nodeId:
name: node_id
in: path
required: true
description: Numeric identifier of the CockroachDB node.
schema:
type: integer
format: int32
rangeId:
name: range_id
in: path
required: true
description: Numeric identifier of the range.
schema:
type: integer
format: int64
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'
NotFound:
description: The requested resource was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
Error:
type: object
description: Standard error response returned by the Cluster API.
properties:
error:
type: string
description: Human-readable description of the error.
LoginRequest:
type: object
description: Credentials for authenticating to the Cluster API.
required:
- username
- password
properties:
username:
type: string
description: SQL username to authenticate with.
password:
type: string
description: Password for the SQL user.
format: password
LoginResponse:
type: object
description: Response from a successful login request.
properties:
session:
type: string
description: >-
Session token. Also returned in the X-Cockroach-API-Session
response header for convenience.
LogoutResponse:
type: object
description: Response from a logout request confirming session termination.
properties:
logged_out:
type: boolean
description: True if the session was successfully terminated.
HealthResponse:
type: object
description: Health status of the CockroachDB node.
properties:
node_id:
type: integer
description: Numeric identifier of the responding node.
ready:
type: boolean
description: >-
True if the node is fully operational and ready to accept SQL
connections.
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.
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.
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'
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).
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).
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.
ListNodeRangesResponse:
type: object
description: Range information for a specific node with pagination metadata.
properties:
ranges:
type: array
description: Array of range information objects for the node.
items:
$ref: '#/components/schemas/RangeInfo'
next:
type: integer
description: Offset for retrieving the next page of results.
RangeInfo:
type: object
description: >-
Information about a single range, including span, replica placement,
lease holder, and per-replica statistics.
properties:
desc:
$ref: '#/components/schemas/RangeDescriptor'
span:
type: object
description: Key span covered by this range.
source_node_id:
type: integer
description: Node ID that provided this range information.
source_store_id:
type: integer
description: Store ID on the source node that holds this range.
error_message:
type: string
description: Error message if range information could not be retrieved.
lease_holder:
type: integer
description: Store ID of the current leaseholder replica.
raft_state:
type: string
description: Raft consensus state of this range (e.g. Leader, Follower).
stats:
type: object
description: Aggregate statistics for the range including key/value counts.
RangeDescriptor:
type: object
description: Describes a range's identity, key bounds, and replica set.
properties:
range_id:
type: integer
format: int64
description: Unique identifier of the range.
start_key:
type: string
description: Base64-encoded start key of the range.
end_key:
type: string
description: Base64-encoded end key of the range.
internal_replicas:
type: array
description: List of replicas for this range.
items:
type: object
properties:
node_id:
type: integer
description: Node hosting this replica.
store_id:
type: integer
description: Store on the node hosting this replica.
replica_id:
type: integer
description: Unique identifier of this replica within the range.
ListHotRangesResponse:
type: object
description: Hot ranges across the cluster or filtered to a specific node.
properties:
ranges:
type: array
description: Array of hot range objects sorted by activity level.
items:
$ref: '#/components/schemas/HotRange'
next:
type: integer
description: Pagination cursor for the next page of hot range results.
HotRange:
type: object
description: >-
A range identified as hot due to elevated query activity, including the
range descriptor and per-second query throughput.
properties:
range_id:
type: integer
format: int64
description: Unique identifier of the hot range.
node_id:
type: integer
description: Node ID of the node reporting this hot range.
qps:
type: number
format: double
description: Queries per second observed on this range.
table_name:
type: string
description: Name of the table this range belongs to, if known.
db_name:
type: string
description: Name of the database this range belongs to, if known.
index_name:
type: string
description: Name of the index this range belongs to, if known.
schema_name:
type: string
description: Schema name for the table this range belongs to, if known.
RangeResponse:
type: object
description: Detailed information about a specific range from all replicas.
properties:
range_id:
type: integer
format: int64
description: Unique identifier of the range.
responses_by_node_id:
type: object
description: >-
Map of node ID to the range information reported by that node's
replica.
additionalProperties:
$ref: '#/components/schemas/RangeInfo'
ListSessionsResponse:
type: object
description: List of active SQL sessions across all cluster nodes.
properties:
sessions:
type: array
description: Array of active session objects.
items:
$ref: '#/components/schemas/Session'
errors:
type: array
description: >-
Errors encountered while collecting session data from individual
nodes. Sessions from healthy nodes are still returned.
items:
type: object
properties:
node_id:
type: integer
description: Node ID that returned an error.
message:
type: string
description: Error message from the node.
next:
type: integer
description: Pagination cursor for the next page of session results.
Session:
type: object
description: >-
An active SQL session on the CockroachDB cluster, representing a
connection from a client application.
properties:
node_id:
type: integer
description: Node ID where this session is being served.
username:
type: string
description: SQL username of the session.
client_address:
type: string
description: Network address of the client (host:port).
application_name:
type: string
description: Application name reported by the SQL client driver.
start:
type: string
format: date-time
description: Timestamp when the session was established.
last_active_query:
type: string
description: Most recently executed SQL query in this session.
id:
type: string
description: Unique identifier of the session.
alloc_bytes:
type: integer
format: int64
description: Memory allocated by this session in bytes.
max_alloc_bytes:
type: integer
format: int64
description: Peak memory allocation for this session in bytes.
active_queries:
type: array
description: Currently executing queries within this session.
items:
type: object
active_txn:
type: object
description: Currently active transaction within this session, if any.