Storage and Ingest¶

Release binding: v0.1.0-enterprise-ready · AMI ami-010806d4d3445660e · 2026-05-19

Base URL https://<host>:8443. All routes require a tenant key. Every response reports its metering weight in X-HX-CUs; ingest routes additionally report X-HX-Row-CUs. Weights are accounting units, not prices.

PUT /v1/put¶

Ingest one entry. The array is supplied as a base64-encoded .npy payload; the engine decomposes it, evaluates fidelity, and stores the representation.

curl -sk -X PUT https://<host>:8443/v1/put \
  -H "Authorization: Bearer <TENANT_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "doc-001",
    "namespace": "team-a",
    "data_b64": "<base64-encoded .npy>",
    "metadata": {"source": "ingest-job-7"}
  }'

The response carries the stored version, the Oracle verdict (exact, safe, weak, or passthrough), and the entry's compression ratio. Writing the same key again creates a new immutable version.

PUT /v1/put/npy¶

Ingest a raw .npy body directly (binary request body rather than JSON). Use for large single entries where base64 overhead matters.

PUT /v1/put/cores and PUT /v1/put/cores/batch¶

Ingest pre-decomposed representations (cores) produced by a compatible encoder, singly or in batches. Batch ingest is the preferred route for bulk loads through the gate.

Admin bulk ingest¶

POST /v1/admin/ingest/dense/batch ingests dense batches on the admin surface, and POST /v1/admin/ingest/from_exact_corpus builds the serving index in place from a registered raw corpus with no HTTP data transfer. Both require admin authorization. See Admin and Tenants.

GET /v1/get/{namespace}/{key}¶

Retrieve entry metadata and representation details. The stored representation stays native; pass version=N for a specific version, otherwise the latest is returned.

GET /v1/serve/{namespace}/{key}¶

Serve a materialized form of the entry (for example a dense reconstruction) for consumers that need values rather than the representation.

POST /v1/serve/gpu/{namespace}/{key}¶

Ship the entry's cores to GPU VRAM for serving on the device.

GET /v1/list/{namespace}¶

List keys in a namespace the tenant is authorized for.

DELETE /v1/delete/{namespace}/{key}¶

Delete an entry. Deletion is tombstoned; space is reclaimed by compaction (see POST /v1/admin/compact on the admin surface).

Streaming ingest¶

Route	Purpose
`POST /v1/streaming/start`	Open a streaming session for a namespace
`POST /v1/streaming/push`	Push records into the stream
`POST /v1/streaming/stop`	Close the session
`GET /v1/streaming/dashboard`	Session and throughput state
`GET /v1/streaming/dead-letters`	Records that failed ingest, with reasons

Columnar pack¶

Route	Purpose
`POST /v1/columnar/rebuild/{namespace}`	Rebuild the columnar pack for a namespace
`GET /v1/columnar/stats`	Columnar pack state and statistics

Real-time stream¶

WS /v1/ws/stream provides bidirectional JSON frames, tenant-scoped by the gate's WebSocket proxy. Pass the key as the holonomix-api-key.<key> subprotocol.