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"?,"vector_encoding"?}. replicas 0–2. Zero is the certified path. 1 or 2 starts async WAL replicas; the primary still acks locally. vector_encoding is sq8 (default) or float32.
  • POST /api/tenants/promote — fail over to a replica without restarting that replica engine; AUTH identity unchanged
  • POST /api/tenants/backup — mutation-consistent archive, SHA-256 manifest and checkpoint_id
  • POST /api/tenants/restore — validate and swap, rollback on failure; recovery verifies vector seals
  • POST /api/tenants/delete — stop; purge: true erases that directory only and returns a forget receipt
  • 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. Optional SPACE name writes a named modality graph beside the default index. Embeddings are caller-provided; DBX does not run a model.

  • VADD / VADD_BATCH — optional SPACE name
  • VDEL — generation tombstone; optional SPACE
  • VCOMPACT — tenant-admin; rewrite active rows and rebuild HNSW
  • VSEARCH — cosine, top-k last. Flags: WITHDOCS, FILTER_CONTAINS, MIN_SCORE, EF, SPACE, AS_OF
  • VMIGRATE START/ADD/SWAP/CANCEL — WAL-durable shadow-index lifecycle; supply re-embedded vectors and promote a non-empty target
  • VSIM — neighbors of a stored id (self excluded); same flags as VSEARCH
  • VFUSE — late-fusion across named spaces (SPACE s floats… repeated, optional WEIGHTS w1,w2)

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

Support capability API — v1.3.0

GET /api/support/v1/snapshot returns allowlisted tenant summaries using a dedicated read token. Optional POST /api/support/v1/tenants/{id}/wake requires a separate wake token, an exact tenant allowlist, a hibernated tenant, and durable audit. The server enforces a five-minute cooldown per tenant and process.

Configure DBX_SUPPORT_READ_TOKEN and DBX_SUPPORT_READ_TENANTS; optional wake uses DBX_SUPPORT_WAKE_TOKEN and DBX_SUPPORT_WAKE_TENANTS. The support API is disabled by default. Full contract · Release announcement.

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.