Skip to content

Backup storage API

Endpoint paths below are backend-native. Add /api when using the dashboard gateway, for example http://localhost:3005/api/process/capabilities.

Register storage before selecting an archive destination

Registration describes an existing directory already mounted inside DUMB. It does not mount a host share or copy a backup by itself.

flowchart TD
    Mount["Existing directory mounted inside DUMB"] --> Preview["Preview storage identity and permissions"]
    Preview --> Register["Register the reviewed destination"]
    Register --> Select["Select it in a supported archive workflow"]
    Select --> Workflow["Preview that workflow's coverage and capacity"]
    Workflow --> Start["Explicitly start the reviewed workflow"]

Capabilities and routes

Clients gate these authenticated routes using explicit backup_storage_selection=true, numeric backup_storage_protocol=1 and the required kind in backup_storage_kinds. Mutating storage routes require DUMB API 2.24.0 or newer. InfiniDysk migration/cleanup clients additionally enforce the strict API version floor and their specific workflow capabilities. See Backup Storage for mount, privacy and local working-storage requirements.

Destination editing and explicit availability checks additionally require backup_storage_profile_management=true and numeric backup_storage_management_protocol=1. Mount-change review also requires backup_storage_revalidation=true. Older backends keep their registration controls; clients must not send unsupported management requests.

Method Route Purpose
GET /process/backup-storage List registered destinations and the explicitly saved global default
POST /process/backup-storage/preview Inspect an existing container-mounted directory without creating it
POST /process/backup-storage/profiles Register a named destination and bind its mounted identity
PUT /process/backup-storage/profiles/{destination_id} Edit metadata for the same identifier/root
DELETE /process/backup-storage/profiles/{destination_id} Remove registration while retaining archive ownership and receipts
POST /process/backup-storage/profiles/{destination_id}/check Explicitly check current mounted storage
POST /process/backup-storage/profiles/{destination_id}/revalidate/preview Review a changed runtime mount for the same owned storage
POST /process/backup-storage/profiles/{destination_id}/revalidate Confirm the unexpired runtime mount review
POST /process/backup-storage/default Explicitly save or clear the shared default
GET /process/backup-storage/artifacts List owned catalog receipts for destination_id and namespace
GET /process/backup-storage/download Verify and download the registered artifact identified by reference

Register a destination

Preview/registration body:

{
  "id": "archive",
  "name": "Archive storage",
  "path": "/backups/dumb",
  "enabled": true,
  "make_default": false
}

The directory must already exist inside the container. make_default is an explicit opt-in; the dedicated default route accepts {"destination_id": "archive"} or an empty identifier to clear it. Missing or replaced mounts and invalid receipts return a conflict; no local fallback is created. Catalog readiness reflects saved registration, while each artifact operation revalidates the mounted identity.

Shared permissions

Backends advertising backup_storage_shared_permissions=true also accept the strict boolean allow_shared_permissions in preview/registration requests. It defaults to false, including for existing profiles without the field. Explicit true permits fixed/shared mode bits on external managed directories and artifacts; it acknowledges trust in storage access controls rather than proving privacy. The saved profile and private controller metadata retain this choice; the immutable ownership binding is preserved. Private local controller/catalog state remains strict. Older backends must not receive the new field.

Preview and catalog records can include warnings and observed_permissions, with directory_mode and file_mode strings such as "0777" and "0666", or null when not observed. These describe visible modes, not server ACL verification; cached catalog reads do not probe the NAS.

Edit, remove, or check a destination

PUT /process/backup-storage/profiles/{destination_id} accepts the same full profile body as registration. Both id and path must match the existing registration; its name, enabled state and supported shared-permission policy can change. The same identity/use guards apply to an existing profile passed through the registration route. Name edits can remain local during an outage.

DELETE /process/backup-storage/profiles/{destination_id} takes no body and removes only the saved registration. Its result includes removed: true, archives_preserved: true and receipts_preserved: true. The owned marker and immutable binding remain, reserving the identifier for the same storage. Re-registering that identifier/root can restore access to historical receipts. The delete does not rewrite consumers or defaults, delete archive bytes or adopt a new root. Active leases, configured selections and retained recovery references block removal/disable; narrowing permission consent is also guarded when an operation still depends on it.

POST /process/backup-storage/profiles/{destination_id}/check takes no body. It explicitly checks the mounted destination and returns a profile with live_checked, validation_state, revalidation_required, check time and blockers, plus safe usage labels for current references. Cached catalog reads remain local and do not perform that check. A blocked check can return readiness/blockers without changing the registration.

Review a controller mount change

Across a new controller, a changed Linux device number alone is accepted only when durable storage coordinates, directory inode/mode and the existing owned marker match. The persisted binding/fingerprint stays unchanged, preserving old archive and migration references. During a controller's lifetime, full runtime mount identity remains pinned and is rechecked throughout artifact I/O.

POST /process/backup-storage/profiles/{destination_id}/revalidate/preview takes no body. A successful review returns ready, revalidation_required, a single-use token, Unix-seconds expires_at, registered/observed storage descriptors, changes and blockers. The token expires after five minutes. Confirm only the same owned storage:

{
  "token": "<review token>",
  "confirm": true
}

Send that body to POST /process/backup-storage/profiles/{destination_id}/revalidate. confirm is a strict boolean. Expired/changed reviews or active artifact use are rejected. Revalidation refreshes only the runtime pin after repeat checks; it does not rewrite the durable binding, enable a disabled profile, recreate a missing namespace/marker or accept replaced storage. Removing an unused registration retires its runtime check; later registration must prove the same retained binding and marker again.

Select storage in a workflow

Symlink backup requests accept optional backup_destination_id; backup_path is required only for the legacy/path choice. Supplying a registered identifier or @default explicitly selects managed storage. An empty or omitted selection keeps the supplied path, including a custom path. Saved schedules use the service's backup_destination_id field with the same semantics.

Managed results retain backup_manifest as an opaque dumb-backup:// reference and add checksum/readback metadata. Manual and scheduled artifacts have separate retention scopes. /process/symlink-manifest-files accepts backup_destination_id plus optional process_name for catalog browsing, or a verified managed manifest_path. No arbitrary filesystem browsing is added. Compare/restore accept the reference and optional process/destination context; provided context must match. Explicitly choosing an older destination can restore its retained snapshot after the current service preference changes. Global restore without process context still requires a verified symlink artifact kind.

The InfiniDysk major preview accepts optional backup_destination_id to explicitly select a registered destination or @default. An empty or omitted selection keeps its legacy local backup tree. Live SQLite databases, migration control records, database scratch and runtime-install transactions retain their local storage contracts.