Recycle Bin API & CLI Cookbook

Copy-paste recipes for every Recycle Bin endpoint. Each section shows a
cURL call plus the equivalent CLI command.

About URLs in examples: all examples use http://localhost:5770.
Replace with your Mockarty address if your instance lives elsewhere. See
Tips & Useful Features.

Related pages: Recycle Bin · CLI User
Guide · API Reference

Authentication

All endpoints require an API token passed via X-API-Key. Tokens are
issued in Settings → API Tokens (or POST /api/v1/auth/tokens) with a role
scoped to a namespace.

export MOCKARTY_URL=http://localhost:5770
export MOCKARTY_API_TOKEN=mk_7_...
export MOCKARTY_NAMESPACE=default

Working from code

The recycle bin is reached over REST and from the CLI. The Go, Python and Java
SDKs deliberately do not wrap it — they cover what a test or a CI job needs, and
emptying a namespace’s bin is an operator action. Use curl (examples below) or
mockarty-cli trash … from a script.

Endpoint map

List soft-deleted items

Filters: type=mock,store, q=substring, cascade=<id>,
closed_by=<email>, from=<RFC3339>, to=<RFC3339>, limit, offset.

cURL

curl -s -H "X-API-Key: $MOCKARTY_API_TOKEN" \
  "$MOCKARTY_URL/api/v1/namespaces/$MOCKARTY_NAMESPACE/trash?type=mock,store&limit=50"

CLI

mockarty-cli trash list --type mock,store --limit 50
mockarty-cli trash list --admin                       # platform-wide

Response:

{
  "items": [
    {
      "id": "mock-abc",
      "name": "users",
      "namespace": "default",
      "entity_type": "mock",
      "closed_at": "2026-04-19T12:00:00Z",
      "closed_by": "alice@example.com",
      "cascade_group_id": "11111111-1111-4111-8111-111111111111",
      "restore_available": true
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

total counts every matching item across resource types. Use offset and
limit to fetch later pages; listing remains available beyond the first 500
items of any resource type.

Summary (badge counts)

cURL

curl -s -H "X-API-Key: $MOCKARTY_API_TOKEN" \
  "$MOCKARTY_URL/api/v1/namespaces/$MOCKARTY_NAMESPACE/trash/summary"

CLI

mockarty-cli trash summary
mockarty-cli trash summary --admin

Retention settings

cURL

# Read
curl -s -H "X-API-Key: $MOCKARTY_API_TOKEN" \
  "$MOCKARTY_URL/api/v1/namespaces/$MOCKARTY_NAMESPACE/trash/settings"

# Upsert
curl -s -X PUT -H "Content-Type: application/json" -H "X-API-Key: $MOCKARTY_API_TOKEN" \
  "$MOCKARTY_URL/api/v1/namespaces/$MOCKARTY_NAMESPACE/trash/settings" \
  -d '{"retention_days": 14, "enabled": true}'

# Global defaults (admin only)
curl -s -X PUT -H "Content-Type: application/json" -H "X-API-Key: $MOCKARTY_API_TOKEN" \
  "$MOCKARTY_URL/api/v1/admin/trash/settings/global" \
  -d '{"retention_days": 30, "enabled": true}'

CLI

mockarty-cli trash settings get
mockarty-cli trash settings set --retention-days 14 --enabled
mockarty-cli trash settings set --global --retention-days 30 --enabled

Restore a single cascade

cURL

curl -s -X POST -H "X-API-Key: $MOCKARTY_API_TOKEN" \
  "$MOCKARTY_URL/api/v1/namespaces/$MOCKARTY_NAMESPACE/trash/restore-cascade/11111111-1111-4111-8111-111111111111"

CLI

mockarty-cli trash restore 11111111-1111-4111-8111-111111111111

Response (camelCase, single-restore shape):

{ "cascadeGroupId": "11111111-1111-4111-8111-111111111111", "restoredCount": 4 }

Restore applies only to items still in that cascade group. If an item was
restored and deleted again, retrying the earlier group leaves the newer
deletion in the Recycle Bin. Use its current entry to restore it.

To restore a deleted issue or issue board, its project must still be active.
If the project is in the Recycle Bin, restore the project first; otherwise the
issue or board restore returns a conflict and leaves it in the bin.

Bulk restore

cURL

curl -s -X POST -H "Content-Type: application/json" -H "X-API-Key: $MOCKARTY_API_TOKEN" \
  "$MOCKARTY_URL/api/v1/namespaces/$MOCKARTY_NAMESPACE/trash/restore" \
  -d '{"cascade_group_ids": ["11111111-1111-4111-8111-111111111111", "22222222-2222-4222-8222-222222222222"], "reason": "rollback"}'

CLI

mockarty-cli trash restore 11111111-1111-4111-8111-111111111111,22222222-2222-4222-8222-222222222222 --reason rollback

Response (207-style envelope):

{
  "restored":  [{ "cascade_group_id": "11111111-1111-4111-8111-111111111111", "entity_type": "mock", "restored_count": 4 }],
  "failed":    [{ "cascade_group_id": "22222222-2222-4222-8222-222222222222", "error": "parent container still deleted" }],
  "not_found": []
}

Each failed group has an error. Expected product refusals have an actionable
message and may include a stable reason. An internal storage failure returns
recycle bin operation failed; check service health before retrying.

Bulk purge (IRREVERSIBLE)

The server requires the exact phrase "I understand this is permanent" in the
confirmation field. The SDKs and the CLI validate it locally so a
misconfigured request never reaches the server.

cURL

curl -s -X POST -H "Content-Type: application/json" -H "X-API-Key: $MOCKARTY_API_TOKEN" \
  "$MOCKARTY_URL/api/v1/namespaces/$MOCKARTY_NAMESPACE/trash/purge" \
  -d '{
    "cascade_group_ids": ["11111111-1111-4111-8111-111111111111"],
    "confirmation": "I understand this is permanent",
    "reason": "GDPR request"
  }'

CLI

# interactive (prompts for the phrase)
mockarty-cli trash purge 11111111-1111-4111-8111-111111111111

# non-interactive
mockarty-cli trash purge 11111111-1111-4111-8111-111111111111 --yes --reason "GDPR request"

Response (207-style envelope):

{
  "purged":    [{ "cascade_group_id": "11111111-1111-4111-8111-111111111111", "entity_type": "mock", "rows_deleted": 7 }],
  "failed":    [],
  "not_found": []
}

For a failed group, internal storage errors use the generic
recycle bin operation failed message. The group remains in the bin.

Empty the whole bin (IRREVERSIBLE)

purge-all permanently deletes every soft-deleted item in scope.
Unlike purge, it takes no id list — the server discovers every
closed cascade group and drains it in bounded batches until the bin is
empty, so it scales to bins with tens of thousands of items. Requires the
same confirmation phrase as purge.

cURL

curl -s -X POST -H "X-API-Key: $MOCKARTY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"confirmation":"I understand this is permanent","reason":"pre-release cleanup"}' \
  "$MOCKARTY_URL/api/v1/namespaces/team-orders/trash/purge-all"

CLI

mockarty-cli trash empty --namespace team-orders --yes --reason "pre-release cleanup"

Response:

{
  "rows_deleted": 18342,
  "groups_purged": 7561,
  "groups_failed": 0,
  "batches_run": 16,
  "truncated": false
}

truncated: true means the bin was so large the safety ceiling was hit
before it fully drained — run the call again to finish.
If discovery or a group operation fails, first_error reports a public reason;
internal storage failures use recycle bin operation failed.

Manual retention tick (admin only)

Synchronously run the retention scheduler across every namespace. Useful
for tests or to confirm the scheduler is healthy.
In a cluster, send this request to the leader. A follower returns HTTP 503
with code: "not_leader"; retry on the leader. Concurrent manual and
scheduled ticks on one node run one at a time.

cURL

curl -s -X POST -H "X-API-Key: $MOCKARTY_API_TOKEN" \
  "$MOCKARTY_URL/api/v1/admin/trash/purge-now"

CLI

mockarty-cli trash purge-now

Response:

{ "status": "ok", "purged_total": 123, "namespaces_scanned": 4 }

If a resource cannot be read or purged, the request returns HTTP 500. Some
rows may already have been removed; check the bin and retry after resolving
the error. A time-limited sweep returns status: "partial" with the number
of rows removed so far.

Error responses

See also

• Recycle Bin — conceptual guide, UI walkthrough,
  RBAC matrix.
• CLI User Guide — full mockarty-cli trash …
  reference.
• SDK Guide — installation and general SDK idioms.