Skip to content

Start a storage sweep

POST
/admin/storage/sweeps

Queues a storage-integrity sweep. It doesn’t change stored file bytes.

You need system.admin for the whole install; a permission held only for a team doesn’t count, and system.storage.read alone can’t start a sweep. Send a JSON body with kind set to orphan_scan or checksum_verify. A body that can’t be decoded gets a plain-text 400, even when you aren’t signed in. Otherwise signed-out callers get 401 and callers without the permission 403. A missing or unknown kind gets a JSON 400, and so does every other start error, database and queueing errors included.

orphan_scan lists recognized object-and-variant paths on the currently configured backend and checks whether each has a storage_variants row. It doesn’t check every kind of database reference, so an orphan finding isn’t permission to delete the bytes. Unrecognized paths are skipped.

checksum_verify walks the registered variant rows and reads their bytes from that backend. For original, it compares the SHA-256 with the object’s hash. A derivative’s parent hash isn’t its checksum, so derivatives only get a presence check and, when a positive size is recorded, a length check; a same-size change to a derivative can pass. Missing bytes, checksum mismatches and size mismatches are recorded, and for an original a checksum mismatch takes precedence over a size mismatch. Checksum verification can be I/O-heavy, so run it in a maintenance window.

Known limitation: a checksum batch currently fails when it saves its checkpoint if its last variant key isn’t empty, which is true of normal keys. The batch can record findings without updating the counters or finishing the run, so a run left running isn’t proof that work is still going.

The worker handles up to 500 registered pairs per checksum batch, or asks for up to 500 backend listing entries per orphan batch, and queues the next batch once it has saved progress. The scan sees changes as it goes rather than one frozen snapshot. Findings are advisory: recheck them before any repair or deletion. These endpoints don’t repair files, delete bytes or resolve findings.

Creating the run and queueing its first job are separate writes. A queueing error can leave a run row behind even though you get 400, and repeating the request creates another run; the API has no guard against duplicate or overlapping runs.

A 202 means the first job was queued, not that the sweep finished. The handler then returns the newest run of that kind, which can belong to a concurrent request. If that lookup fails or finds nothing, you get the new run’s ID with running status, zero counters and no timestamps. Don’t assume a successful response always identifies your own run.

The kind of storage-integrity work to queue. Starting a sweep creates run and job records but doesn’t repair or delete stored bytes.

object
kind
required

orphan_scan checks recognized backend paths for a missing variant-registry row. checksum_verify checks registered pairs on the configured backend: originals by hash, derivatives by presence and, when a positive size is recorded, by length. The operation page describes the current checksum checkpoint limitation.

string
Allowed values: orphan_scan checksum_verify

The first job was queued. The row is the newest run of that kind, or a minimal fallback for the new run, not a completion result.

Stored progress of one storage-integrity sweep. Status and counters need not reflect current worker activity or the number of finding rows already written.

object
id
required

UUID of the sweep run, not a job ID. A trigger response may return another recent run of the requested kind.

string format: uuid
kind
required

Recorded sweep kind: orphan_scan or checksum_verify.

string
Example
orphan_scan
status
required

The last stored run label. running can mean queued or stalled work, failed can come before a retry, and completed doesn’t certify that all bytes are healthy.

string
Allowed values: running completed failed
objects_scanned
required

Cumulative number of object-and-variant entries added by saved batch checkpoints, not a count of distinct objects. Retries can count an entry again, and work before a failed checkpoint isn’t included.

integer format: int64
findings_count
required

Cumulative findings added by saved batch checkpoints. Findings are inserted separately, so this can differ from the number of stored rows or their filtered list total.

integer format: int64
started_at

When the run row was created, before the first job was queued. Left out in the minimal trigger fallback.

string format: date-time
nullable
finished_at

Last written by a completed or failed status update; left out until one is recorded. Setting it doesn’t stop further job retries.

string format: date-time
nullable
error

Stored scan error, if any; left out when none is stored. Checkpoint or scheduling errors can fail a job without setting this field.

string
nullable

Malformed request

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"error": "authentication required: sign in and retry with a valid session or API token"
}

Authenticated but missing required capabilities

object
error
required

Human-readable error summary

string
Example
the request could not be completed