Decision Provenance

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

Parameter	Type	Description
`id`	string	Decision 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

Header	Description
`X-Provenance-Signature`	The 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

Code	Reason
`400`	Missing decision id.
`403`	Caller is not admin.
`404`	No 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.

Overview

Decisioning

Studio

Data

Algorithms & Models

Content & Metrics

Orchestration

Customers & Traces

Events & Attribution

Analytics

AI

Testing & Simulation

Export & Import

Admin

Integrations

Decision Provenance

GET /api/v1/decisions//provenance

Path parameters

Response `200`

Response headers

Errors

​GET /api/v1/decisions//provenance

​Path parameters

​Response 200

​Response headers

​Errors

​Related — decision narrative

GET /api/v1/decisions//provenance

Path parameters

Response `200`

Response headers

Errors

Related — decision narrative