backup

The backup domain has 17 actions. On the meta surface they are all reached through arcane_backup; on the individual surface each one is its own tool; on the dynamic surface run them with arcane_execute_action and the canonical ID.

Summary

Action	Title	Kind
`backup.browse_files`	Browse project files in an Arcane system backup	read
`backup.create`	Create Arcane system backup	write
`backup.delete`	Delete Arcane system backup	destructive
`backup.discover`	Discover Arcane system backups in S3	write
`backup.history`	List unified backup history	read
`backup.list`	List Arcane system backups	read
`backup.policies_get`	Get Arcane system backup policies	read
`backup.policies_update`	Update Arcane system backup policies	write
`backup.recovery_key_generate`	Generate an Arcane system backup recovery key	read
`backup.recovery_key_set`	Configure Arcane system backup recovery key	destructive
`backup.restore`	Restore Arcane system backup	destructive
`backup.restore_files`	Restore project files from an Arcane system backup	destructive
`backup.upload_to_s3`	Upload Arcane system backup	write
`backup.volume_config_get`	Get system-managed volume backup policies	read
`backup.volume_config_update`	Update system-managed volume backup policies	write
`backup.volume_options`	List volumes available to system-managed backups	read
`backup.volume_run`	Run system-managed volume backups	write

Actions

`backup.browse_files`

Browse project files in an Arcane system backup

Kind: read
Required parameters: id, recoveryKey
Meta tool: arcane_backup with "action": "browse_files"
Individual tool: arcane_backup_browse_files
Arcane route: POST /api/backups/{id}/files/browse
Operation ID: browse-system-backup-files
Usage: Lists the project files inside a succeeded system backup (id from backup.list) one folder at a time: path is the folder relative to the backup root (empty for the top, where each project is a directory), search switches to a case-insensitive search over all paths, start/limit page. The recoveryKey field must be sent, but an empty string falls back to the stored key. Entries carry path, name and isDirectory, and the paths feed backup.restore_files. Failed backups are refused.
Related actions: backup.list, backup.restore_files

`backup.create`

Create Arcane system backup

Kind: write
Required parameters: none
Meta tool: arcane_backup with "action": "create"
Individual tool: arcane_backup_create
Arcane route: POST /api/backups
Operation ID: create-system-backup
Usage: Backs up Arcane itself (its SQLite database and projects directory, encrypted with the recovery key), not Docker volume data (volume_backup.create or backup.volume_run). destination is local (default), s3 or local_s3, the S3 ones with s3DestinationId from s3_destination.list. policyId runs a saved policy’s targets instead. recoveryKey may be omitted once one is stored (backup.recovery_key_set). Global admin only. Accepted in the background, it returns the run (id system-…, status running, activityId): poll backup.list until status is succeeded or failed. Only one system backup or system-managed volume run at a time. Refused unless Arcane uses the SQLite database provider. A containerised Arcane must also find its own container on the Docker host it manages, otherwise the accepted run fails (error could not detect Arcane container).
Related actions: backup.list, backup.recovery_key_set, s3_destination.list, backup.upload_to_s3, volume_backup.create

`backup.delete`

Delete Arcane system backup

Kind: destructive — requires confirm: true
Required parameters: id
Meta tool: arcane_backup with "action": "delete"
Individual tool: arcane_backup_delete
Arcane route: DELETE /api/backups/{id}
Operation ID: delete-system-backup
Usage: Permanently deletes a system backup (id from backup.list): forgets its local and S3 snapshots and removes its record. recoveryKey is optional (the stored key is used), and a failed backup without snapshots needs no key at all. If a snapshot cannot be forgotten the record stays with the remaining one.
Related actions: backup.list, backup.history

`backup.discover`

Discover Arcane system backups in S3

Kind: write
Required parameters: recoveryKey, s3DestinationId
Meta tool: arcane_backup with "action": "discover"
Individual tool: arcane_backup_discover
Arcane route: POST /api/backups/discover
Operation ID: discover-system-backups
Usage: Imports the system backups found on an S3 destination (s3DestinationId from s3_destination.list) that this instance does not know yet, after a reinstall for example, as remote-… records in backup.list, and returns how many were added (0 when all are known). recoveryKey must be the key they were made with (empty uses the stored key). Volume backups are discovered with volume_backup.discover.
Related actions: s3_destination.list, backup.list, backup.restore, volume_backup.discover

`backup.history`

List unified backup history

Kind: read
Required parameters: none
Meta tool: arcane_backup with "action": "history"
Individual tool: arcane_backup_history
Arcane route: GET /api/backups/history
Operation ID: list-backup-history
Usage: One paginated list of every backup record: Arcane system backups and Docker volume backups of all volumes, each with resourceType (system or volume) and resourceName (Arcane or the volume name). type filters by origin: system (system backups plus volume backups made by system-managed policies or backup.volume_run) or volume (per-volume backups from volume_backup.*). search matches id, status, trigger, destination, error, resource name or type. Use it to follow backup.volume_run results.
Related actions: backup.list, backup.volume_run, volume_backup.list

`backup.list`

List Arcane system backups

Kind: read
Required parameters: none
Meta tool: arcane_backup with "action": "list"
Individual tool: arcane_backup_list
Arcane route: GET /api/backups
Operation ID: list-system-backups
Usage: Paginated Arcane system backups (id system-…, or remote-… when imported by backup.discover) with status (running, succeeded, failed), trigger (manual, scheduled, safety), destination, localSnapshotId/remoteSnapshotId, policyId and error. The id feeds backup.browse_files, backup.restore, backup.upload_to_s3 and backup.delete. search matches status, trigger, destination or error. Volume backups are not here: use backup.history.
Related actions: backup.create, backup.history, backup.browse_files, backup.restore, backup.delete

`backup.policies_get`

Get Arcane system backup policies

Kind: read
Required parameters: none
Meta tool: arcane_backup with "action": "policies_get"
Individual tool: arcane_backup_policies_get
Arcane route: GET /api/backups/policies
Operation ID: get-system-backup-policies
Usage: Scheduled system backup policies (id, enabled, schedule, retentionCount, localEnabled, s3Enabled, s3DestinationId, lastRun) and whether a recovery key is stored (recoveryKeyStored). Read it before backup.policies_update, which replaces the whole list.
Related actions: backup.policies_update, backup.recovery_key_set, backup.list

`backup.policies_update`

Update Arcane system backup policies

Kind: write
Required parameters: policies
Meta tool: arcane_backup with "action": "policies_update"
Individual tool: arcane_backup_policies_update
Arcane route: PUT /api/backups/policies
Operation ID: update-system-backup-policies
Usage: Replaces the whole list of scheduled system backup policies: keep a policy by sending its id from backup.policies_get, add one by omitting id. Omitted policies are deleted ([] removes them all). Each needs enabled, schedule (six-field cron with seconds, e.g. 0 0 3 * * *), retentionCount (succeeded backups kept, 0-3650, 0 keeps all), localEnabled and/or s3Enabled, plus s3DestinationId when s3Enabled. Enabling needs a stored recovery key. An enabled policy becomes job system-backup:<policyId>, runnable now with job.run.
Related actions: backup.policies_get, backup.recovery_key_set, s3_destination.list, job.run

`backup.recovery_key_generate`

Generate an Arcane system backup recovery key

Kind: read
Required parameters: none
Meta tool: arcane_backup with "action": "recovery_key_generate"
Individual tool: arcane_backup_recovery_key_generate
Arcane route: POST /api/backups/recovery-key/generate
Operation ID: generate-system-backup-recovery-key
Usage: Only returns a fresh random recoveryKey (8 dash-separated groups of 6 characters). Nothing is stored until backup.recovery_key_set. Give the key to the user to keep: system and volume backups cannot be opened without it.
Related actions: backup.recovery_key_set, backup.policies_get

`backup.recovery_key_set`

Configure Arcane system backup recovery key

Kind: destructive — requires confirm: true
Required parameters: recoveryKey
Meta tool: arcane_backup with "action": "recovery_key_set"
Individual tool: arcane_backup_recovery_key_set
Arcane route: PUT /api/backups/recovery-key
Operation ID: set-system-backup-recovery-key
Usage: Stores the recovery key (from backup.recovery_key_generate, other formats are refused) that encrypts system and volume backups, and is needed before enabling scheduled system backups. Replacing a stored key with a different one is refused while system or volume backups exist, since they open only with the key that made them. Returns configured true, and backup.policies_get reports recoveryKeyStored.
Related actions: backup.recovery_key_generate, backup.policies_get

`backup.restore`

Restore Arcane system backup

Kind: destructive — requires confirm: true
Required parameters: id, recoveryKey
Meta tool: arcane_backup with "action": "restore"
Individual tool: arcane_backup_restore
Arcane route: POST /api/backups/{id}/restore
Operation ID: restore-system-backup
Usage: Rolls the whole Arcane instance back to a succeeded system backup (id from backup.list): takes a local safety backup, then a helper container stops Arcane, replaces its database and projects and restarts it, so Arcane is unreachable for a while and everything created since the backup (settings, S3 destinations, projects…) is gone. Returns once the helper has started. Global admin only. Needs Arcane running in Docker with /app/data mounted, and recoveryKey must be sent (empty uses the stored key). For single project files use backup.restore_files.
Related actions: backup.list, backup.restore_files, backup.create

`backup.restore_files`

Restore project files from an Arcane system backup

Kind: destructive — requires confirm: true
Required parameters: id, recoveryKey
Meta tool: arcane_backup with "action": "restore_files"
Individual tool: arcane_backup_restore_files
Arcane route: POST /api/backups/{id}/restore-files
Operation ID: restore-system-backup-files
Usage: Overwrites selected project files in Arcane’s projects directory with their copies from a succeeded system backup, after taking a safety backup. Arcane’s database is not touched. Select with paths (from backup.browse_files), or selectAll (not with paths), optionally narrowed by search. recoveryKey must be sent (empty uses the stored key). A restored directory is mirrored, so files added to it since the backup are deleted (selectAll without search does this to the whole projects directory). Waits for the restore to finish and rolls back on failure. Entries that contain Arcane’s data directory are refused.
Related actions: backup.browse_files, backup.list, backup.restore, project.get

`backup.upload_to_s3`

Upload Arcane system backup

Kind: write
Required parameters: id, recoveryKey, s3DestinationId
Meta tool: arcane_backup with "action": "upload_to_s3"
Individual tool: arcane_backup_upload_to_s3
Arcane route: POST /api/backups/{id}/upload
Operation ID: upload-system-backup
Usage: Copies a succeeded system backup that has a local snapshot (id from backup.list) to an S3 destination (s3DestinationId from s3_destination.list). recoveryKey must be sent (empty uses the stored key). Waits for the copy and returns the run with remoteSnapshotId and destination local_s3. A backup already uploaded is refused.
Related actions: backup.list, s3_destination.list, backup.discover

`backup.volume_config_get`

Get system-managed volume backup policies

Kind: read
Required parameters: none
Meta tool: arcane_backup with "action": "volume_config_get"
Individual tool: arcane_backup_volume_config_get
Arcane route: GET /api/backups/volumes/config
Operation ID: get-system-volume-backup-config
Usage: System-managed volume backup policies, each selecting many volumes at once (unlike the per-volume policies of volume_backup.policy_get): id, enabled, schedule, retentionCount, stopContainers, local/S3 targets, selectionMode, volumeNames, ignoreAnonymous and lastRun. Read it before backup.volume_config_update, which replaces the whole list. An id feeds backup.volume_run policyId.
Related actions: backup.volume_config_update, backup.volume_run, volume_backup.policy_get

`backup.volume_config_update`

Update system-managed volume backup policies

Kind: write
Required parameters: policies
Meta tool: arcane_backup with "action": "volume_config_update"
Individual tool: arcane_backup_volume_config_update
Arcane route: PUT /api/backups/volumes/config
Operation ID: update-system-volume-backup-config
Usage: Replaces the whole list of system-managed volume backup policies: keep one by sending its id from backup.volume_config_get, add one by omitting id. Omitted policies are deleted ([] removes them all). Each selects volumes with selectionMode all, allowlist or blocklist plus volumeNames (from backup.volume_options) and ignoreAnonymous, and needs enabled, schedule (six-field cron with seconds), retentionCount, localEnabled and/or s3Enabled (with s3DestinationId). stopContainers stops the volumes’ containers during the backup. Volumes with an enabled per-volume policy (volume_backup.policy_update) are skipped. An enabled policy becomes job system-backup:volumes:<policyId>.
Related actions: backup.volume_config_get, backup.volume_options, backup.volume_run, volume_backup.policy_update

`backup.volume_options`

List volumes available to system-managed backups

Kind: read
Required parameters: none
Meta tool: arcane_backup with "action": "volume_options"
Individual tool: arcane_backup_volume_options
Arcane route: GET /api/backups/volumes/options
Operation ID: list-system-volume-backup-options
Usage: Volume names a system-managed volume backup policy or backup.volume_run can select: the local Docker volumes minus internal ones and Arcane’s own, each with anonymous, plus names saved in policies that no longer exist (available false, skipped by runs).
Related actions: backup.volume_config_update, backup.volume_run, volume.list

`backup.volume_run`

Run system-managed volume backups

Kind: write
Required parameters: none
Meta tool: arcane_backup with "action": "volume_run"
Individual tool: arcane_backup_volume_run
Arcane route: POST /api/backups/volumes/run
Operation ID: run-system-volume-backups
Usage: Backs up many local Docker volumes now, from either policyId (backup.volume_config_get) or custom {destination local|s3|local_s3, s3DestinationId, stopContainers, selectionMode, volumeNames, ignoreAnonymous}, not both. With neither it backs up every non-anonymous volume locally. Runs in the background and returns activityId (follow with activity.get in environment 0). Each volume’s backup then appears in backup.history with type system. Volumes with an enabled per-volume policy (volume_backup.policy_update) are skipped. Refused while a system backup or another such run is in progress.
Related actions: backup.volume_options, backup.volume_config_get, backup.history, activity.get, volume_backup.create