Retention API
The routes behind Settings → Data retention: the effective policy, previews, on-demand purges (Clean now), destruction records and legal holds. They are tenant-scoped dashboard routes under /api/retention: they authenticate with a browser session (not an API token) and act on the signed-in workspace. Concepts, data classes and the screen are in Data retention.
Access
The routes belong to the audit permission service. Reads and the two preview calls need audit.read; saving or cancelling a policy, starting or cancelling a purge, and placing or releasing a hold need audit.admin. The engine runs in every edition; the Data retention screen is part of the enterprise data-retention module (see Licence packages).
| Method | Path | Purpose |
|---|---|---|
GET | /api/retention | Effective classes with source, caps and pending caps, targets, mechanisms, bounded presets, engine state, last sweep, current purge |
PUT | /api/retention/policy | Save { preset, classes, projects } within the current licensed and operator bounds |
DELETE | /api/retention/policy/pending | Cancel a pending policy shortening |
POST | /api/retention/policy/preview | Rows a draft policy would delete or redact now |
POST | /api/retention/purge/preview | Rows a purge would touch |
POST | /api/retention/purge | Start a purge |
GET | /api/retention/purge | Status of the current or last purge |
DELETE | /api/retention/purge | Cancel the running purge after its current batch |
GET | /api/retention/runs | Destruction records (audit rows of service retention) |
GET | /api/retention/holds | The workspace's legal holds, the operator's included |
POST | /api/retention/holds | Place a legal hold |
DELETE | /api/retention/holds/:id | Release a legal hold |
Purge
curl -X POST "$CONSOLE_URL/api/retention/purge" \
-H "Content-Type: application/json" -H "Cookie: $SESSION_COOKIE" \
-d '{ "mode": "olderThan", "days": 90, "classes": ["telemetry", "trace"], "confirm": "my-workspace" }'| Field | Description |
|---|---|
mode | "policy" (what the next sweep would do) or "olderThan" (needs days). |
days | A whole number from 0 to 3650. 0 removes everything up to now in the chosen classes. |
classes | Optional non-empty list of retention classes; absent means every class a tenant may purge. |
projectId | Optional project id. Collections without a project are skipped when it is set. |
confirm | The workspace slug. |
The answer is 202, or 409 while another purge runs. The audit trail is append-only: classes containing audit answers 400, for the purge and for its preview. Held data is skipped (see below).
Legal holds
A hold keeps data past its retention until it is released. Held data is skipped by every sweep, purge and preview. At most 100 holds can be active at once.
Place a hold: POST /api/retention/holds, answers 201 with { "hold": { … } }.
{
"name": "Dispute with a customer",
"scope": { "kind": "project", "projectId": "proj_123" },
"classes": ["content", "telemetry"],
"ref": "CASE-1042",
"reason": "Preserve the records until the case closes"
}| Field | Description |
|---|---|
name | Required, at most 120 characters. Shown in the destruction records. |
scope | { "kind": "tenant" } for the whole workspace, or { "kind": "project", "projectId": "…" } for one project of the workspace. |
classes | "all" (default) or a non-empty list of retention classes. |
reason | Optional, at most 2000 characters. |
ref | Optional case or ticket reference, at most 200 characters. |
Release a hold: DELETE /api/retention/holds/:id returns the released hold. A hold placed by the platform operator cannot be released here (403).
| Status | Meaning |
|---|---|
400 | Invalid body (a missing name, a bad scope or classes, a projectId that is not a project of this workspace). |
403 | The operator placed this hold; only the operator can release it. |
404 | Unknown hold id. |
409 | Too many active holds, the hold is already released, or its release is still in progress (try again in a minute). |
Placing and releasing a hold write audit rows that are kept with the destruction records.

