API Reference

HX-SDP exposes a RESTful HTTP API. All data-plane traffic flows through the HX-Gate reverse proxy, which handles authentication, namespace isolation, rate limiting, metering, and audit logging before forwarding to the HX-Engine backend.

Base URL

Environment	URL
Production	https://gate.holonomx.com
Self-hosted	http://<host>:8080

Authentication

Every data-plane request must include a tenant API key:

X-Api-Key: hx_live_abc123...

or

Authorization: Bearer hx_live_abc123...

Admin endpoints use the engine service key instead. See Authentication for details.

Request / response format

• Content-Type: application/json for all JSON endpoints.
• Binary payloads: Base64-encoded in the data_b64 field.
• All responses are JSON with appropriate HTTP status codes.

Common headers

Header	Direction	Description
X-Api-Key	Request	Tenant API key
X-Request-Id	Both	Correlation ID (gate injects if absent)
X-HX-Tenant	Request (injected)	Tenant ID injected by gate into engine requests
X-HX-CUs	Response	Compute Units consumed by the operation

Verb model

HX-SDP uses five core verbs:

Verb	Endpoint prefix	Description
PUT	POST /v1/put	Ingest — compress and store a tensor or blob
GET	GET /v1/get/{ns}/{key}	Retrieve metadata and compression fingerprint
QUERY	POST /v1/query/*	Similarity search — pairwise, top-K, or external vector
SEARCH	POST /v1/search	Metadata-filtered key listing
SERVE	POST /v1/serve	Reconstruct dense array or load TT-cores to GPU VRAM

Additional administrative verbs are documented in the Admin section.

Error responses

All errors return a JSON body:

{
  "detail": "Human-readable error message"
}

Status	Meaning
400	Malformed request (missing key, bad JSON, invalid namespace)
401	Missing or invalid API key
403	Namespace not authorized for this tenant
404	Key not found in the specified namespace
409	Version conflict (optimistic concurrency)
429	Rate limit exceeded — retry after window resets
502	Engine backend unreachable
503	Monthly CU quota exhausted

CU metering

Every operation consumes Compute Units. The X-HX-CUs response header reports the cost. See Billing & Usage for the full cost table and tier definitions.

Pagination

List endpoints return up to 1,000 results by default. Use ?limit=N&offset=M query parameters for pagination.

Next steps

• Storage API — PUT, GET, SERVE, DELETE, LIST
• Query API — pairwise similarity, top-K, vector search, metadata search
• Simulation API — physics simulation dispatch
• Admin API — tenant management, usage, registry reload