Recycle Bin (Soft-Delete)

Every time you delete a mock, API test collection, recorder session, contract, fuzz config, test plan, schedule,
webhook or webhook subscription, notification channel subscription or binding, CI trigger or CI job run
configuration, security scan template, saved test-case folder view, or step comment in Mockarty, the item is
not removed immediately — it is moved
to the per-namespace Recycle Bin with a retention window. Inside the
window you can restore the item (together with every dependent row that was
soft-deleted in the same operation). After the window expires, Mockarty
purges the rows automatically; administrators can also purge on demand.

This page covers:

• How soft-delete works (what you see, what is actually stored)
• Retention settings — namespace overrides and global defaults
• Restoring a single cascade group or a batch
• Manual purge (irreversible) and the confirmation phrase
• Role-based access (who can view, restore, purge)

Looking for the CLI / SDK / API call shapes? See
Recycle Bin API & CLI Cookbook.

How soft-delete works

When you delete an entity from the UI, the CLI, or through the API:

1. Mockarty marks the row with closed_at / closed_by and the optional
   closed_reason — the row stays in the database.
2. Dependent rows (for example: mocks belonging to a chain, schedules and
   webhooks belonging to a test plan) are soft-deleted in the same
   transaction and share a cascade_group_id. Restoring the group
   brings back every member at once.
3. The item disappears from normal list views immediately. It only
   reappears in the Recycle Bin.

A few records are closed as part of normal work rather than deleted by you, so they never
appear in the bin — but they do not pile up either: Mockarty removes them on the same retention
schedule. These are remote agents that deregistered on shutdown, notification policies you reset
to the inherited default, and test-case workflows (with their states) replaced by applying another
workflow preset.

Accessing the Recycle Bin

Web UI — namespace view: open the sidebar and click Recycle Bin
(or navigate directly to /ui/trash). The page is filtered to the
namespace selected in the header namespace switcher.

Web UI — global view (admin / support): platform admins and support
users additionally see a Recycle Bin (All) entry in the sidebar
(/ui/admin/trash). The same page is used with a scope switch at the
top so you can jump between the namespace-scoped view and the global one.

CLI:

mockarty-cli trash list
mockarty-cli trash summary

Platform-wide CLI view: add --admin to list every namespace.
Support users can view every namespace but cannot purge.

UI walkthrough

Once the page loads you see three zones:

1. Header strip — a running total of items in the bin, a chip per
   entity type (click a chip to filter the table), a Refresh button and
   a Retention Settings button.
2. Filter bar — search by name/ID, type filter, from/to date range,
   and a deleted-by login or UUID filter.
3. Table — each row shows the item name, type badge, namespace, who
   deleted it and when, and the reason (if any). The per-row Restore
   and Purge buttons open a confirmation dialog scoped to just that
   row. Select multiple rows with the checkboxes and a bulk action bar
   appears at the top with Restore selected and Purge selected.

The table collapses into a card list on narrow viewports so the page
remains usable from a tablet or phone.
If a filter finds no items, the page says No matching items; clear or
change the filters to see the rest of the bin.

Restoring an item

Click Restore on the row (or select multiple rows and click
Restore selected). A dialog confirms the operation and offers an
optional free-form Reason field that is captured in the audit log.
Restore is idempotent — running it twice on the same cascade group has
no extra effect.

Permanently deleting (purge)

Purge is irreversible. When you click Purge (or Purge selected),
Mockarty shows a red confirmation dialog with the exact number of
cascade groups about to be deleted and requires you to type the
confirmation phrase exactly:

I understand this is permanent

The Permanently delete button stays disabled until the phrase is
entered exactly; the backend rejects anything else with HTTP 400. An
optional Reason field is captured in the audit log — use this for
GDPR requests or incident tickets.

Retention settings

Click Retention Settings in the header. The dialog shows:

• Recycle bin enabled toggle — turn the bin off to have deletions
  skip the retention window entirely (not recommended for regulated
  environments).
• Retention period (days) — a 1–365 day slider with a paired number
  input. Namespace owners can override the global default; platform
  admins set the default from the All namespaces scope.
• Retention Scheduler → Run Now (admin scope only) — triggers the
  automatic retention sweep immediately, useful for ops verification or
  after reducing the retention window. Only the cluster leader runs the
  scheduler tick; followers return 503 with a hint and no work.

Retention settings

Two levels:

• Global defaults — platform-wide values applied when a namespace has
  no override. Default: 7 days, enabled. Configurable in Admin →
  Retention Settings, or via mockarty-cli trash settings set --global --retention-days N --enabled.
• Per-namespace overrides — set from Settings → Recycle Bin →
  Retention (requires namespace owner) or mockarty-cli trash settings set --retention-days N --enabled.

Constraints:

• retention_days must be 1..365.
• Setting enabled=false disables purging entirely for the scope — rows
  accumulate forever. Only recommended for forensic namespaces.

When a namespace inherits the global defaults, GET /api/v1/namespaces/:ns/trash/settings returns
"inherited": true and the global values. As soon as an override is
saved, inherited becomes false.

The same retention also applies to deleted items that never appear in the
bin and cannot be restored — for example comments, saved filters and views,
dashboards and widgets, UI tests and their baselines, sprints and worklogs.
They disappear from the product the moment you delete them and are removed
permanently once the retention period has passed (or never, while retention
is disabled for the namespace).

Restoring

Every restore is idempotent — calling it twice yields
restored_count=0 on the second attempt, never an error.

Restoring a single cascade group (UI button, CLI, or SDK):

mockarty-cli trash restore <cascade-id>

Bulk restore — pass several ids (UI multi-select, CLI CSV, SDK
cascade_group_ids):

mockarty-cli trash restore cg-abc,cg-def --reason "rollback of wrong cleanup"

Bulk responses follow the 207-style envelope:

{
  "restored":  [{ "cascade_group_id": "cg-abc", "entity_type": "mock", "restored_count": 4 }],
  "failed":    [{ "cascade_group_id": "cg-def", "error": "parent container still deleted" }],
  "not_found": ["cg-xyz"]
}

Common restore failures

• parent container still deleted — the entity depends on another row
  that is also in the Recycle Bin. Restore the parent first (the UI
  suggests this automatically).
• retention expired — the restore window closed; the row has already
  been hard-deleted.
• conflict — a live row with the same business key (for example, the
  same mock id) exists. Rename or delete it, then retry.

Purging (IRREVERSIBLE)

Purge permanently removes rows from the database — there is no
recovery. Mockarty runs the retention scheduler periodically to purge
expired rows automatically; you only need the manual command for:

• Proactively freeing space before the retention window expires
• Responding to a data-subject erasure request (GDPR-style)
• Unblocking a namespace owner who hit the per-namespace row ceiling

Confirmation phrase

Every manual purge requires the exact phrase I understand this is permanent (case-sensitive, no trailing whitespace). The UI shows it
in the confirm dialog; the CLI and SDKs check it before sending the
request. If the phrase is missing or wrong the request is refused
locally — no API call is made.

CLI

Interactive:

mockarty-cli trash purge <cascade-id>
# CLI prompts for the phrase, exits non-zero if you type anything else

Non-interactive (CI / scripts) — add --yes:

mockarty-cli trash purge cg-abc,cg-def --yes --reason "GDPR request #4421"

Empty the whole bin

To permanently delete every item in the bin in one step — without
listing ids first — use trash empty. The server discovers every
soft-deleted item in scope and drains it in batches until the bin is
empty, so this works even for bins holding tens of thousands of items
(a single purge call is bounded per request).

# Current namespace
mockarty-cli trash empty --namespace team-orders

# Platform-wide (platform admin only)
mockarty-cli trash empty --admin --yes --reason "pre-release cleanup"

The same action is available in the UI as the Empty bin button. If
you set a search, type, date, or deleted-by filter first, the button
deletes only matching items. The confirmation shows a minimum visible
count because more matches may be beyond the current list page; the UI
continues in bounded batches until no matching items remain and reports
any items it could not delete. Without filters, the UI refreshes the count
before opening the confirmation. If you switch namespaces while a confirmed
operation is still running, its remaining batches stay in the namespace you
confirmed.

Manual retention tick (admin only)

To force the retention scheduler to run immediately across every
namespace:

mockarty-cli trash purge-now

This returns the number of rows purged and namespaces scanned.
If one resource fails, the call reports an error; earlier deletions may have
succeeded, so inspect the bin before retrying.

Role-based access

Platform support and platform admin both purge across namespaces — use
the role you’ve been granted; the audit log records who actually pressed
“purge”. Namespace owner can purge inside their own namespace.

Audit trail

Every Recycle Bin operation produces an audit log entry with the actor,
target entity, cascade group id, reason (when supplied), and outcome.
Retrieve the history from Admin → Audit Log, filter by action
trash_restore / trash_purge / trash_settings_update.

Related pages

• Recycle Bin API & CLI Cookbook — request/response
  examples for every endpoint, in Go / Python / Java / CLI / curl.
• Administration Guide — global retention defaults and
  platform-wide Recycle Bin.
• CLI User Guide — mockarty-cli trash … full
  reference.