Skip to content

Native API

Base URL: https://<hub-host>. Every endpoint needs Authorization: Bearer <key> except the probes.

Method Path Notes
GET /livez, /readyz, /healthz probes, no key; /healthz → {"ok","name","version","commit","uptimeSec"}
GET /v1/models models of all online nodes in the key’s scope: id, version, name, task, state, backend, location (peer:<best node>), nodes
GET /v1/models/{id} one model
POST /v1/models/{id}/run image body (JPEG, PNG, WebP, GIF, BMP, HEIF, AVIF; sniffed) ≤ 10 MB → the node’s answer plus servedBy and via
POST /v1/embed the default embedding model; adds legacy dim and embedding
GET /v1/nodes admin or nodes:read keys: full node details; other keys see only {name, reachable, online, models} for nodes in scope
GET /health hub summary
Terminal window
curl -H "Authorization: Bearer $KEY" --data-binary @photo.jpg \
https://<hub-host>/v1/models/efficientnet-lite4-int8/run

Answer:

{
"model": {"id": "efficientnet-lite4-int8", "version": "1.0.0"},
"output": {"labels": [{"label": "…", "score": 0.0}]},
"ms": 72.0,
"backend": "nnapi:mtk-mdla_shim",
"servedBy": "living-room-tv",
"via": "home-hub",
"timings": {"decode": 0.0, "queue": 0.0, "render": 0.0, "pack": 0.0, "invoke": 22.0, "postprocess": 0.0, "total": 0.0}
}

Embedding models answer "output": {"embedding": [ … ]} (L2-normalised unless the manifest says otherwise). timings (0.1 ms resolution) break down one run: decode (bytes → bitmap), queue, load (first run only), render (crop/letterbox), pack (pixels → tensor), invoke (the accelerator), postprocess, total.

Errors always look like {"error":{"code":"busy","message":"…"}}:

Status Codes
400 bad_request
401 unauthorized (missing or wrong key)
403 forbidden (role violation, e.g. a node key on a client endpoint)
404 not_found, model_not_found (also for models outside the key’s scope)
405 method_not_allowed (see Allow)
411 / 413 / 415 length_required, payload_too_large, unsupported_media_type
429 rate_limited (with Retry-After), quota_exceeded (daily quota), busy (queue or node slots full)
500 internal, inference_failed
502 peer_unavailable (node unreachable or gave a bad answer)
503 unavailable (no node can serve the model, or it failed to load)
504 timeout
508 loop_detected (X-Gateway-Hop above 1)

X-Request-ID (8–64 safe characters) is accepted or generated, and returned.