Cluster API v2.0

On this page Carat arrow pointing down
Warning:
CockroachDB v21.2 is no longer supported as of May 16, 2023. For more details, refer to the Release Support Policy.

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 DB Console 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/). Additional endpoints are planned for future versions of CockroachDB.

Each listed endpoint links to its full API reference documentation.

Endpoint Name Description
/databases List databases Get all databases in the cluster.
/databases/{database} Get database details Get the descriptor ID of a specified database.
/databases/{database}/grants List database grants List all privileges granted to users for a specified database.
/databases/{database}/tables List database tables List all tables in a specified database.
/databases/{database}/tables/{table} Get table details Get details on a specified table, including schema, grants, indexes, range count, and zone configuration.
/events List events List the latest events on the cluster, in descending order.

Deprecated: Use an external log sink or configure alerting on specific log events instead.
/health Check node health Determine if the node is running and ready to accept SQL connections.
/nodes List nodes Get details on all nodes in the cluster, including node IDs, software versions, and hardware.
/nodes/{node_id}/ranges List node ranges Get details on the ranges on a specified node.
/ranges/hot List hot ranges Get information on ranges receiving a high number of reads or writes.
/ranges/{range_id} Get range details Get detailed technical information on a range. Typically used by Cockroach Labs engineers.
/sessions List sessions Get SQL session details of all current users or a specified user.
/users List users List all SQL users on the cluster.
/login Log in Authenticate as a SQL role that is a member of the admin role to retrieve a session token to use with further API calls.
/logout Log out Invalidate the session token.

Requirements

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

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 cockroach auth-session 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:

    icon/buttons/copy
    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.

    icon/buttons/copy
    {"session":"CIGAiPis4fj3CBIQ3u0rRQJ3tD8yIqee4hipow=="}
    
  3. Pass the token with each call using the X-Cockroach-API-Session header. For example:

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

Versioning and Stability

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). Minor versions could add new endpoints but will not remove existing endpoints.


Yes No
On this page

Yes No