Skip to main content
The provenance endpoint assembles a complete, tamper-evident record of how one decision was made: the (PII-redacted) decision trace, hashed model snapshots, the effective-rules cascade per selected offer, the hash-chained audit log, the build identity (git + container image + SBOM, optionally with a SLSA attestation), and the latest fairness slice. The whole bundle is canonicalized and hashed, and — when COSIGN_KEY is configured — signed with cosign.

​
GET /api/v1/decisions//provenance

Return the provenance bundle for a decision trace. Admin only.

​
Path parameters

ParameterTypeDescription
idstringDecision trace id.

​
Response 200

{
  "schemaVersion": "kaireon.provenance.v1",
  "generatedAt": "2026-07-03T12:00:00.000Z",
  "decisionTrace": {
    "id": "dt_...",
    "requestId": "req_...",
    "candidateCount": 12,
    "finalCount": 3,
    "scoringResults": [],
    "selectedOffers": [],
    "inputsHash": "…",
    "policyVersionHash": "…",
    "degradedScoring": false
  },
  "modelSnapshots": [
    { "modelId": "mdl_...", "modelType": "gradient_boosted", "modelStateHashSha256": "…" }
  ],
  "effectiveRulesByOffer": {
    "off_...": { "…": "deduped effective-rules cascade with explainCascade" }
  },
  "auditLog": [
    {
      "id": "al_...",
      "action": "scoring_result",
      "entityType": "decision_trace",
      "entityId": "dt_...",
      "timestamp": "2026-07-03T11:59:59.000Z",
      "prevHash": "…",
      "integrityHash": "…"
    }
  ],
  "buildIdentity": {
    "gitSha": "…",
    "gitRepo": "…",
    "imageName": "…",
    "imageDigest": "…",
    "sbomDigestSha256": "…",
    "slsaAttestation": null
  },
  "fairnessSlice": null
}
Notes on the bundle:
  • decisionTrace is PII-redacted before it leaves the server.
  • modelSnapshots carry a SHA-256 hash of each referenced model’s state, not the state itself.
  • auditLog rows are hash-chained (prevHash → integrityHash) so tampering is detectable.
  • buildIdentity fields come from deployment env vars (GIT_SHA, IMAGE_DIGEST, SBOM_DIGEST_SHA256, …); slsaAttestation is populated only when the git + image identity is fully present.
  • fairnessSlice is the latest fairness_evaluate / fairness_report audit row for the tenant, or null.

​
Response headers

HeaderDescription
X-Provenance-SignatureThe cosign signature over the canonicalized bundle, or unsigned when COSIGN_KEY is not configured (or the cosign binary is missing). Consumers use this to tell a key-bound bundle from a dev bundle.
The bundle is canonicalized (stable key order) and SHA-256 hashed before signing, so the digest is reproducible across pods.

​
Errors

CodeReason
400Missing decision id.
403Caller is not admin.
404No decision trace with that id in the tenant.
A human-readable, LLM-generated explanation for the same decision is available at POST /api/v1/decisions/{id}/narrative (customer / agent / regulator modes). It is documented on the Decision Traces page.