Sbom
Package sbom is what is inside a container image: every component, resolvable by digest or image ref.
Package sbom is what is inside a container image: every component, resolvable by digest or image ref.
| Base URL | https://api.hanzo.ai |
| Operations | 3 |
| Auth | Authorization: Bearer $HANZO_API_KEY |
sbom
GET /v1/sbom/{wildcard1}
Resolve everything inside a container image
Answers with the component set of one container image — each component's name, version, type, package URL and license — addressed by either the image digest or the image ref. The captured segment is greedy and percent-decoded, so a ref carrying slashes and a tag is passed whole.
This read is GLOBAL, not tenant-scoped, and deliberately so: a bill of materials belongs to a content-addressed digest rather than to an org, so every caller deploying the same image resolves the same components, and nothing tenant-owned is exposed by it. Ingest is the gated half of the pair.
A miss is not the end of the lookup. The registry is the source of truth, so an unmaterialized ref is pulled from the SBOM attached to that image, persisted, and answered from the store — the first read of a freshly built image pays for the pull, later ones do not. A bare digest with no repository is not pullable and answers an honest 404, as does a ref with no attached document. Repeated ingests collapse to the latest, components come back ordered by type then name, and a result over 5000 components is capped with truncated set. When the datastore is not connected the answer is 503 rather than a fabricated empty image.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
wildcard1 | path | string | yes |
GET /v1/sbom/health
Health is a pure liveness probe: the service is up; datastore reflects whether the datastore store is connected. Not JWT-gated, always 200 (a disconnected datastore is degraded-but-alive; the data endpoints report that as 503).
POST /v1/sbom
Ingest persists a CycloneDX SBOM's components keyed by image digest. Gated to a validated SuperAdmin (owner == AdminOrg) — the canonical cloud super-admin check, which the build fleet / CI carries. Re-ingest is idempotent: rows share the (digest, name, version, purl) ORDER BY, so ReplacingMergeTree keeps the latest by ingested_at (and resolve reads FINAL).
Request body — application/json (required)
| Field | Type | Required | Description |
|---|---|---|---|
document | — | Document is the raw CycloneDX bill of materials, any JSON. | |
format | string | — | Format names the document format; "cyclonedx" is the only one parsed. |
gitSha | string | — | GitSha is the commit the image was built from. |
imageDigest | string | — | ImageDigest is the content-addressed digest (sha256:…) the components are keyed under. |
imageRef | string | — | ImageRef is the human-readable image reference the digest was published as. |
sourceRepo | string | — | SourceRepo is the repository the image was built from. |
How is this guide?