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

# Decision Provenance

> Fetch a signed, tamper-evident provenance bundle for a single decision — trace, model snapshots, effective rules, audit chain, build identity, and fairness slice.

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/{id}/provenance

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

### Path parameters

| Parameter | Type   | Description        |
| --------- | ------ | ------------------ |
| `id`      | string | Decision trace id. |

### Response `200`

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

## Related — decision narrative

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](./decision-traces#post-apiv1decisionsidnarrative) page.