Model endpoints

The endpoints that register, admit, version and activate an ONNX model held in object storage.

ONNX models held in object storage. The lifecycle is the workflow’s. A registration carries the manifest, which is the orion:model@1.0.0 JSON document, and an artifact reference. The reference is a storage connector, an object key and the sha256: digest the bytes must hash to. It never carries the bytes. The manifest itself may name where its bytes are twice, for the two places it is read. artifact is a path relative to the manifest, read only by the offline tooling. lint reports the graph’s stats from it, dry-run and test run the model from it, and compile hashes it. reference is { "connector", "key" }, where a pipeline put the same bytes for a serving instance. compile writes that into a package’s models[] entry, beside the digest of the local file. A served row ignores both — the request’s artifact reference is its authority — and neither is required. The server validates the manifest and checks the connector exists and allows reads (operations.presign_get). It confirms the object is there and within models.max_artifact_bytes, writes the draft, and answers 202. The node’s admission worker then fetches the object through the connector and verifies the digest.

It reads the graph: parameter and node counts, the distinct operators it asks a runtime for, IR version and opset. The parameter count is every value the graph carries, in its initializers or in its nodes’ attributes, through every subgraph body. Every manifest input and output must name a graph tensor, and models.max_parameters applies.

It then probes the model on the node’s default runtime for the manifest’s format ([models.default_runtime]). The probe is five inferences over zero-filled inputs. Any named dimension runs at the manifest’s probe_dims, 1 where it says nothing, and the binding is recorded in stats.probe_dims. The median must be within models.max_probe_ms, and the outputs must have the dtypes and shapes the manifest declares.

The verdict lands on the row as admission (pending → passed | failed) with a stage and a reason, plus stats. The stages are signature, gate, head, size, fetch, digest, cache, parse and probe. Activation is refused until the verdict is passed. Every route answers 400 on a node with models.enabled = false.

# Register from a manifest, naming the object in the `models` storage connector
jq -n --slurpfile manifest model.json \
  --arg digest "sha256:$(sha256sum c4-tiny.onnx | cut -d' ' -f1)" \
  '{manifest: $manifest[0], artifact: {connector: "models", key: "c4-tiny.onnx", digest: $digest}}' \
  | curl -s -X POST http://localhost:8080/api/v1/admin/models \
      -H 'Content-Type: application/json' --data @-

# Poll for the verdict: admission.state is pending, then passed or failed
curl -s http://localhost:8080/api/v1/admin/models/ada.c4-tiny | jq '.data.admission'

# Activate once it has passed; the engine reloads
curl -s -X PATCH http://localhost:8080/api/v1/admin/models/ada.c4-tiny/status \
  -H 'Content-Type: application/json' -d '{"status":"active"}'

# Export the references, for a promotion — the target fetches the bytes itself
curl -s "http://localhost:8080/api/v1/admin/models/export?tag=vision" | jq '.data' > models.json

Related

• Admin API: every admin resource, and the contracts they share.
• Models: what a model is, and what it is for.
• Model settings: the [models] block a node needs before any of this works.
• Serve a model: the same endpoints, as a walkthrough.

Last verified 14 September 2026