Admin API Reference

The full HTTP surface exposed on -metrics-addr (default :2112): health probes, Prometheus metrics, and the /admin/* operational endpoints implemented in adminapi/admin.go and cmd/server/admin_cluster.go.

Health and metrics endpoints

These are registered directly in cmd/server/main.go, before the storage engine finishes initializing, so liveness checks never time out during a slow WAL replay.

curl http://localhost:2112/healthz
curl http://localhost:2112/readyz
curl http://localhost:2112/metrics | head -30
curl http://localhost:2112/traces

GET /admin/stats

Returns a full JSON snapshot of engine state: index size, cumulative op counters, cache stats, WAL totals, CDC counters, per-disk VLog stats, and namespace list. This is the endpoint the veltrix status, veltrix compaction, veltrix cache, and veltrix top subcommands poll.

curl http://localhost:2112/admin/stats

Response shape (fields read directly from handleStats in adminapi/admin.go):

GET /admin/version

Returns the on-disk schema version and whether at-rest encryption is enabled.

curl http://localhost:2112/admin/version

POST /admin/checkpoint

Forces an immediate WAL checkpoint across all disks. Synchronous — the HTTP response is delayed until the checkpoint completes.

curl -X POST http://localhost:2112/admin/checkpoint

Non-POST requests receive 405 GET or POST is not accepted here — only POST is allowed.

GET / POST /admin/quotas

Reads or mutates per-namespace rate-limit and key-count quotas (token-bucket write throttling plus a hard key-count cap).

GET — list current quotas

curl http://localhost:2112/admin/quotas

Returns a JSON array of storage.QuotaSnapshot objects, one per namespace with a configured limit.

POST — set a namespace quota

Accepts form-encoded parameters (not JSON):

curl -X POST http://localhost:2112/admin/quotas \
  -d "ns=tenant_42&writes_per_sec=5000&burst=10000&max_keys=1000000"

Response: {"status": "ok", "ns": "tenant_42"}.

POST /admin/migrate

Runs schema migrations across all keys currently below current_schema_version.

curl -X POST http://localhost:2112/admin/migrate

This is also the endpoint kubectl veltrix migrate calls (see CLI Reference).

GET /admin/cdc

Streams live change-data-capture events as newline-delimited JSON (application/x-ndjson) until the client disconnects, an optional duration elapses, or the subscription is evicted for being a slow consumer.

curl "http://localhost:2112/admin/cdc?prefix=orders/&duration_seconds=60"

Each streamed line is one JSON-encoded storage.CDCEvent (operation type, key, and related metadata — consumed directly by veltrix cdc-tail and by the repl-ship cross-region shipper).

GET /admin/changes

v1.1.0 The durable catch-up feed backing cross-region replication (storage.ChangesSince). Where /admin/cdc streams live events, /admin/changes scans the index for entries written at or after a microsecond cursor — so a shipper that persists its "last shipped timestamp" can replay the delta it missed while down, then rejoin the live stream. This is what repl-ship --checkpoint calls on restart.

curl "http://localhost:2112/admin/changes?since=1752800000000000&limit=1000"

The response is newline-delimited JSON (application/x-ndjson): one storage.CDCEvent per line (Op "PUT" or "DEL", Key, Value — empty for deletes — and Timestamp in µs), ordered by write timestamp, followed by a single trailer line:

{"Op":"PUT","Key":"orders/1042","Value":"...","Timestamp":1752800000123456}
{"Op":"DEL","Key":"orders/0999","Timestamp":1752800000234567}
{"cursor":1752800000234567,"more":false}

Semantics worth knowing before building on it:

• The boundary is inclusive (>= since), and pagination resumes from the last returned event's timestamp — so events sharing the checkpoint's exact microsecond re-ship rather than being lost. Destination applies are last-write-wins Puts/Deletes, so replays are harmless; consumers must be idempotent.
• Tombstones are included (Op:"DEL") — deletes made during shipper downtime reach the remote region too. Expired-TTL entries are skipped (they expire remotely on their own).
• The cursor is the single node's clock (WriteTimestampUs, monotone in practice); the same value is carried as Timestamp on the live /admin/cdc path, so the two feeds share one checkpoint.

POST /admin/backup

Triggers a full or incremental backup from a live engine, writing to a local destination directory on the server's filesystem. Only registered when the server is started with a non-nil BackupEngine (always true for cmd/server).

Request body (JSON):

{
  "type": "full",
  "dest_dir": "/backup/2026-07-05",
  "base_dir": ""
}

curl -X POST http://localhost:2112/admin/backup \
  -H "Content-Type: application/json" \
  -d '{"type":"full","dest_dir":"/backup/2026-07-05"}'

Response includes status, type, backup_id, dest_dir, num_disks, duration_ms, and the full manifest object. This is what veltrix backup DEST_DIR calls under the hood.

GET /admin/cluster (alias: /admin/topology)

Returns the live distributed-layer topology: node role, Raft term/leader (in raft mode), replication lag (in replicated mode), partition count, and fencing epoch. Registered separately from the rest of the admin API, in cmd/server/admin_cluster.go, via registerClusterAdmin.

curl http://localhost:2112/admin/cluster

This is the endpoint the bundled cluster-aware client (client.NewClient) calls to bootstrap consistent-hash routing and discover the current Raft leader, and it is what veltrix nodes renders as a table.

GET /admin/ui

Serves the built-in HTML/JS web dashboard (implemented in adminapi/ui.go). Also mounted as the catch-all at /admin/, so any unmatched path under /admin/ falls through to the dashboard.

open http://localhost:2112/admin/ui

Endpoint summary