Evidence snapshots API

Purpose

• freeze one explicit set of package artifacts and OCI subjects
• capture compact SBOM, vulnerability, license, suppression, policy-decision, and provenance summary values
• give automation a stable technical review record without exporting a compliance package

Request

Send name and at least one subject. Each subject must include repository and exactly one selector.

Package artifact subject

• artifact_id: existing package artifact ID

OCI subject

• oci_digest: existing visible OCI manifest or index digest

For least privilege, snapshot creation requires current package artifact read access, composition read access for SBOM data, findings read access, license-policy read access, pull-gate inspect access, and token scope for every referenced repository family. Existing findings-suppress or license-policy configure permissions also satisfy the corresponding visibility checks, but they are not needed for read-only evidence collection.

capture_options defaults to omitting privileged suppression details. Set include_suppression_actor_rationale to include suppression created_by and justification, and set include_suppression_scope_details to include scope_key and scope_label. Either option requires findings:suppress on every selected repository. Included values are frozen into the snapshot and become visible to anyone who can later read or download that snapshot.

{
  "name": "Release 1.0 review",
  "description": "Technical review inputs for release 1.0.",
  "capture_options": {
    "include_suppression_actor_rationale": false,
    "include_suppression_scope_details": false
  },
  "subjects": [
    {
      "repository": "libs-release",
      "artifact_id": "4fd75091-2d3a-48b7-9e35-85a5edfa1d92"
    },
    {
      "repository": "containers",
      "oci_digest": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
    }
  ]
}

Create Responses

Common status codes:

• 201 Created: the snapshot was created and returned with captured subjects.
• 400 Bad Request: the subject set is empty, duplicated, too large, or uses invalid selectors.
• 401 Unauthorized: no valid programmatic credentials were provided.
• 403 Forbidden: the caller can access the repository but lacks one required evidence summary permission.
• 404 Not Found: a repository or selected subject cannot be resolved or is hidden by repository read access or token scope.

List Snapshots

List returns only snapshots where the caller can still access every captured repository. Partially inaccessible snapshots are omitted instead of exposing their existence. Snapshots can remain visible when a captured artifact or OCI subject is no longer live, as long as the captured repository is still accessible.

Read Snapshot

Use the snapshot ID from create or list responses. The response contains the captured subjects and summary values frozen at creation time. Those frozen values remain readable even if the original artifact, tag, manifest, or index is later deleted, hidden, untagged, or otherwise unavailable. Live detail links are available only while the source subject can still be resolved.

Export Snapshot

Use export when you need a portable copy of the snapshot bundle. The ZIP contains manifest.json with SHA-256 hashes, evidence.json with the captured snapshot payload, summary.md with a concise Markdown summary, and per-subject subjects/<subject-id>/vulnerabilities.json and subjects/<subject-id>/suppressions.json detail files. Craftifact uses the frozen snapshot values and does not recompute live SBOM, vulnerability, license, suppression, policy-decision, or provenance state while exporting. Exports stay based on captured values even when the source subject is no longer available. If privileged suppression fields were included at capture time, the exported detail files include those frozen values even for later viewers who only have read access to the snapshot.

Examples

curl \
  -X POST \
  -H "Authorization: Bearer $CRAFTIFACT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Release 1.0 review","subjects":[{"repository":"libs-release","artifact_id":"ARTIFACT_ID"},{"repository":"containers","oci_digest":"sha256:DIGEST"}]}' \
  "https://packages.example.com/api/evidence/snapshots/"

curl \
  -H "Authorization: Bearer $CRAFTIFACT_TOKEN" \
  "https://packages.example.com/api/evidence/snapshots/"

curl \
  -H "Authorization: Bearer $CRAFTIFACT_TOKEN" \
  "https://packages.example.com/api/evidence/snapshots/SNAPSHOT_ID/"

curl \
  -H "Authorization: Bearer $CRAFTIFACT_TOKEN" \
  -o evidence-snapshot.zip \
  "https://packages.example.com/api/evidence/snapshots/SNAPSHOT_ID/export/"

Boundaries

An evidence snapshot is a technical review record. It does not assert legal compliance, conformity assessment status, CE marking, statutory reporting status, or final release acceptance.

Related Pages

• To resolve package artifact IDs first, see Artifact lookup API.
• To attach SBOM input first, see SBOM upload API.
• To read live vulnerability details for one subject, see SBOM vulnerability report API.