Skip to content
wabe Disk

Reclaim obsolete file data

Start a self-hosted server and use its connection variables for these requests.

Endpoint

Section titled “Endpoint”
POST /v1/disks/{disk}/gc

Parameters

Section titled “Parameters”
Query parameter Behavior
limit Optional integer from 1 to 4096. Process at most this many filesystem garbage records in one step. Without it, collect filesystem garbage to completion and reclaim obsolete Redis data.

Request

Section titled “Request”

Run a bounded collection step on an open disk:

Terminal window
curl --fail-with-body -X POST "$WABE_DISK_URL/v1/disks/demo/gc?limit=256" \
  -H "Authorization: Bearer $WABE_DISK_API_KEY"

Run collection to completion:

Terminal window
curl --fail-with-body -X POST "$WABE_DISK_URL/v1/disks/demo/gc" \
  -H "Authorization: Bearer $WABE_DISK_API_KEY"

Response

Section titled “Response”
200 example on a clean disk
{"reclaimed_bytes":0,"removed_blobs":0,"removed_nodes":0,"removed_versions":0,"examined_entries":0,"batches":0,"removed_index_entries":0}

reclaimed_bytes counts unique filesystem blob payload bytes tombstoned and, during full collection, removed Redis collection payload bytes. Shared blobs are counted once. The remaining counters describe filesystem collection: removed_index_entries counts removed history-index records and current-version records from deleted branches or reset staging; examined_entries includes inspected candidates and retired current-version records; batches counts batches that changed reference metadata. A record can release several child references, so limit does not cap database writes or bytes.

Redis cleanup runs during collection without limit, eviction and graceful close. Bounded filesystem steps leave Redis data untouched.

GC preserves current branches, retained commits and bases, labels, configured recent history and retained notification content. User KV remains untouched. Unlimited history is the default, so replacing a file alone does not make its old content reclaimable.

An accepted collection continues if its requester disconnects. Each batch waits for active file-content readers and writers and pauses new file operations while applying deletions. Operations can run between batches. Continuous content activity can delay GC. The disk remains open.

GC flushes deletions before returning. Backing-store maintenance reclaims physical objects later; the response does not promise immediate object deletion or a proportional storage-bill reduction.

Eviction and graceful close collect eligible garbage to completion. Call this endpoint to reclaim data without unloading the disk; use limit to control each step. The standalone server has no periodic GC timer.

Errors

Section titled “Errors”

400 for an invalid disk name or limit, 401 for authentication, and 500 for storage failure.