API reference
/v1/admin/control-backup10 operations
← All groups · First call? Read the tutorial: auth, permissions, requests and responses, common failures
| Method | Path | Summary | Auth |
|---|---|---|---|
| GET | /v1/admin/control-backup | Signer fingerprint, freeze state, bundles, recent runs and redacted settings | Session |
| POST | /v1/admin/control-backup/backups | Queue an immediate backup | Session |
| DELETE | /v1/admin/control-backup/backups/{backup_id} | Queue deletion of a bundle and its remote copies; body confirm must equal backup_id | Session |
| GET | /v1/admin/control-backup/backups/{backup_id}/restore-commands | Text commands to restore a bundle onto an empty host (nothing is executed) | Session |
| POST | /v1/admin/control-backup/host-key | Read an SSH host key fingerprint to pin before a migration | Session |
| POST | /v1/admin/control-backup/migrations | Queue a migration to an empty new host; confirm must equal host. This control plane stays frozen after success. | Session |
| POST | /v1/admin/control-backup/recovery-kit | Download the backup identity sealed with a passphrase (scrypt) for off-host disaster recovery | Session |
| GET | /v1/admin/control-backup/runs/{run_id} | One agent run with its redacted log | Session |
| PUT | /v1/admin/control-backup/settings | Replace schedule, retention and off-host targets | Session |
| POST | /v1/admin/control-backup/targets/probe | Write, read back and delete a probe object on the target as on screen (nothing is saved) | Session |
Contract file：api/control-native-backup.openapi.yaml
/v1/admin/control-backupSigner fingerprint, freeze state, bundles, recent runs and redacted settings
| Status | Description |
|---|---|
200 | Status |
401 | Authentication required |
403 | Permission denied |
401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account./v1/admin/control-backup/backupsQueue an immediate backup
| Status | Description |
|---|---|
202 | Queued run |
409 | Another backup or migration is queued or running |
409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body./v1/admin/control-backup/backups/{backup_id}Queue deletion of a bundle and its remote copies; body confirm must equal backup_id
| Name | In | Type | Required | Description |
|---|---|---|---|---|
backup_id | path | string | Yes | — |
| Status | Description |
|---|---|
202 | Queued |
400 | Confirmation mismatch |
400 Fix the parameters or body per the field list; do not retry unchanged./v1/admin/control-backup/backups/{backup_id}/restore-commandsText commands to restore a bundle onto an empty host (nothing is executed)
| Name | In | Type | Required | Description |
|---|---|---|---|---|
backup_id | path | string | Yes | — |
| Status | Description |
|---|---|
200 | Commands |
/v1/admin/control-backup/host-keyRead an SSH host key fingerprint to pin before a migration
| Status | Description |
|---|---|
200 | Fingerprint |
502 | Host unreachable |
/v1/admin/control-backup/migrationsQueue a migration to an empty new host; confirm must equal host. This control plane stays frozen after success.
| Status | Description |
|---|---|
202 | Queued run |
400 | Invalid target or confirmation mismatch |
409 | Busy |
400 Fix the parameters or body per the field list; do not retry unchanged.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body./v1/admin/control-backup/recovery-kitDownload the backup identity sealed with a passphrase (scrypt) for off-host disaster recovery
| Status | Description |
|---|---|
200 | Recovery kit JSON |
400 | Passphrase shorter than 12 characters |
400 Fix the parameters or body per the field list; do not retry unchanged./v1/admin/control-backup/runs/{run_id}One agent run with its redacted log
| Name | In | Type | Required | Description |
|---|---|---|---|---|
run_id | path | string | Yes | — |
| Status | Description |
|---|---|
200 | Run |
404 | Unknown run |
404 The resource does not exist or belongs to another tenant./v1/admin/control-backup/settingsReplace schedule, retention and off-host targets
expected_revision must equal settings.revision of the status read (409 control_backup_revision_conflict otherwise). Each target names the saved target it edits in stored_name (absent for a new target, which never inherits stored secrets). Empty secret fields keep the stored value of stored_name; for SFTP only while auth stays the same: a changed auth without a matching new credential is 400 control_backup_auth_changed, and a credential that does not fit auth is 400 control_backup_invalid_private_key / control_backup_invalid_password, with error.details {target, field}.
| Status | Description |
|---|---|
200 | Updated status |
400 | Invalid settings or a refused target credential |
409 | The settings changed since expected_revision |
400 Fix the parameters or body per the field list; do not retry unchanged.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body./v1/admin/control-backup/targets/probeWrite, read back and delete a probe object on the target as on screen (nothing is saved)
Body {expected_revision, target}. target is merged over the stored settings exactly as a save would (same stored_name and credential rules), then probed.
| Status | Description |
|---|---|
200 | Probe result (ok and a redacted message) |
400 | Invalid target or a refused credential |
409 | The settings changed since expected_revision |
400 Fix the parameters or body per the field list; do not retry unchanged.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.