Backups ability reference
Reference for the GoBuildWP Pro 1.12.4 and Free 1.18.6 source. Installed schemas and policy remain authoritative.
This Backups ability reference covers how an agent reads the site's backups from UpdraftPlus, Duplicator, BackWPup and All-in-One WP Migration and starts a new one with the backup plugin's own scheduler or, for All-in-One WP Migration, by running that plugin's own export steps on the server. It reports the last backup and whether it worked, what it contained, its size, jobs running now and the next scheduled run. It cannot restore, download or delete a backup, and never returns archive paths.
Read-only, write and destructive groups describe the source annotations. They do not establish a minimum safety profile, human approval or undo support. Those controls are separate: check the installed ability, the connected user and the active site policy before calling it. A read can still return sensitive data. These pages are not evidence that every operation passed an end-to-end runtime test.
What Backups needs before these load
2 of the 3 also ship in GoBuildWP Free 1.18.6 under the same names, marked “Also in GoBuildWP Free” below. They need no GoBuildWP Pro licence, but each retains its own dependency, feature and permission checks. Where Free's copy does less, its own description follows Pro's. When Pro's richer copy passes its gates, it registers first and answers.
At least one of UpdraftPlus 1.26 or newer, Duplicator 5.0 or newer, BackWPup 5.7 or newer, or All-in-One WP Migration 7.112 or newer must be active; Pro loads the kit when the UpdraftPlus, BackWPup, Duplicator\Package\DupPackage or Ai1wm_Backups class, or the UPDRAFTPLUS_DIR constant, is present. Duplicator Pro and Duplicator before 5.0 are not read. Every call checks that GoBuildWP is switched on and that the user has manage_options. With no supported plugin active, a trigger call returns kit_backups_provider_required. The free plugin's backup-status still reports, in trigger, whether Pro could start a backup for each provider; backup-trigger and the fresh-backup hold are Pro's.
- Backups editions
- free
What each backup plugin allows from here
UpdraftPlus is read from its backup history and its last-backup record, and a backup can be started with scope full, database or files, sent wherever UpdraftPlus is configured to store it. BackWPup is read from its job logs; it can run a job whose schedule type is WP-Cron, picked with job_id when there are several. Duplicator is read from its duplicator_backups table and cannot be started from here, because the free version has no server-side start (kit_backups_trigger_unsupported).
All-in-One WP Migration (provider ai1wm) is read from the .wpress files in its backups folder. A file counts as a backup only in the folder itself, at least 1 MB, not dated in the future, and ending in a complete archive block by the plugin's own check; anything else is listed as unverified. backup-trigger starts a full export by running the plugin's own export steps on the server in short slices: up to five seconds inside the call, then on WP-Cron and for a few seconds before each wppilot/backup-status answer. It does not rely on the plugin's loopback requests to admin-ajax.php, which some hosts drop. The call answers running (or finished, for a very small site); poll backup-status until running is false and the newest backup is later than queued_at, and read its export state, which says running, stalled or failed with the reason. A step that throws, keeps restarting or makes no progress for 15 minutes fails the export and deletes its job folder.
BackWPup logs outlive archives, so a successful run to a local folder counts while the archive it names is still there, and otherwise shows as deleted. Runs sent to remote storage are listed with archive_verified false.
What is kept out of every result
Results carry times in the site timezone and UTC, the result, contents, size in bytes, storage names, labels and error and warning counts. Archive paths and file names, download URLs, job nonces and storage credentials are never returned.
When a backup start is refused
wppilot/backup-trigger is refused while a backup with that plugin is running or queued (kit_backups_running), and within 15 minutes of the last one this ability started for it, an hour for All-in-One WP Migration (kit_backups_cooldown; the wppilot_kit_backups_trigger_cooldown filter changes the interval). Two calls at once take one lock per backup plugin, so the second is refused (kit_backups_trigger_busy). All-in-One WP Migration is also refused when the disk holding its backups has less free space than twice the newest export, or 1 GB with none to go by (kit_backups_disk_space), because the free plugin never deletes an export. With more than one backup plugin active, provider has to be named. A start is recorded in the change ledger as irreversible: there is nothing for an undo to take back.
Example Backups input: wppilot/backup-status
This one operation declares the 1 top-level input parameters below in wppilot/includes/kits/backup-status/src/abilities/backup-status.php, and none is required on its own. Other calls in this module take different arguments. Nested schemas and constraints are not expanded here; the complete live schema a connected client discovers is authoritative.
| Parameter | Type and meaning |
|---|---|
provider | string one of updraftplus, duplicator, backwpup, ai1wm. Only this backup plugin. Defaults to every active one. |
Representative call sequence
This sequence describes the documented calls and checks to perform. It is not a recorded result from an installed WordPress site. Inspect returned errors and partial results, then verify the saved values and affected output before proceeding.
Before a large content import, make sure the site has a fresh database backup.
- 01
wppilot/backup-statusReturns the newest successful UpdraftPlus backup, what it contained and whether a backup is running. - 02
wppilot/backup-triggerQueues an UpdraftPlus backup with scope database and returns at once with the backup queued. - 03
wppilot/backup-listShows the new backup at the top once it has finished, with its result, size and storage names.
Questions about Backups
Can my agent restore a backup through GoBuildWP?
No. The kit reads backups and can start one, but restoring, downloading and deleting stay in the backup plugin's own screens.
Why does a BackWPup backup show as deleted when the run succeeded?
The log for that run still exists, but the archive it names is no longer in the job's local folder. The kit checks the archive rather than trusting the log.
Why are All-in-One WP Migration file names never returned?
On servers that ignore the backups folder's .htaccess, such as nginx, a .wpress file's name is enough to download the whole site. Each backup is identified by a hash of its name instead.
Backups reads
| Ability | What it does |
|---|---|
wppilot/backup-listList BackupsAlso in GoBuildWP Free | Recent backups per active backup plugin, newest first: when (site timezone and UTC), result (success, failed, cancelled, running or unknown), contents, size in bytes, storage names, the label or job name, and error and warning counts where the plugin records them. UpdraftPlus lists its backup sets (only the most recent has a recorded result), Duplicator its backups, BackWPup its job runs from its logs, All-in-One WP Migration (provider "ai1wm") the finished exports in its backups folder (time is when the export finished; contents are not recorded). limit applies per provider (default 20, at most 100). Never returns archive paths, file names, download links or storage credentials. In GoBuildWP Free: Recent backups per active backup plugin, newest first: when (site timezone and UTC), result (success, failed, cancelled, running or unknown), contents, size in bytes, storage names, the label or job name, and error and warning counts where the plugin records them. UpdraftPlus lists its backup sets (only the most recent has a recorded result), Duplicator its backups, BackWPup its job runs from its logs, All-in-One WP Migration (provider "ai1wm") the finished exports in its backups folder (time is when the export finished; contents are not recorded). limit applies per provider (default 20, at most 100). Never returns archive paths, file names, download links or storage credentials. |
wppilot/backup-statusBackup StatusAlso in GoBuildWP Free | Backup health for each active backup plugin (UpdraftPlus, Duplicator, BackWPup, All-in-One WP Migration as provider "ai1wm"): the last backup and its result (success, failed, cancelled, running or unknown), the last successful one, what it contained (db, plugins, themes, uploads… when the plugin records it), its size, whether a backup is running or queued now, the next scheduled backup, and the names of the storage archives go to. Times are given in the site timezone (time) and UTC (time_utc). Each provider says whether it can be read, and in trigger whether the Pro edition could start a backup for it. Never returns archive paths, download links or storage credentials. Use before a risky change to confirm a recent good backup exists. In GoBuildWP Free: Backup health for each active backup plugin (UpdraftPlus, Duplicator, BackWPup, All-in-One WP Migration as provider "ai1wm"): the last backup and its result (success, failed, cancelled, running or unknown), the last successful one, what it contained (db, plugins, themes, uploads… when the plugin records it), its size, whether a backup is running or queued now, the next scheduled backup, and the names of the storage archives go to. Times are given in the site timezone (time) and UTC (time_utc). Each provider says whether it can be read, and in trigger whether the Pro edition could start a backup for it. Never returns archive paths, download links or storage credentials. Use before a risky change to confirm a recent good backup exists. |
Backups writes
| Ability | What it does |
|---|---|
wppilot/backup-triggerStart a Backup | Start a backup with the backup plugin's own scheduler. UpdraftPlus: scope "full" (default), "database" or "files", stored where UpdraftPlus is configured to send it. BackWPup: runs one of its jobs that is scheduled with WP-Cron (job_id when there are several); the job decides what is backed up, so scope is not accepted. All-in-One WP Migration (provider "ai1wm"): a full export to its backups folder, run on the server with the plugin's own export steps in short slices on WP-Cron and on every wppilot/backup-status read, so it does not depend on the plugin's loopback requests; scope is not accepted, and it is refused when the disk has less free space than twice the newest export (the free plugin never deletes old ones). Duplicator cannot be started from here. provider is required when more than one backup plugin is active. The backup runs in the background: this returns at once with state "queued" (UpdraftPlus, BackWPup: WP-Cron), "running" (All-in-One WP Migration), and wppilot/backup-status shows it running and then its result; for All-in-One WP Migration its providers[].export says running, stalled or failed, with the reason. Refused while a backup of that plugin is running, queued or being started by another call, and within 15 minutes (All-in-One WP Migration: 1 hour) of the last one this ability started for it. Creates an archive; it does not restore, download or delete anything. |