Cluster API v2.0

The CockroachDB Cluster API is a REST API that provides information about a cluster and its nodes. The API offers programmatic access to much of the information available in the user interface, enabling you to monitor and troubleshoot your cluster using your choice of tooling.

The Cluster API is hosted by all nodes of your cluster and provides information about all nodes. The API is available on the same port that is listening for HTTP connections to the DB Console. This defaults to 8080 and can be specified using --http-addr={server}:{port} when configuring your node.

Resources

The following endpoints are available as URLs under the /api/v2 base path (for example, https://localhost:8080/api/v2/health/). For more information about the support policies for endpoints, see .

Each listed endpoint links to its full .

Endpoint	Name	Description	Support
	List databases	Get all databases in the cluster.	Stable
	Get database details	Get the descriptor ID of a specified database.	Stable
	List database grants	List all granted to users for a specified database.	Stable
	List database tables	List all tables in a specified database.	Stable
	Get table details	Get details on a specified table, including schema, grants, indexes, range count, and .	Stable
	List events	List the latest on the cluster, in descending order.	Unstable
	Check node health	Determine if the node is running and ready to accept SQL connections.	Stable
	List nodes	Get details on all nodes in the cluster, including node IDs, software versions, and hardware.	Stable
	List node ranges	Get details on the ranges on a specified node.	Unstable
	List hot ranges	Get information on ranges receiving a high number of reads or writes.	Stable
	Get range details	Get detailed technical information on a range. Typically used by Cockroach Labs engineers.	Unstable
	List sessions	Get SQL session details of all current users or a specified user.	Unstable
	List users	List all SQL users on the cluster.	Stable
	Log in	Authenticate as a that is a member of the to retrieve a session token to use with further API calls.	Stable
	Log out	Invalidate the session token.	Stable

Requirements

All endpoints except /health and /login require authentication using a session token. To obtain a session token, you will need:

• A that is a member of the and has login permissions and a password.

To connect with the API on a secure cluster, you will need:

• The CA cert used by the cluster or any intermediary proxy server, either in the client’s cert store as a trusted certificate authority or as a file manually specified by the HTTP request (for example, using curl’s cacert ).

Authentication

To create and manage web sessions and authentication tokens to the Cluster API from the command line, use the CLI command.

Alternatively, you may also request a token directly from the /login endpoint using the following instructions:

1. Request a session token using the /login endpoint. For example:

   curl -d "username=user&password=pass" \
   -H 'Content-Type: application/x-www-form-urlencoded' \
   https://localhost:8080/api/v2/login/
   

2. Record the token (session value) that is returned.

   {"session":"CIGAiPis4fj3CBIQ3u0rRQJ3tD8yIqee4hipow=="}
   

3. Pass the token with each call using the X-Cockroach-API-Session header. For example:

   curl -H "X-Cockroach-API-Session: CIGAiPis4fj3CBIQ3u0rRQJ3tD8yIqee4hipow==" \
   https://localhost:8080/api/v2/nodes/
   

Versioning and stability

The Cluster API version is defined in the request path. For example: <cluster/api/v2/health.

Future versions of CockroachDB may provide multiple API versions and will continue to provide access to this v2.0 API until it is deprecated.

All endpoint paths and payloads will remain available within a major API version number (v2.x). Patch versions could add new endpoints but will not remove existing endpoints. For more information, see .