Symlink operations API¶
Endpoint paths below are backend-native. Add /api when using the dashboard gateway, for example http://localhost:3005/api/process/capabilities.
Review changes before applying them
Use a dry run to inspect the proposed link changes. Asynchronous operations expose a job to poll; keep its final report with the backup used for recovery.
flowchart TD
Request["Choose repair, migration or restore inputs"] --> Dry["Request a dry run"]
Dry --> Review["Review paths, conflicts and proposed changes"]
Review --> Apply["Submit the intended non-dry-run operation"]
Apply --> Async{"Asynchronous route?"}
Async -->|Yes| Poll["Poll /process/symlink-job-status"]
Async -->|No| Response["Inspect the operation response"]
Poll --> Verify["Read the final report and verify representative links"]
Response --> Verify
POST /process/symlink-repair¶
Runs symlink target rewrites for service symlink trees (Decypharr, InfiniDysk, CLI Debrid, Riven).
Use this endpoint when mount paths change and existing symlink targets need to be rewritten.
Request Body:¶
{
"dry_run": true,
"include_broken": true,
"presets": ["decypharr_beta_consolidated"],
"roots": ["/mnt/debrid/decypharr_symlinks", "/mnt/debrid/clid_symlinks"],
"root_migrations": [
{
"from_root": "/mnt/debrid/decypharr_symlinks",
"to_root": "/mnt/debrid/combined_symlinks"
}
],
"overwrite_existing": false,
"copy_instead_of_move": false,
"rewrite_rules": [
{
"from_prefix": "/mnt/debrid/old",
"to_prefix": "/mnt/debrid/new"
}
],
"backup_path": "/config/symlink-repair/manifest.json"
}
Behavior¶
dry_run: truescans and reports without changing symlinks.dry_run: falserewrites matching symlinks in place.process_nameis optional but recommended for async runs/job lookup.- Provide at least one of:
presets,rewrite_rules,root_migrations. root_migrationsmoves symlink entries from one symlink tree to another while preserving relative paths. This is intended for individual-root to combined-root migrations.overwrite_existingcontrols behavior when a destination symlink already exists during root migration.copy_instead_of_move(root migration mode) creates destination symlinks and keeps source symlinks in place.- If
rootsis omitted, backend defaults are used:/mnt/debrid/decypharr_symlinks,/mnt/debrid/infinidysk-symlinks,/mnt/debrid/combined_symlinks,/mnt/debrid/clid_symlinks, andriven_backend.symlink_library_pathwhen configured. backup_pathis written only for non-dry-run operations with changes.
Example Response:¶
{
"dry_run": true,
"scanned_symlinks": 2451,
"changed": 312,
"moved": 120,
"copied": 0,
"skipped_unchanged": 2139,
"errors": [],
"changes": []
}
POST /process/symlink-repair-async¶
Queues symlink repair as a background job and returns immediately.
Use GET /process/symlink-job-status (or /process/symlink-job-latest) to track completion.
Response (example)¶
POST /process/symlink-manifest/backup¶
Creates a standalone snapshot manifest of symlink entries for later restore.
Request Body:¶
{
"backup_path": "/config/symlink-repair/snapshots/latest.json",
"roots": ["/mnt/debrid/decypharr_symlinks", "/mnt/debrid/clid_symlinks"],
"include_broken": true
}
Behavior¶
- Writes a manifest containing
link_path+targetentries. - If
rootsis omitted, backend default symlink roots are used. - Used by the internal DUMB scheduler when
symlink_backup_enabledis set on supported services. - Scheduled runs can prune older manifests when
symlink_backup_retention_countis greater than0.
POST /process/symlink-manifest/backup-async¶
Queues a standalone snapshot backup as a background job and returns immediately.
Response (example)¶
{
"status": "queued",
"job_id": "8e9fd0fbe88d4a6fbb2f3f77b2a3f8c1",
"operation": "symlink_manifest_backup"
}
GET /process/symlink-job-status¶
Returns status/result for background symlink jobs.
Query Params¶
job_id(required)
Response fields¶
status:queued,running,completed, orerrorresult: operation payload when completederror: error payload when failedcreated_at,updated_at,started_at,finished_attimestamps (when available)
GET /process/symlink-job-latest¶
Returns the latest symlink job for a process/operation (optionally only active jobs).
Query Params¶
process_name(required)operation(optional, defaultsymlink_manifest_backup)active_only(optional, defaulttrue)
POST /process/symlink-manifest/restore¶
Restores symlinks from a previously generated snapshot manifest.
Request Body:¶
{
"manifest_path": "/config/symlink-repair/snapshots/latest.json",
"dry_run": true,
"overwrite_existing": false,
"restore_broken": true
}
Behavior¶
dry_run: truepreviews restore actions without writing.overwrite_existingcontrols whether existing paths are replaced.restore_brokencontrols whether entries with currently missing targets are restored.
GET /process/symlink-manifest/compare¶
Compares a snapshot manifest against current filesystem state and returns projected restore outcomes.
Query Params¶
manifest_path(required)overwrite_existing(optional, defaultfalse)restore_broken(optional, defaulttrue)sample_limit(optional, default50, max200)
Behavior¶
- Uses the same overwrite/missing-target rules as restore.
- Returns projected counts (
projected_restored, skipped categories, errors). - Returns
sample_changeswith representative actions (create,overwrite,skip_*) for quick review before apply.
POST /process/symlink-manifest/restore-async¶
Queues restore as a background job and returns immediately.
Use GET /process/symlink-job-status (or /process/symlink-job-latest) to track completion.
GET /process/symlink-backup-status¶
Returns current symlink-backup scheduler state for a service.
GET /process/symlink-backup-manifests¶
Lists backup manifests that match the current service symlink_backup_path template.
GET /process/symlink-manifest-files¶
Lists files under /config/symlink-repair/snapshots by default.
Use this to populate manifest pickers in the Snapshot tab for quick restore/overwrite selection.
POST /process/symlink-backup/reschedule¶
Rebuilds symlink-backup schedule state from current service config.