HTTP API

REST API on port 6480 for web clients and services.

Endpoints

Execute SQL

curl -X POST http://localhost:6480/v1/query \
  -H "Authorization: Bearer ndb_..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.nodedb.v1+json" \
  -d '{"sql": "SELECT * FROM users LIMIT 10"}'

Stream Results (NDJSON)

curl -X POST http://localhost:6480/v1/query/stream \
  -d '{"sql": "SELECT * FROM large_table"}'

Health & Readiness

curl http://localhost:6480/healthz        # k8s readiness — 503 until startup completes
curl http://localhost:6480/health/live    # liveness probe
curl http://localhost:6480/health/ready   # WAL recovered, ready for queries

Prometheus Metrics

curl http://localhost:6480/metrics

70+ system metrics: per-engine, per-core, connection, query, replication, storage. Latency histogram with 13 buckets.

PromQL

http://localhost:6480/v1/obsv/api

Full Prometheus query engine. Point Grafana at this URL as a Prometheus data source.

CDC Streams

GET /v1/streams/{stream}/events?group={group}   # SSE
GET /v1/streams/{stream}/poll?group={group}      # Long-poll

WebSocket

/v1/ws endpoint for JSON-RPC: SQL execution, LIVE SELECT delivery, session reconnect.

Versioning

All non-probe routes are under the /v1/ prefix. JSON responses carry Content-Type: application/vnd.nodedb.v1+json; charset=utf-8. Clients may opt into version negotiation by sending Accept: application/vnd.nodedb.v1+json; sending only an unsupported application/vnd.nodedb.vN+json returns 406 Not Acceptable. Probe routes (/healthz, /health/*, /metrics) are unversioned and always reachable, including during startup.