---
title: "Change this account's retention settings"
method: PATCH
path: "/api/v1/retention"
tags: ["Retention"]
---

# Change this account's retention settings

`PATCH /api/v1/retention`

## Request

- Base URL: `https://tamperlens.com` (the document declares no server; this is the origin it was published from)
- URL: `https://tamperlens.com/api/v1/retention`
- Auth: none declared

JSON body, every field optional: `mode` (`off` | `derived`), `days` (30 | 90 | 365), `bytesDays` (7 | 30 | 90 | null) and `keys`, a list of `{id, retention}` with `retention` `inherit` | `none`.

Turning `mode` off stops keeping new inspections; what is already kept stays until it expires or is deleted. Shortening `days` applies to what is already kept as well, and lengthening it never extends a record already written. The change is all or nothing: an unknown key id is 404 and nothing is applied.

`bytesDays` keeps the uploaded file itself, encrypted with a key of its own, for that many days (never longer than its derived record), so it can be downloaded or inspected again with a newer engine. Off by default. Turning it on when the server cannot keep files answers 409 `retention_bytes_unavailable`, and on an account whose email is not verified 403 `email_unverified`; both change nothing. Setting it to `null` turns it off **and deletes every file this account kept**; the derived records stay. Shortening it applies to files already kept.

**Dashboard session only.** An API key gets 403 `session_required`.

## Response `200`

Default Response

- object
  - `mode` 'off' | 'derived'
  - `days` 30 | 90 | 365
  - `bytesDays` 7 | 30 | 90 | null, nullable
  - `bytesAvailable` boolean
  - `keys` object[]
    - `id` string
    - `label` string, nullable
    - `retention` 'inherit' | 'none'

## Other responses

- `400`: Default Response
- `401`: Default Response
- `403`: Default Response
- `404`: Default Response
- `409`: Default Response
- `415`: Default Response
- `429`: Default Response

---

[API](https://skmtc.dev/tamperlens/apis/tamperlens-api.md) · [All operations](https://skmtc.dev/tamperlens/apis/tamperlens-api/llms.txt) · [OpenAPI document](https://skmtc.dev/tamperlens/apis/tamperlens-api/revisions/e1b7ae64347b?raw)