# Data handling and masking

Separate evaluation payloads, stored evidence, Recon uploads, and usage reporting.

Updated: 2026-09-22

Canonical: https://docs.kastra.ai/evidence/data-handling

## Four different data paths

| Path | What to review |
| --- | --- |
| Edge evaluation | Action context, attributes, tool input, source, and supported prompt context sent by the hook |
| Proxy | Request and response content handled on the selected provider path |
| Recon | Supported local history, on-device redaction, and uploaded candidate summaries |
| Usage reporting | Client-reported usage events, separate from proxy metering |

Do not infer “no content leaves the device” from a masked interface. Edge calls the configured Kastra service, proxy content passes through that service, and Recon uses server-side analysis after local redaction. In SaaS this is Kastra-operated infrastructure; an appliance still needs its model and other dependencies assessed separately.

## Masking and sealed originals

Current decision records separate immutable metadata from retained payload content. The selected retention policy determines whether new history keeps no content, masked content, or an encrypted original. Normal reads display the masked representation. Detector coverage is bounded; unrecognized formats can remain outside a detector's findings. Older records retain their original format and custody rules.

Forwarded-content redaction changes what the provider or downstream path receives. Stored-payload masking changes what is written or shown in evidence. These are distinct controls.

## Retention and access

An OWNER can select metadata-only, masked or encrypted-original history for future evaluations, with 1, 7, 30 or 90-day deadlines. New workspaces default to metadata-only; pre-existing workspaces retain legacy behavior until an owner adopts a policy. Changing the policy neither backfills missing content nor extends existing deadlines.

HOLD keeps separate masked review copies with their own finite lifetime. A metadata-only history setting does not remove the context needed for human review. Content states distinguish omitted, never captured, unavailable, expired, erased and legacy-unknown data; absence is not an empty payload.

Reading an encrypted original requires current OWNER membership, fresh MFA and a stated purpose. The access audit must commit before content is returned. History-content erasure and erasure of all closed-review copies are separate actions. These operations do not rewrite immutable decision hashes.

Expiry is enforced on reads, while a bounded worker clears expired stored content. Manual erasure records a dated marker and independent custody before database redaction. It does not immediately remove ciphertext from every retained backup or rotate shared keys.

## Restore and erasure custody

Self-hosted operators must preserve the latest erasure custody independently of installation/database backups and supply it during recovery. Missing or invalid required custody prevents activation. Restoring an old database together with an old custody copy cannot establish that later erasures remain effective. Never-bound review-only installations have weaker database-only erasure: an older backup can restore review copies until their original deadlines.

Agree separately on backup retention and disposal, usage telemetry and exported-report retention. A plan label alone does not prove a deletion schedule. See [self-hosted recovery](https://docs.kastra.ai/reference/self-hosted#recovery-execution-and-upgrades).

## Rollout checklist

Review data collection with your organization, test synthetic sensitive examples, inspect masked decisions and exports, and confirm who can reveal or access protected details. Route privacy requests through the [contact page](https://kastra.ai/contact).

Use the [data protection review](https://docs.kastra.ai/security/data-protection) to prepare a data map, retention requirements, and deployment questions. The [Kastra Trust Center](https://trust.oneleet.com/kastra) is the starting point for GDPR documentation and vendor privacy review.

## Retention API

Authenticated customer management calls use the selected workspace through `X-Organization-ID`:

| Request | Purpose |
| --- | --- |
| `GET /api/v1/content-retention` | Read the current mode, days and revision |
| `PUT /api/v1/content-retention` | OWNER changes future retention using `mode`, `days` and the current `revision`; a stale revision returns 409 |
| `GET /api/v1/decisions/{id}/content` | Read content availability and deadlines without payloads |
| `GET /api/v1/decisions/{id}/content/{kind}?purpose=history` | Authorized masked history read |

Modes are `metadata`, `masked` and `original`; content kinds are `prompt`, `tool_input` and `response`. These are management routes, not API-key evaluation endpoints. Use the console's separately authorized reveal and erasure actions for protected content.