Trust metadata: summary and detail views

The trust metadata API is the canonical discovery surface for release trust attachments. It exposes two views: a fact-first summary that tells you which categories of trust artifacts are present, and a full detail view that gives you everything you need to independently retrieve, inspect, and verify each attachment. Both views are read-only and require no authentication.

Endpoints

# Summary view — scopeless
GET /api/v1/volumes/{name}/{version}/trust/summary

# Summary view — scoped
GET /api/v1/volumes/@{scope}/{name}/{version}/trust/summary

# Detail view — scopeless
GET /api/v1/volumes/{name}/{version}/trust/detail

# Detail view — scoped
GET /api/v1/volumes/@{scope}/{name}/{version}/trust/detail

Summary view

The summary view is fact-first: it reports observable facts about which trust attachment categories are present. A bibliotheca may include optional judgments, but derived judgments are non-canonical policy outcomes and are not substitutes for raw trust facts or independent verification.

Summary response fields

object

required

The release subject this summary is bound to.

Show subject fields

string

required

Canonical pkg:volume/...@version logical identity of the release.

string

required

sha256:<hex> immutable content identity of the release.

object[]

required

Array of trust artifact category summaries. May be empty when the release exists but no trust artifacts have been attached yet.

Show artifact item fields

string

required

Trust artifact category: bom, provenance, signature, or other.

string[]

required

Format identifiers present for this category, e.g. ["cyclonedx-json"], ["slsa-provenance-v1"], ["sigstore-bundle-v1"].

boolean

Whether artifacts in this category are present. Defaults to true when the item appears in the array.

boolean

required

Whether the full detail view is available for this release.

object

Optional bibliotheca-produced assessments such as verification labels or policy outcomes. These are derived judgments, not canonical trust facts.

object

required

Current-state revision metadata.

Show revision fields

string

required

Revision identifier for the current state of trust metadata.

string

ISO 8601 timestamp of the most recent trust metadata update.

Summary example

GET /api/v1/volumes/@acme/research-agent-pack/1.4.0/trust/summary

{
  "subject": {
    "purl": "pkg:volume/%40acme/research-agent-pack@1.4.0",
    "integrity": "sha256:a3f2b8c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2"
  },
  "artifacts": [
    {
      "category": "bom",
      "formatsPresent": ["cyclonedx-json"],
      "present": true
    },
    {
      "category": "provenance",
      "formatsPresent": ["slsa-provenance-v1"],
      "present": true
    },
    {
      "category": "signature",
      "formatsPresent": ["sigstore-bundle-v1"],
      "present": true
    }
  ],
  "detailAvailable": true,
  "revision": {
    "revision": "rev_03",
    "updatedAt": "2026-05-10T14:22:00Z"
  }
}

An empty artifacts array means the release exists but no trust artifacts have been attached yet. This is not a failure — it means there is no current trust evidence, not that the release is missing or invalid.

Detail view

The detail view exposes full information for independent retrieval and verification of each trust attachment.

Detail response fields

object

required

The bound release subject (same structure as the summary view).

object[]

required

Array of trust attachment records. May be empty.

Show attachment item fields

string

required

Bibliotheca-local attachment identifier.

string

required

Trust artifact category: bom, provenance, signature, or other.

object

required

Format identity for this attachment.

Show format fields

string

required

Format family identifier: cyclonedx, slsa-provenance, sigstore-bundle, or another family.

string

required

MIME type of the attachment bytes.

string

Predicate URI for in-toto/SLSA-style artifacts, e.g. https://slsa.dev/provenance/v1.

string

Optional profile identifier for a more specific artifact convention.

string

Optional version identifier for the format, e.g. a CycloneDX schema version.

string

required

sha256:<hex> digest of the finalized attachment bytes. Verify downloaded attachment bytes against this value.

integer

Declared byte size of the attachment.

object

required

Where to retrieve the attachment bytes.

Show locator fields

string

URL to retrieve the attachment. Present when the attachment is hosted externally.

any

Embedded attachment representation. Present when the attachment is inlined in the response.

object

required

Lifecycle status of this attachment.

Show status fields

string

required

One of active, revoked, superseded, or invalid.

string

Optional human-readable reason for the current state.

object

Optional objective verification facts for formats the implementation claims to support. Unsupported artifact formats must not be reported as verified.

object

required

Current-state revision metadata (same structure as summary).

Detail example

GET /api/v1/volumes/@acme/research-agent-pack/1.4.0/trust/detail

{
  "subject": {
    "purl": "pkg:volume/%40acme/research-agent-pack@1.4.0",
    "integrity": "sha256:a3f2b8c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2"
  },
  "attachments": [
    {
      "id": "att_01HZ9QRTXK4J2M8SVWBN6P3Y5C",
      "category": "provenance",
      "format": {
        "family": "slsa-provenance",
        "mediaType": "application/vnd.in-toto+json",
        "predicateType": "https://slsa.dev/provenance/v1"
      },
      "artifactDigest": "sha256:c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5",
      "artifactSize": 2048,
      "locator": {
        "url": "https://trust.example.com/attachments/att_01HZ9QRTXK4J2M8SVWBN6P3Y5C"
      },
      "status": {
        "state": "active"
      }
    }
  ],
  "revision": {
    "revision": "rev_03",
    "updatedAt": "2026-05-10T14:22:00Z"
  }
}

Trust artifact format profiles

Category	`format.family`	Key format fields
`bom`	`cyclonedx`	`mediaType = "application/vnd.cyclonedx+json"`; `version` identifies the CycloneDX schema version
`provenance`	`slsa-provenance`	`mediaType = "application/vnd.in-toto+json"`; `predicateType = "https://slsa.dev/provenance/v1"`
`signature`	`sigstore-bundle`	`mediaType` identifies the Sigstore bundle representation; `version` identifies the bundle profile

Attachment status semantics

State	Meaning	Satisfies current-state evidence?
`active`	Current finalized attachment	Yes, when it satisfies the required trust category and any separate verification policy
`revoked`	Attachment has been revoked	No — treat as failure by default
`superseded`	Replaced by a newer attachment	No — does not satisfy current-state evidence
`invalid`	Attachment failed validation	No — treat as failure by default

superseded is a freshness state, not a revocation. A superseded attachment was not necessarily compromised — it was replaced. However, it does not satisfy mandatory current-state trust evidence in the baseline. If only superseded evidence is available for a mandatory trust category, report a stale-trust-evidence-only diagnostic rather than a pass or a security failure.

​Endpoints

​Summary view

​Summary response fields

​Summary example

​Detail view

​Detail response fields

​Detail example

​Trust artifact format profiles

​Attachment status semantics

Endpoints

Summary view

Summary response fields

Summary example

Detail view

Detail response fields

Detail example

Trust artifact format profiles

Attachment status semantics