Admin API Reference

The full HTTP surface exposed on -metrics-addr (default :2112): health probes, Prometheus metrics, traces, and the /admin/* operational endpoints implemented in adminapi/admin.go and cmd/server/admin_cluster.go — plus the INFO command on the data port, which is where search-index readiness is reported.

Health and metrics endpoints

These are registered in cmd/server/main.go. /healthz and /readyz are served from the moment the process starts, so liveness checks never time out during a slow WAL replay; /metrics, /traces and every /admin/* path are added only after the storage engine has opened and return 404 until then.

curl http://localhost:2112/healthz
curl http://localhost:2112/readyz
curl http://localhost:2112/metrics | head -30
curl "http://localhost:2112/traces?limit=50&error=true"

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, compaction, cache, wal, replication, cdc and top subcommands poll (since v1.14, replication reads /admin/cluster instead). Methods other than GET get 405.

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

Any method other than POST gets 405 POST only; a failed checkpoint returns 500 with the error text.

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. The struct has no JSON tags, so the fields are capitalised: Namespace, WritesPerSec, BurstWrites, MaxKeys, KeyCount, TokensLeft. Methods other than GET/POST get 405 GET or POST.

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"}. Omitted or non-numeric fields are set to 0; the request always replaces the namespace's whole limit.

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: Op, Key, Value (base64, as Go encodes []byte; null for deletes) and Timestamp (µs). It is consumed by the repl-ship cross-region shipper; veltrix cdc-tail reads it too; in v1.12 its formatter looks for lowercase field names, so its op/key columns print — (Fixed in v1.14 it decodes these fields; see CLI Reference).

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 — base64, null for deletes — and Timestamp in µs), ordered by write timestamp, followed by a single trailer line. Methods other than GET get 405.

{"Op":"PUT","Key":"orders/1042","Value":"eyJ0b3RhbCI6NDJ9","Timestamp":1752800000123456}
{"Op":"DEL","Key":"orders/0999","Value":null,"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 the running engine, written by the server process to a local destination directory on the server's filesystem. This (or veltrix backup DEST_DIR, which calls it) is the way to back up a running server: the offline veltrixdb-backup tool opens its own engine on the data dirs and must only be pointed at a stopped server's directories — against a live server it truncated the live wal.log and vlog_active.dat in testing. The endpoint is always registered by cmd/server. On v1.16 and earlier, restart the node cleanly after an online backup — writes made after it are lost on a crash until then (see above).

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"}'

curl -X POST http://localhost:2112/admin/backup \
  -d '{"type":"incremental","dest_dir":"/backup/2026-07-05-1500","base_dir":"/backup/2026-07-05"}'

Response includes status, type, backup_id, dest_dir (and base_dir for incremental), num_disks, duration_ms, and the full manifest object. Errors: 400 for a bad body, a missing dest_dir, a missing or unreadable base_dir, or an unknown type; 500 if the backup itself fails; 405 for non-POST. veltrix backup DEST_DIR sends {"type":"full","dest_dir":DEST_DIR}.

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

veltrix nodes renders this endpoint as a table. The same JSON, on one line, is returned by the TOPOLOGY text command on the data port — that is what the bundled cluster-aware client (client.NewClient) uses to build its consistent-hash ring and find the Raft leader, so it needs no admin access. Non-GET methods get 405.

GET / POST /admin/cluster/members, DELETE /admin/cluster/members/{id} New on main after v1.16 — ships in the next release

Online membership changes (cmd/server/membership.go), with the same auth as every other /admin/* endpoint. Needs --mode=raft or --mode=replicated (otherwise 400). Any node accepts a change and forwards it to the raft leader or the replicated-mode coordinator over the transfer listener, which requires --cluster-secret-file or --cluster-mtls. Procedures: membership runbook.

curl http://localhost:2112/admin/cluster/members
curl -X POST http://localhost:2112/admin/cluster/members \
  -d '{"id":"n4","addr":"10.0.0.14:9000","wait_ms":60000}'
curl -X DELETE 'http://localhost:2112/admin/cluster/members/n2?wait_ms=120000'
curl -X DELETE 'http://localhost:2112/admin/cluster/members/r2?force=true'   # replicated: dead node, no drain

POST body: id, addr (the node's client --addr) and optional wait_ms. DELETE query: force=true (replicated: remove without draining — writes the dead node acknowledged but never replicated are lost) and wait_ms. Answers: 200 done; 202 raft learner added, promotion still pending; 400 bad request or last voter; 404 unknown id; 409 duplicate id, a change already in progress, a concurrent replicated change, or a failed drain; 503 no reachable quorum, no leader, or coordinator unreachable. CLI: veltrix cluster members | add-node ID@HOST:PORT | remove-node ID [--force] [--wait-ms N].

INFO (data port, not HTTP)

INFO is a text-protocol command on -addr (default :9000), not an HTTP endpoint, but it is the one place a node reports whether its search indexes are ready. With -auth-config it needs the admin permission. The reply is one line of key=value pairs:

$ printf 'INFO\nQUIT\n' | nc 127.0.0.1 9000
keys=1203 writes=5120 reads=880 deletes=4 cache_hits=812 cache_misses=68 hit_rate=0.92 wal_flushes=311 compaction_runs=0 version=5128 search_ready=0 search_loaded=4100/9000 disk[0]=./veltrixdb-data:12.4MB
BYE

The binary INFO frame (0x05) returns a shorter string — keys, writes, reads, cache_hit_rate, wal_flushes — without the search fields, so use the text command to poll readiness. veltrix-admin stats prints the text reply 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