Docs

API reference

The public application data plane is authenticated RESP on port 6380. The first command must be AUTH <tenantID>:<keyID> <secret>. HTTP /t/{tenantID}/query requires an operator JWT and is for the dashboard, not a public tenant API.

POST /api/login

Issue a JWT. Body: {"username":"admin","password":"…"}. Send Content-Type: application/json. Response field is token.

Tenants

  • GET /api/tenants — list
  • POST /api/provision — {"id","name","replicas"?}. replicas 0–2. Zero is the certified path. 1 or 2 starts async WAL replicas; the primary still acks locally.
  • POST /api/tenants/promote — fail over to a replica; AUTH identity unchanged
  • POST /api/tenants/backup — mutation-consistent archive, SHA-256 manifest
  • POST /api/tenants/restore — validate and swap, rollback on failure
  • POST /api/tenants/delete — stop; purge: true erases that directory only
  • GET /api/v1/tenants/{id}/usage — keys, vectors, memory, disk, commands
  • GET /api/usage — the same meter for every tenant
  • POST /api/tenants/export / import — portable tenant archive
  • POST /api/v1/tenants/{id}/hibernate and /wake — evict a cold engine

Keys

/api/v1/tenants/{id}/keys — POST creates a 256-bit key (name, role reader/writer/tenant-admin, optional key_patterns). GET lists metadata. DELETE revokes immediately, including existing RESP connections. Secret hashes are never returned. The dashboard Tenant keys page is this API. Orchestrator tenants have no default superuser.

KV (v1 durable)

SET (optional EX), SETEX, GET DEL KEYS EXPIRE TTL PERSIST MSET MGET. Hashes, lists, sets, sorted sets, streams, JSON, bitmap, geo, transactions, pub/sub, FLUSH*, cluster, and replication mutations are not in the v1 contract and fail before dispatch.

Vectors

Index key first, so one tenant can hold several indexes.

  • VADD / VADD_BATCH
  • VDEL — generation tombstone
  • VCOMPACT — tenant-admin; rewrite active rows and rebuild HNSW
  • VSEARCH — cosine, top-k last

There is no VGET or VSET. Recall and latency gates are on the performance page.

Metrics

GET /t/{tenantID}/metrics — JSON command/latency/memory snapshot. Orchestrator GET /metrics is Prometheus text with per-tenant labels. Production requires Authorization: Bearer (operator JWT or DBX_INTERNAL_API_TOKEN). -insecure-http leaves it open for local scrapes. Tenant engines also expose /usage and /metrics/prometheus to the internal token.