Sbom Service API Reference

Operations

POST /api/change-traces/build

Builds a deterministic change trace document for the supplied tenant and artifact digest pair. Accepts modern fromDigest/toDigest fields and legacy fromScanId/toScanId compatibility fields.

Responses:

GET /api/change-traces/{traceId}

Reconstructs a deterministic change trace document from a shareable traceId without requiring persisted trace blobs.

Parameters:

Responses:

GET /api/compare/baselines/{scanDigest}

Returns baseline scan recommendations for delta comparison. Returns empty recommendations when no previous scans are available.

Parameters:

Responses:

POST /api/v1/artifact-links

Creates or updates a source/build/image/SBOM/scan artifact association. OCI image subjects require immutable sha256 digests, source snapshots require repoUrl plus commitSha, and weak evidence creates candidates only.

Responses:

GET /api/v1/artifact-links/candidates

Lists strong candidate artifact links that still need operator confirmation or deterministic evidence verification.

Parameters:

Responses:

POST /api/v1/artifact-links/import

Imports a related source/build/image/SBOM/scan/detector bundle and creates deterministic first-class artifact links for every supplied relationship.

Responses:

GET /api/v1/artifact-links/resolve

Resolves an artifact association graph by subject key, image digest, SBOM digest, scan job ID, or source repo URL plus commit SHA.

Parameters:

Responses:

GET /api/v1/artifact-links/unlinked

Lists artifact subjects with no non-rejected links so operators can resolve missing source/image/SBOM/scan associations.

Parameters:

Responses:

POST /api/v1/artifact-links/{linkId}/confirm

Confirms an artifact link from the UI or CLI and promotes it to verified UI-confirmed evidence.

Parameters:

Responses:

POST /api/v1/artifact-links/{linkId}/reject

Rejects an artifact association candidate and removes it from resolved graphs while retaining audit history.

Parameters:

Responses:

POST /api/v1/artifact-links/{linkId}/verify

Re-evaluates an artifact link confidence from its stored evidence type and promotes strong evidence to verified.

Parameters:

Responses:

GET /api/v1/buildinfo

API alias for /buildinfo.json (same payload).

Responses:

GET /api/v1/lineage/compare

Returns a rich comparison between two artifact versions by lineage digest (a and b) for the given tenant. Optionally includes SBOM diff, VEX deltas, reachability deltas, attestations, and replay hashes. Returns 404 if comparison data is not found.

Parameters:

Responses:

POST /api/v1/lineage/compare-drift

Compares two replay hashes (hashA and hashB) for the given tenant to detect drift between two release decision points. Returns a structured drift report indicating whether the two points are equivalent. Requires hashA, hashB, and tenantId.

Responses:

GET /api/v1/lineage/diff

Returns a graph-level diff between two artifact lineage graphs identified by their digests (from and to) for the given tenant. Highlights added and removed nodes and edges between two artifact versions. Returns 404 if either graph is not found.

Parameters:

Responses:

POST /api/v1/lineage/export

Exports the lineage evidence pack between two artifact digests for the given tenant as a structured bundle. Enforces a 50 MB size limit on the export payload. Returns 413 if the export exceeds the size limit. Requires fromDigest, toDigest, and tenantId in the request body.

Responses:

GET /api/v1/lineage/hover

Returns a lightweight hover card summary of the lineage relationship between two artifact digests for the given tenant. Used for fast UI hover popups. Cached for low-latency responses. Returns 404 if no hover card data is available.

Parameters:

Responses:

POST /api/v1/lineage/verify

Verifies a deterministic replay hash against the current policy and SBOM state to confirm the release decision is reproducible. Optionally re-evaluates the policy against current feeds. Requires replayHash and tenantId in the request body.

Responses:

GET /api/v1/lineage/{artifactDigest}

Returns the lineage graph for a specific artifact by digest for the given tenant, including upstream provenance nodes up to maxDepth levels, optional trust badges, and an optional deterministic replay hash. Returns 404 if the graph is not found.

Parameters:

Responses:

GET /api/v1/lineage/{artifactDigest}/children

Returns the direct child artifacts in the lineage graph for a specific artifact digest and tenant. Lists artifacts that were built from or derived from the specified artifact.

Parameters:

Responses:

GET /api/v1/lineage/{artifactDigest}/parents

Returns the direct parent artifacts in the lineage graph for a specific artifact digest and tenant. Lists artifacts from which the specified artifact was built or derived.

Parameters:

Responses:

GET /api/v1/registry-sources

Parameters:

Responses:

POST /api/v1/registry-sources

Responses:

POST /api/v1/registry-sources/test

Responses:

GET /api/v1/registry-sources/{id}

Parameters:

Responses:

PUT /api/v1/registry-sources/{id}

Parameters:

Responses:

DELETE /api/v1/registry-sources/{id}

Parameters:

Responses:

POST /api/v1/registry-sources/{id}/discover-and-scan

Parameters:

Responses:

GET /api/v1/registry-sources/{id}/discover/images

Parameters:

Responses:

GET /api/v1/registry-sources/{id}/discover/repositories

Parameters:

Responses:

GET /api/v1/registry-sources/{id}/discover/tags/{repository}

Parameters:

Responses:

GET /api/v1/registry-sources/{id}/images

Parameters:

Responses:

GET /api/v1/registry-sources/{id}/images/sbom

Parameters:

Responses:

POST /api/v1/registry-sources/{id}/pause

Parameters:

Responses:

POST /api/v1/registry-sources/{id}/resume

Parameters:

Responses:

GET /api/v1/registry-sources/{id}/runs

Parameters:

Responses:

POST /api/v1/registry-sources/{id}/test

Parameters:

Responses:

POST /api/v1/registry-sources/{id}/trigger

Parameters:

Responses:

GET /api/v1/sbom/ledger/diff

Canonical v1 API alias for /sbom/ledger/diff. Required so the Console SBOM A/B diff round-trips via the gateway’s /api/v1/sbom(.*) regex.

Parameters:

Responses:

GET /api/v1/sbom/production-answer

Returns the authenticated tenant’s bounded SBOM production answer: accepted CycloneDX/SPDX versions, canonical ingest routes, and the latest persisted SBOM per artifact with stored producer provenance and a format-preserving raw-document export handoff when available. Items cap at 100 while totalProduced remains exact.

Parameters:

Responses:

GET /api/v1/sbom/subject/{subjectRef}/cyclonedx

Returns the raw CycloneDX SBOM document (byte-for-byte verbatim) for the given subject (artifact ref), tenant-scoped by the authenticated stellaops:tenant claim. Optional ?version=<guid|latest> selects a specific ledger version (default latest). 200 with application/json (or application/vnd.cyclonedx+json when requested via Accept). 404 when no SBOM exists for that subject/tenant - never fabricated. Consumed by the ExportCenter audit bundle.

Parameters:

Responses:

GET /api/v1/sbom/subject/{subjectRef}/document

Returns the raw uploaded SBOM document byte-for-byte for the authenticated tenant using its stored media type (CycloneDX JSON or SPDX JSON). Optional version selects a ledger version; missing tenant ownership or missing legacy sidecar returns 404 rather than fabricated content.

Parameters:

Responses:

POST /api/v1/sbom/upload

Canonical v1 API path alias for UploadSbom. Uploads and ingests a new SBOM for the specified artifact, validating the payload and persisting it to the ledger. Returns 202 Accepted with the artifact reference and ledger entry on success.

Responses:

GET /api/v1/sbom/uploads

Canonical v1 API GET path for uploaded SBOMs (alias for /sbom/ledger/history). Returns the paginated ledger history for the artifact query parameter. Required so SBOM uploads round-trip via the gateway’s /api/v1/sbom(.*) regex without being silently shadowed by the SPA fallback. Returns 404 when no uploads exist for the artifact.

Parameters:

Responses:

GET /api/v1/sbom/uploads/{artifactRef}

Canonical v1 API GET-by-artifact path for uploaded SBOMs (alias for /sbom/ledger/history). The artifactRef route parameter is URL-decoded before lookup so the gateway can pass artifact references that contain ‘:’ and ‘/’ verbatim. Returns the paginated ledger history. Returns 404 when no uploads exist.

Parameters:

Responses:

GET /api/v1/sbom/versions

Canonical v1 API alias for /sbom/versions. Required so the Console SBOM A/B diff version picker round-trips via the gateway’s /api/v1/sbom(.*) regex.

Parameters:

Responses:

GET /api/v1/scan/results

Vuln/scan report by subject (artifact ref or digest), tenant-scoped by the authenticated stellaops:tenant claim. Proxies Scanner’s canonical artifact vulnerability report endpoint and returns Scanner 200 JSON verbatim; Scanner 404/empty remains 404 so audit bundles omit the section; Scanner transport failures return a non-placeholder 503.

Parameters:

Responses:

GET /buildinfo.json

Image build provenance (module, gitSha, gitCommitTime, imageBuiltAt, branch) for drift detection.

Responses:

GET /components/lookup

Looks up the authenticated tenant’s component read model by PURL, optionally filtered by artifact. Neighbors are keyed by tenant (migration 006); another tenant’s rows - and legacy rows with no tenant - are never returned.

Parameters:

Responses:

GET /console/sboms

Returns the authenticated tenant’s paginated SBOM catalog, optionally filtered by artifact name, license, scope, and asset tag. Rows are keyed by tenant (migration 006); another tenant’s rows - and legacy rows with no tenant - are never returned.

Parameters:

Responses:

GET /entrypoints

Returns all registered service entrypoints for the authenticated tenant, listing artifact, service, path, scope, and runtime flag for each. An optional tenant query value is accepted only as a matching assertion.

Parameters:

Responses:

POST /entrypoints

Creates or updates a service entrypoint for the authenticated tenant linking an artifact to a service path. Returns the full updated entrypoint list. The optional tenant body value is a matching assertion; artifact, service, and path are required.

Responses:

GET /healthz

Returns liveness status of the SBOM service. Always returns 200 OK with status ‘ok’ when the process is running. Used by infrastructure liveness probes.

Responses:

GET /internal/orchestrator/control

Internal endpoint. Returns the current orchestrator control state for the given tenant including pause/resume flags and scheduling overrides. Requires tenant query parameter.

Parameters:

Responses:

POST /internal/orchestrator/control

Internal endpoint. Updates the orchestrator control state for the given tenant, allowing operators to pause, resume, or adjust scheduling parameters. Requires tenantId in the request body.

Responses:

GET /internal/orchestrator/sources

Internal endpoint. Returns all registered orchestrator artifact sources for the given tenant. Requires tenant query parameter.

Parameters:

Responses:

POST /internal/orchestrator/sources

Internal endpoint. Registers a new orchestrator artifact source for the given tenant linking an artifact digest to a source type. Requires tenantId, artifactDigest, and sourceType in the request body.

Responses:

GET /internal/orchestrator/watermarks

Internal endpoint. Returns the current ingestion watermark state for the given tenant, indicating the last successfully processed position in the artifact stream. Requires tenant query parameter.

Parameters:

Responses:

POST /internal/orchestrator/watermarks

Internal endpoint. Sets the ingestion watermark for the given tenant to the specified value, marking the last processed position in the artifact stream. Requires tenant query parameter.

Parameters:

Responses:

GET /internal/sbom/analysis/jobs

Internal endpoint. Returns the chronologically ordered list of SBOM analysis jobs for a specific artifact. Requires artifact query parameter.

Parameters:

Responses:

GET /internal/sbom/asset-events

Internal endpoint. Returns all SBOM asset-level events from the configured event store. Used by orchestrators to process asset lifecycle changes associated with SBOM versions.

Responses:

GET /internal/sbom/events

Internal endpoint. Returns all SBOM version-created events in the configured event store backlog. Logs a warning if the backlog exceeds 100 entries. Used by orchestrators to process pending SBOM ingestion events.

Responses:

POST /internal/sbom/events/backfill

Internal endpoint. Replays all known SBOM projections as version-created events into the event store backlog. Used for backfill and recovery scenarios after store resets. Returns the count of successfully published events.

Responses:

GET /internal/sbom/inventory

Internal endpoint. Returns all SBOM inventory entries from the event store, representing the known set of artifacts and their SBOM state across tenants.

Responses:

POST /internal/sbom/inventory/backfill

Internal endpoint. Clears and replays the SBOM inventory by re-fetching projections for known snapshot/tenant pairs. Used for recovery after inventory store resets. Returns the count of replayed entries.

Responses:

GET /internal/sbom/ledger/audit

Internal endpoint. Returns the chronologically ordered audit trail for a specific artifact from the SBOM ledger, listing all state transitions and operations. Requires artifact query parameter.

Parameters:

Responses:

GET /internal/sbom/resolver-feed

Internal endpoint. Returns all resolver feed candidates from the event store. The resolver feed is used by the policy engine and scanner to resolve component identities across SBOM versions.

Responses:

POST /internal/sbom/resolver-feed/backfill

Internal endpoint. Clears and replays the resolver feed by re-fetching projections for known snapshot/tenant pairs. Used for recovery after resolver store resets. Returns the count of re-published resolver feed entries.

Responses:

GET /internal/sbom/resolver-feed/export

Internal endpoint. Exports all resolver feed candidates as a newline-delimited JSON (NDJSON) stream. Used for bulk export and offline processing of the resolver feed by external consumers.

Responses:

POST /internal/sbom/retention/prune

Internal endpoint. Applies the configured retention policy to the SBOM ledger, pruning old versions beyond the configured min/max version counts. Records pruned version counts in metrics. Returns a retention result summary.

Responses:

GET /readyz

Returns readiness status of the SBOM service. Returns 200 with status ‘warming’ while the service is starting up. Used by infrastructure readiness probes.

Responses:

GET /sbom/context

Returns an assembled SBOM context for an artifact. Timeline and persisted dependency-path data are both read under the authenticated tenant; another tenant’s graph rows and legacy tenantless rows are never returned.

Parameters:

Responses:

GET /sbom/ledger/diff

Returns a component-level diff between two SBOM ledger entries identified by their GUIDs (before and after). Highlights added, removed, and changed components between two SBOM versions. Returns 404 if either entry is not found.

Parameters:

Responses:

GET /sbom/ledger/history

Returns the paginated ledger history for a specific artifact, listing SBOM versions in chronological order with ledger metadata. Requires artifact query parameter. Returns 404 if no history is found.

Parameters:

Responses:

GET /sbom/ledger/lineage

Returns the full artifact lineage chain from the SBOM ledger for a specific artifact, showing the provenance ancestry of SBOM versions. Requires artifact query parameter. Returns 404 if lineage is not found.

Parameters:

Responses:

GET /sbom/ledger/point

Returns the SBOM ledger entry for a specific artifact at a given point in time. Requires artifact and at (ISO-8601 timestamp) query parameters. Returns 404 if no ledger entry exists for the specified time.

Parameters:

Responses:

GET /sbom/ledger/range

Returns paginated SBOM ledger entries for a specific artifact within a time range defined by start and end ISO-8601 timestamps. Requires artifact, start, and end query parameters. Returns 404 if no data is found for the range.

Parameters:

Responses:

GET /sbom/paths

Returns deterministic dependency paths from uploaded CycloneDX or SPDX edges for the authenticated tenant. Coverage and truncation fields distinguish complete, partial, zero-edge, and unavailable graphs; paths are never synthesized for orphan components.

Parameters:

Responses:

POST /sbom/upload

Uploads and ingests a new SBOM for the specified artifact, validating the payload and persisting it to the ledger. Returns 202 Accepted with the artifact reference and ledger entry on success. Returns 400 if validation fails.

Responses:

GET /sbom/versions

Returns the paginated version timeline for a specific artifact, listing SBOM snapshots in chronological order. Requires artifact query parameter. Limit must be between 1 and 200.

Parameters:

Responses:

GET /sboms/{snapshotId}/projection

Returns the structured SBOM projection for a specific snapshot ID and tenant. The projection contains the full normalized component graph with schema version and a deterministic hash. Used by the policy engine and reachability graph for decision-making.

Parameters:

Responses: