HTTP APIs

Every CockroachDB node serves HTTP on port 8080 (default). The surface is split into four prefixes.

/api/v2/

The newest, OpenAPI-style API. Source: pkg/server/api_v2*.go. Used by the DB Console.

Endpoint group	File	What it covers
/api/v2/sql/	api_v2_sql.go	Run SQL via REST
/api/v2/databases/	api_v2_databases_metadata.go	Database/table metadata
/api/v2/grants/	api_v2_grants.go	Grants by user/role
/api/v2/ranges/	api_v2_ranges.go	Range location info
/api/v2/sql_schema/	api_v2_sql_schema.go	Schema introspection

Authentication uses session cookies issued by pkg/server/authserver/.

/_admin/v1/

Older REST API focused on cluster administration. Source: pkg/server/admin.go (~125 KB). Endpoints include cluster settings management, jobs, locations, decommissioning, table stats, hot ranges, and user/role admin.

/_status/

Read-only observability API. Source: pkg/server/status.go (~155 KB). Endpoints include nodes, ranges, replicas, problem ranges, sessions, statements, contention events, profiling, traces, and Prometheus metrics at /_status/vars.

/debug/

The debug routes for in-process introspection:

• /debug/pprof/... — Go's standard CPU/heap/goroutine profiles.
• /debug/requests — net/trace events.
• /debug/events — net/trace event log.
• /debug/logspy — tail logs over HTTP.
• /debug/zip — a single endpoint that produces the same zip as cockroach debug zip.
• /debug/stores/<id> — per-store info.
• /debug/range_log — range-event log.
• /debug/keyvis — key visualizer (pkg/keyvisualizer/).

Other endpoints

• /health — load-balancer health probe.
• /health?ready=1 — readiness probe (drain-aware).
• /_join/v1 — node-join handshake.
• /ts/query — time-series query endpoint used by the DB Console.
• /_internal/* — endpoints used internally by tenant <-> host orchestration.

Authentication

The HTTP server enforces:

• Session cookies for browser-driven access, issued by pkg/server/authserver/oidc.go (OIDC) or auth.go (login form).
• Bearer tokens for /api/v2/ programmatic access.
• None for /health and /health?ready=1.

Tenant routing happens via the tenant_name cookie (set by the controller) or the X-CockroachDB-Tenant header.

Related pages

• systems/server — server lifecycle and listeners.
• systems/security — auth providers.
• features/multi-tenant — tenant-aware routing.