API Reference¶
Release binding: v0.1.0-enterprise-ready · AMI ami-010806d4d3445660e · 2026-05-19
Base URL: https://<host>:8443
All data-plane traffic passes through hx-gate (authentication, namespace ACL, rate limiting, metering, audit) and is forwarded to the engine on loopback. There is one environment: the customer's appliance.
Authentication: Authorization: Bearer <key> or X-Api-Key: <key>. See Authentication.
Surface¶
57 /v1/* routes in 18 categories, one WebSocket stream, and two probes.
| Category | Endpoints |
|---|---|
| Ingest (write) | PUT /v1/put, PUT /v1/put/npy, PUT /v1/put/cores, PUT /v1/put/cores/batch, POST /v1/admin/ingest/dense/batch, POST /v1/admin/ingest/from_exact_corpus |
| Retrieve | GET /v1/get/{namespace}/{key}, GET /v1/serve/{namespace}/{key}, GET /v1/list/{namespace} |
| Delete | DELETE /v1/delete/{namespace}/{key} |
| Query, approximate | POST /v1/query/similarity, POST /v1/query/topk, POST /v1/query/vector |
| Query, EXACT (R@100% contract, ML-DSA-65 receipt) | POST /v1/query/exact |
| Rerank (two-tier) | POST /v1/rerank, POST /v1/rerank/vector |
| Search | POST /v1/search, POST /v1/search/text, POST /v1/search/hybrid, POST /v1/search/fuzzy, POST /v1/search/autocomplete, POST /v1/search/highlight |
| Feature serving | POST /v1/features/serve, POST /v1/features/batch |
| Server-side metadata ops | POST /v1/aggregate, POST /v1/eval, POST /v1/append, POST /v1/getrange |
| Streaming ingest | POST /v1/streaming/push, POST /v1/streaming/start, POST /v1/streaming/stop, GET /v1/streaming/dashboard, GET /v1/streaming/dead-letters |
| Columnar pack | POST /v1/columnar/rebuild/{namespace}, GET /v1/columnar/stats |
| GPU serve | POST /v1/serve/gpu/{namespace}/{key} |
| Admin and diagnostics | GET /v1/admin/diagnostics, GET /v1/stats |
| Exact corpus registry | POST /v1/admin/corpus/register, GET /v1/admin/corpus, DELETE /v1/admin/corpus/{namespace} |
| Intelligence and telemetry | GET /v1/intelligence/dashboard, GET /v1/intelligence/accuracy, GET /v1/intelligence/alerts, GET /v1/intelligence/billing, GET /v1/intelligence/calibration, GET /v1/intelligence/rescue |
| Attestation (third-party verify) | POST /v1/attestation/verify |
| Console (UI-backing) | GET /v1/console/runtime, GET /v1/console/gpu, GET /v1/console/namespaces, GET /v1/console/representations, GET /v1/console/certification, GET /v1/console/commands, POST /v1/console/execute, GET /v1/console/traces, GET /v1/console/search |
| Real-time telemetry | WS /v1/ws/stream (tenant-scoped, holonomix-api-key.<key> subprotocol) |
| Probes | GET /health, GET /metrics |
Similarity metric names are cosine, dot, and l2.
Metering headers¶
Every operation reports its metering weight in X-HX-CUs, and row-weighted operations additionally report X-HX-Row-CUs. Weights are accounting units, not prices. See Metering.
Errors¶
| Status | Meaning |
|---|---|
| 400 | Malformed request |
| 401 | Missing or invalid API key |
| 403 | Namespace not in the tenant's ACL |
| 404 | Key not found |
| 409 | Version conflict, or, on the EXACT path, no corpus registered for the namespace |
| 429 | Rate limit exceeded (Retry-After set) |
| 502 | Engine unreachable |
| 503 | Engine not ready, admission control under load (never OOM), EXACT-path signing unavailable, or a tenant CU quota exhausted where an operator has set one |
Reference pages¶
- Storage and Ingest: put, get, serve, list, delete, streaming, columnar
- Query and Search: approximate query, EXACT with signed receipts, rerank, search, features, metadata ops
- Admin and Tenants: gate onboarding and administration, corpus registry, diagnostics