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.
Authorizations
Section titled “Authorizations ”Request Body required
Section titled “Request Body required ”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
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.
Responses
Section titled “ Responses ”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
UUID of the sweep run, not a job ID. A trigger response may return another recent run of the requested kind.
Recorded sweep kind: orphan_scan or checksum_verify.
Example
orphan_scanThe 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.
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.
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.
When the run row was created, before the first job was queued. Left out in the minimal trigger fallback.
Last written by a completed or failed status update; left out until one is recorded. Setting it doesn’t stop further job retries.
Stored scan error, if any; left out when none is stored. Checkpoint or scheduling errors can fail a job without setting this field.
Malformed request
object
Human-readable error summary
Example
the request could not be completedAuthentication required, missing, or invalid
object
Human-readable error summary
Example
the request could not be completedExample
{ "error": "authentication required: sign in and retry with a valid session or API token"}Authenticated but missing required capabilities
object
Human-readable error summary
Example
the request could not be completed