> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentvolumes.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Trust metadata: summary and detail views

> Discover trust attachments — BOMs, provenance attestations, and signatures — for a published volume release via summary and detail endpoints.

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

```http theme={null}
# 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

<ResponseField name="subject" type="object" required>
  The release subject this summary is bound to.

  <Expandable title="subject fields">
    <ResponseField name="subject.purl" type="string" required>
      Canonical `pkg:volume/...@version` logical identity of the release.
    </ResponseField>

    <ResponseField name="subject.integrity" type="string" required>
      `sha256:<hex>` immutable content identity of the release.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="artifacts" type="object[]" required>
  Array of trust artifact category summaries. May be empty when the release exists but no trust artifacts have been attached yet.

  <Expandable title="artifact item fields">
    <ResponseField name="category" type="string" required>
      Trust artifact category: `bom`, `provenance`, `signature`, or `other`.
    </ResponseField>

    <ResponseField name="formatsPresent" type="string[]" required>
      Format identifiers present for this category, e.g. `["cyclonedx-json"]`, `["slsa-provenance-v1"]`, `["sigstore-bundle-v1"]`.
    </ResponseField>

    <ResponseField name="present" type="boolean">
      Whether artifacts in this category are present. Defaults to `true` when the item appears in the array.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="detailAvailable" type="boolean" required>
  Whether the full detail view is available for this release.
</ResponseField>

<ResponseField name="judgments" type="object">
  Optional bibliotheca-produced assessments such as verification labels or policy outcomes. These
  are derived judgments, not canonical trust facts.
</ResponseField>

<ResponseField name="revision" type="object" required>
  Current-state revision metadata.

  <Expandable title="revision fields">
    <ResponseField name="revision.revision" type="string" required>
      Revision identifier for the current state of trust metadata.
    </ResponseField>

    <ResponseField name="revision.updatedAt" type="string">
      ISO 8601 timestamp of the most recent trust metadata update.
    </ResponseField>
  </Expandable>
</ResponseField>

### Summary example

```http theme={null}
GET /api/v1/volumes/@acme/research-agent-pack/1.4.0/trust/summary
```

```json theme={null}
{
  "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"
  }
}
```

<Note>
  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.
</Note>

## Detail view

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

### Detail response fields

<ResponseField name="subject" type="object" required>
  The bound release subject (same structure as the summary view).
</ResponseField>

<ResponseField name="attachments" type="object[]" required>
  Array of trust attachment records. May be empty.

  <Expandable title="attachment item fields">
    <ResponseField name="id" type="string" required>
      Bibliotheca-local attachment identifier.
    </ResponseField>

    <ResponseField name="category" type="string" required>
      Trust artifact category: `bom`, `provenance`, `signature`, or `other`.
    </ResponseField>

    <ResponseField name="format" type="object" required>
      Format identity for this attachment.

      <Expandable title="format fields">
        <ResponseField name="format.family" type="string" required>
          Format family identifier: `cyclonedx`, `slsa-provenance`, `sigstore-bundle`, or another family.
        </ResponseField>

        <ResponseField name="format.mediaType" type="string" required>
          MIME type of the attachment bytes.
        </ResponseField>

        <ResponseField name="format.predicateType" type="string">
          Predicate URI for in-toto/SLSA-style artifacts, e.g. `https://slsa.dev/provenance/v1`.
        </ResponseField>

        <ResponseField name="format.profile" type="string">
          Optional profile identifier for a more specific artifact convention.
        </ResponseField>

        <ResponseField name="format.version" type="string">
          Optional version identifier for the format, e.g. a CycloneDX schema version.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="artifactDigest" type="string" required>
      `sha256:<hex>` digest of the finalized attachment bytes. Verify downloaded attachment bytes against this value.
    </ResponseField>

    <ResponseField name="artifactSize" type="integer">
      Declared byte size of the attachment.
    </ResponseField>

    <ResponseField name="locator" type="object" required>
      Where to retrieve the attachment bytes.

      <Expandable title="locator fields">
        <ResponseField name="locator.url" type="string">
          URL to retrieve the attachment. Present when the attachment is hosted externally.
        </ResponseField>

        <ResponseField name="locator.embedded" type="any">
          Embedded attachment representation. Present when the attachment is inlined in the response.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="status" type="object" required>
      Lifecycle status of this attachment.

      <Expandable title="status fields">
        <ResponseField name="status.state" type="string" required>
          One of `active`, `revoked`, `superseded`, or `invalid`.
        </ResponseField>

        <ResponseField name="status.reason" type="string">
          Optional human-readable reason for the current state.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="verification" type="object">
      Optional objective verification facts for formats the implementation claims to support. Unsupported artifact formats
      must not be reported as verified.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="revision" type="object" required>
  Current-state revision metadata (same structure as summary).
</ResponseField>

### Detail example

```http theme={null}
GET /api/v1/volumes/@acme/research-agent-pack/1.4.0/trust/detail
```

```json theme={null}
{
  "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                                                        |

<Warning>
  `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.
</Warning>