POST
Trigger retention run

Overview

Manually triggers the tenancy-document retention cleanup that normally runs on a daily schedule (03:00 UTC). The endpoint enqueues a one-shot job onto the worker’s BullMQ queue and returns 202 Accepted immediately — the actual cleanup runs out-of-band in the worker process, using the same handler as the scheduled run. Useful when a backlog has built up (the per-run cap is 500 rows) and an operator wants to drain it without waiting for the next nightly window. See Tenancy retention for the full lifecycle.

Authentication

Bearer <accessToken> with scope: 'admin' required (requireAdmin).
Role-gated: SUPER only. Neither MODERATOR nor FINANCE may invoke it — cleanup is destructive (the tenancy document is permanently removed from object storage). Per QUESTIONS.md §8.4.

Path parameters

None.

Query parameters

None.

Request body

None.

Response — 202 Accepted

202 means accepted for processing, not completed. The response carries no cleanup result counts (scanned/deleted/failed) — those are logged by the worker. There is no synchronous “how many rows did it delete?” read in Phase 6.

Error responses

Example error — 403 FORBIDDEN

Side effects

  • A one-shot retention-cleanup job is enqueued on the worker queue.
  • An audit-log row is written (action retention.manual-trigger).
  • When no Redis/queue is wired (dev/test), a no-op enqueuer is used and the call still returns 202.

See also

  • Tenancy retention — the full 30-day lifecycle, the scheduled job, and failure semantics.
  • Approve tenancy — where reviewedAt (the start of the 30-day clock) is set.

curl

Postman

See docs/postman/swappr.postman_collection.json → Admin Retention → Run.