Skip to content

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).

MethodPathPurpose
GET/api/retentionEffective classes with source, caps and pending caps, targets, mechanisms, bounded presets, engine state, last sweep, current purge
PUT/api/retention/policySave { preset, classes, projects } within the current licensed and operator bounds
DELETE/api/retention/policy/pendingCancel a pending policy shortening
POST/api/retention/policy/previewRows a draft policy would delete or redact now
POST/api/retention/purge/previewRows a purge would touch
POST/api/retention/purgeStart a purge
GET/api/retention/purgeStatus of the current or last purge
DELETE/api/retention/purgeCancel the running purge after its current batch
GET/api/retention/runsDestruction records (audit rows of service retention)
GET/api/retention/holdsThe workspace's legal holds, the operator's included
POST/api/retention/holdsPlace a legal hold
DELETE/api/retention/holds/:idRelease a legal hold

Purge ​

bash
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" }'
FieldDescription
mode"policy" (what the next sweep would do) or "olderThan" (needs days).
daysA whole number from 0 to 3650. 0 removes everything up to now in the chosen classes.
classesOptional non-empty list of retention classes; absent means every class a tenant may purge.
projectIdOptional project id. Collections without a project are skipped when it is set.
confirmThe 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).

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": { … } }.

json
{
  "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"
}
FieldDescription
nameRequired, 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.
reasonOptional, at most 2000 characters.
refOptional 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).

StatusMeaning
400Invalid body (a missing name, a bad scope or classes, a projectId that is not a project of this workspace).
403The operator placed this hold; only the operator can release it.
404Unknown hold id.
409Too 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.

Studio · Pulse · Console · Agent SDK and more — the Cognipeer documentation hub