Skip to main content

App Environment Backups API

The App Environment Backups API lets you inspect and configure logical database backups and volume snapshot recovery points for a Quave ONE app environment.

Make sure to read the Get Started document to understand authentication, base URLs, and token types.

Customer-facing endpoints mirror the regular Backups and Snapshots tabs. Raw schedules, incremental-chain caps, storage paths, and credentials remain internal.

Backup overview and workspace freshness use the newest valid full or incremental snapshot timestamp across volume chains (falling back to chain creation when entry timestamps are unavailable), compared with the latest logical database backup when applicable. A recovery point is stale after 48 hours; a chain's age alone does not make recent incrementals stale. latestRecoveryPointBackupId names the snapshot chain holding the newest point; when two staggered chains captured the same tick, it is the chain with the shorter restore sequence.

Update Snapshot Options​

Updates the same customer-friendly recovery-point interval, full snapshot period, recovery points during full snapshots and replica coverage shown in the Snapshots tab. Quave ONE converts the selected interval and period to the exact low-level configuration sent to the Go API. An option you omit keeps its stored value, so changing replica coverage or the interval does not reset the full snapshot period.

Endpoint: PATCH /api/public/v1/app-env/snapshot-options

This operation requires account-admin permission. Environment tokens cannot use it.

Request Body​

FieldTypeRequiredDescription
appEnvIdStringEitherThe ID of the app environment.
envNameStringEitherThe CLI environment name, as an alternative ID.
snapshotFrequencyEnumAt least one optionEVERY_HOUR, EVERY_2_HOURS, EVERY_4_HOURS, EVERY_6_HOURS, EVERY_8_HOURS, or EVERY_12_HOURS.
fullSnapshotPeriodEnumAt least one optionHow often a snapshot chain starts with a new full snapshot: EVERY_DAY (default), EVERY_7_DAYS, EVERY_15_DAYS, or EVERY_30_DAYS. Every other recovery point in the period is an incremental.
backupSingleReplicaOnlyBooleanAt least one optiontrue backs up one database replica; false backs up every replica.
snapshotBackupDisabledBooleanAt least one optiontrue stops scheduled volume snapshots and keeps existing recovery points. false turns them back on at the stored interval.
recoveryPointsDuringFullEnumAt least one optionKeep recovery points during full snapshots: OFF (default), HANDOVER or TWO_LANES. See Recovery points during full snapshots.
interleaveLanePointsBooleanAt least one optiontrue makes the two chains of TWO_LANES take turns, so a recovery point lands every half interval. Needs TWO_LANES (in the same request or already stored); otherwise the request is rejected. Choosing another recoveryPointsDuringFull turns it off. Default false. See Interleave lane points.

Do not send snapshotSchedule, incrementalCount, chainLanes, laneSpacing or laneTickPolicy; customer API clients use only the friendly enum contract.

Full snapshot period​

A chain holds one full snapshot plus incrementals until the period ends, so it has days × 24 ÷ interval hours recovery points (for example, EVERY_HOUR with EVERY_7_DAYS gives 168). A new period applies from the next chain; the running chain keeps the length it started with.

  • Longer periods read and upload the whole volume less often, which matters for large volumes.
  • Restores take longer: restoring a point applies the full snapshot and every incremental up to it, up to 720 files for hourly points with a 30-day period.
  • Failures cost more: today a failed incremental ends the chain and the next run starts a new full snapshot.
  • Retention works by chain: volume snapshot retentionDays is how far back you can restore. Cleanup deletes a chain only after its newest recovery point is older than retentionDays, and deletes it whole, so stored snapshots can span up to retentionDays + the full period. A chain whose full snapshot is still uploading does not count as the newest chain, so it never causes the previous complete chain to be removed by age or by the storage cap. The newest complete chain is always kept; when every replica is backed up (backupSingleReplicaOnly: false), the newest complete chain of each current replica's volume is (a volume left by a removed replica expires normally).

Existing environments keep one full snapshot per day until you choose another period.

Recovery points during full snapshots​

Without this option, one chain is written at a time: while a full snapshot uploads, no new recovery point is created. For a large volume whose full snapshot takes longer than the recovery-point interval (a multi-terabyte database can take a day or more), that is a gap in recovery points. Turn it on when a full snapshot takes longer than the interval; the Snapshots tab shows how long the last full snapshot took to upload.

  • HANDOVER (recommended): when a chain reaches the full period, the next chain starts its full snapshot and the previous chain keeps adding incrementals until that full completes, then closes. Storage grows by about one full snapshot plus the incrementals taken while it uploads.
  • TWO_LANES: two independent chains whose full snapshots start half a period apart. Storage holds about twice the full snapshots, restores of the latest point apply fewer incrementals, and a failed full on one chain leaves the other chain restorable.

Two full snapshots of one volume never upload at once. Each recovery point belongs to one chain, and a restore uses only that point's own chain. The volume-backup list returns the points of both chains newest first with their chain as lane (0 or 1); when two chains captured the same moment, the one with the shorter restore sequence comes first. With TWO_LANES, cleanup always keeps the newest complete chain of each lane, by age and by the storage cap. With HANDOVER the chains take turns, so cleanup keeps only the newest complete chain. An active (warm) Disaster Readiness standby keeps one chain, so this option does not apply to it while that protection is on. The setting applies from the next chain. Responses return recoveryPointsDuringFull, its label and chainLanes.

Interleave lane points​

With TWO_LANES, both chains normally take a point at every interval. Set interleaveLanePoints: true to make them take turns instead: the schedule runs every half interval and each run goes to one chain, so the volume gets a recovery point every half interval. While one chain uploads its full snapshot, the other chain takes every run.

snapshotFrequencyRecovery point with interleaveLanePoints
EVERY_HOURevery 30 min
EVERY_2_HOURSevery hour
EVERY_4_HOURSevery 2 hours
EVERY_6_HOURSevery 3 hours
EVERY_8_HOURSevery 4 hours
EVERY_12_HOURSevery 6 hours

Each chain keeps the length of the chosen interval and full period (for example, 720 points for EVERY_HOUR with EVERY_30_DAYS), so restores apply as many incrementals as before and storage stays about the same as TWO_LANES. The setting applies from the next chain. Responses return interleaveLanePoints and recoveryPointFrequency, a sentence with the effective frequency, for example A recovery point every 30 min outside a full (lanes alternate); every 30 min on one lane while the other uploads its full. Both describe the schedule actually in effect: when a custom schedule or Disaster Readiness sets the interval, the interval is not halved, interleaveLanePoints is false and recoveryPointFrequency ends with Interleave is not active with a custom or disaster-readiness schedule. The stored choice is kept and applies again once the schedule is a standard interval.

For an environment enrolled in Disaster Ready, its DR snapshot interval and selected storage override ordinary snapshot settings while protection is active, including after a normal deployment. The stored interval is not rewritten; the shorter cadence is applied. For a passive (cold) standby, the stored full snapshot period still applies at the DR interval, shortened to the longest period whose chain stays within 720 recovery points (for example, EVERY_7_DAYS at the default 15-minute interval). An active (warm) standby continues its chain with incrementals instead of new full snapshots, so the period does not apply to it. Logical database backup settings remain separate. Turning snapshots off is rejected while Disaster Ready is active for that environment. Activating Disaster Ready clears snapshotBackupDisabled on the app env so the Snapshots tab lists recovery points. Turning Disaster Ready off does not restore a previous opt-out. DR defaults to 15 minutes; its configurable snapshot intervals must divide an hour, or be whole-hour intervals that divide a day. Unsupported intervals are rejected, not rounded. Operator acceptance is not confirmation of a completed snapshot or Disaster Ready status. See Disaster Readiness.

Example​

curl -X PATCH \
-H 'Authorization: YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"appEnvId": "5f7b1b7b7b7b7b7b7b7b7b7b",
"snapshotFrequency": "EVERY_4_HOURS",
"fullSnapshotPeriod": "EVERY_7_DAYS",
"backupSingleReplicaOnly": false,
"recoveryPointsDuringFull": "TWO_LANES",
"interleaveLanePoints": true
}' \
https://api.quave.cloud/api/public/v1/app-env/snapshot-options

Example Response​

{
"snapshotOptions": {
"snapshotFrequency": "EVERY_4_HOURS",
"recoveryPointIntervalLabel": "Every 4 hours",
"fullSnapshotPeriod": "EVERY_7_DAYS",
"fullSnapshotPeriodLabel": "7 days",
"backupSingleReplicaOnly": false,
"snapshotBackupDisabled": false,
"recoveryPointsDuringFull": "TWO_LANES",
"recoveryPointsDuringFullLabel": "On: two staggered chains",
"chainLanes": 2,
"interleaveLanePoints": true,
"recoveryPointFrequency": "A recovery point every 2 hours outside a full (lanes alternate); every 2 hours on one lane while the other uploads its full."
},
"applyResult": {
"applied": true
}
}

The backup overview and workspace responses expose the same snapshotOptions object without returning the derived raw schedule or incremental count.

In the backup overview, inventory.databaseBackupCount is the number of logical database dump files stored for the environment, not only the newest one. In backup storage usage, database.objectCount and database.bytes cover every stored object under logical backups, including the backup encryption public key; database.backupFileCount counts only the dump files.

Sizes are compressed. Backups and snapshots are compressed before upload, so every stored size is usually much smaller than the data on the volume or database; restoring brings back the full data. This covers bytes in backup storage usage (database, volume and total) and in the account backup overview (usage, usageByType), each recovery-point snapshot's entries[].sizeBytes in GET /api/public/v1/app-env/volume-backups (compressed upload size; volumeCapacityBytes is the volume size), and the size of each file in List Backups. A storage cap (maxSizeGb) counts these stored bytes. The Snapshots tab labels the same numbers as compressed.

List Backups​

Lists the latest encrypted logical database backup files for an app environment. The response contains metadata only and does not include secret decryption material. databaseBackupDisabled distinguishes an intentional logical-backup opt-out from an environment with enabled backups, while backupListingUnavailable reports that historical files could not be listed.

Endpoint: GET /api/public/v1/app-env/backups

Query Parameters​

FieldTypeRequiredDescription
appEnvIdStringEitherThe ID of the app environment.
envNameStringEitherThe CLI environment name, as an alternative ID.

Example​

curl -X GET \
-H 'Authorization: YOUR_TOKEN' \
'https://api.quave.cloud/api/public/v1/app-env/backups?appEnvId=5f7b1b7b7b7b7b7b7b7b7b7b'

Example Response​

{
"appEnvId": "5f7b1b7b7b7b7b7b7b7b7b7b",
"databaseBackupDisabled": false,
"backupListingUnavailable": false,
"backups": [
{
"file": "backup-20260615.tgz.gpg",
"date": "2026-06-15T06:00:00.000Z",
"size": 104857600,
"key": "db/prod/account/app/env/backup-20260615.tgz.gpg"
}
]
}

When logical database backups are intentionally disabled and historical storage cannot be read, the endpoint still returns HTTP 200 with databaseBackupDisabled: true, backupListingUnavailable: true, and an empty backups array. Other listing failures use the normal API error response.

Get Backup Download​

Returns a time-limited backup download URL and the decryption material needed for that backup.

Endpoint: POST /api/public/v1/app-env/backup-download

Security​

  • Requires Secrets Access permission on the account that owns the app environment.
  • When called through MCP, the MCP key must include quave:read:secrets.
  • Environment-token-only authentication cannot decrypt backup secrets.
  • The backupKey must come from the same environment backup list; unrelated object keys are rejected.

Request Body​

FieldTypeRequiredDescription
appEnvIdStringEitherThe ID of the app environment.
envNameStringEitherThe CLI environment name, as an alternative ID.
backupKeyStringYesThe backup object key returned by the list backups endpoint.

Example​

curl -X POST \
-H 'Authorization: YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"appEnvId": "5f7b1b7b7b7b7b7b7b7b7b7b",
"backupKey": "db/prod/account/app/env/backup-20260615.tgz.gpg"
}' \
https://api.quave.cloud/api/public/v1/app-env/backup-download

Example Response​

{
"appEnvId": "5f7b1b7b7b7b7b7b7b7b7b7b",
"backup": {
"file": "backup-20260615.tgz.gpg",
"key": "db/prod/account/app/env/backup-20260615.tgz.gpg"
},
"downloadUrl": "https://example.com/signed-download-url",
"privateKeyPem": "-----BEGIN PGP PRIVATE KEY BLOCK-----...",
"privateKeyFileName": "privateKey-ABC123.pem",
"passphrase": "backup-key-passphrase",
"keyId": "ABC123",
"decryptCommands": [
{
"description": "Install gpg",
"command": "sudo apt install gpg"
},
{
"description": "Import the private key",
"command": "gpg --import 'privateKey-ABC123.pem'"
},
{
"description": "Decrypt the backup file. Enter the returned passphrase when prompted.",
"command": "gpg --decrypt 'backup-20260615.tgz.gpg' > backup.tgz"
},
{
"description": "Extract the backup archive",
"command": "tar -xvzf backup.tgz"
}
]
}

Decrypt the Backup​

  1. Save privateKeyPem to the returned privateKeyFileName.
  2. Download the encrypted backup from downloadUrl.
  3. Run the returned decryptCommands in order.
  4. Use the returned passphrase when GPG prompts for the private key passphrase.

Snapshot validation evidence​

Restore and validation submission require a complete selected snapshot chain and its original encryption key. Key rotation does not select the current key for older snapshots. Missing/ambiguous metadata or keys and mixed-key chains fail before submission; retain historical keys. This preflight is not destination-readability evidence. See snapshot validation failures.

The existing validation-list and snapshot-overview readers return the same customer-safe evidence used by Snapshots, including through MCP. Existing authorization and account/environment isolation remain unchanged. API/MCP identifiers such as list-app-env-backup-validations and the backupId field retain their existing names for compatibility; here they refer to snapshot validation, not logical dump backups.

Validation runs include id, backupId, requested checkLevel, the recorded selected snapshot in upTo, region, recoveryPointAt, testedVolumeRoles, requestedAt, startedAt, completedAt, and lastPolledAt, where available. startedAt and completedAt now represent operator execution timestamps only; legacy request/poll times are not returned as measured execution times. Missing facts are omitted, not backfilled.

Validation requests accept checkLevel integrity or schema (default). query is rejected because snapshot validation does not start the database or run queries yet. Additive evidence fields are checks (known name, type, status, safe detail, measured durationMs when available), restore (phase and per-volume role/progress/file counts; currentFile is the 0-based index of the file being applied and equals totalFiles once every file is applied, and a per-volume error is omitted once the validation phase is Succeeded), cleanup (status and observed confirmedAt), and a safe evidenceRef. Check states include pass, fail, skip, and unknown. Cleanup states include pending, failed, and confirmed; an absent state means not recorded. A terminal validation result is not a cleanup confirmation. Continue refreshing while cleanup is pending or retrying.

Cleanup confirmation covers namespaced temporary resources, not independent proof of physical storage reclamation. Raw messages, filenames, internal resource names, credentials, and signed URLs are not evidence fields. Read the validation lifecycle and limitations before interpreting a successful result; it is not Disaster Ready status.

Create an Environment from a Snapshot​

POST /api/public/v1/app-env/volume-backup-restores creates a separate environment from a volume recovery point. It is available for application environments and managed MongoDB, PostgreSQL and MySQL; other engines (for example Redis) are rejected with a clear error, and so is snapshot validation for them. Supply the source appEnvId (or envName), a backupId returned by the volume-backup list, and target.envName. target.envName must be non-empty after trimming. For application sources, omit target.createNewApp (or set it to false) to use the source App, or set it to true to create a new App in the same account. Database restores always create a new App, even when createNewApp is omitted or false. The new App is named target.appName; when it is omitted, the name defaults to <source app>-restore-<mon><dd>-<hhmm> (request time, UTC), the same pattern the dashboard prefills, and the response includes the chosen appName. A blank target.appName is rejected. Database additional services are not copied into the new App. A database restore runs the exact engine version the snapshot was taken with (for example PostgreSQL 17.6 for a snapshot taken before an upgrade to 18), never the preset default. The restored database keeps what its data was created with: the database name, the admin user and, for MySQL, the lower_case_table_names setting. Its passwords are the new environment's own, like a newly created one; the source's passwords do not carry over. Snapshots taken before November 2026 have no recorded version and use the version the source runs now. Snapshot validation uses the same version; if that version is unknown or no supported version shares its major, the request is rejected before anything is created. Optional target.region selects the destination region (default: the source's region). A database restore needs a region with managed databases (deployDevOpsEnabled in GET /api/public/v1/regions), and an application with a local volume needs a region with volumes (volumeEnabled); any other region is rejected with 400 before anything is created (the dashboard offers only the same regions). target.upTo selects a snapshot in the chain. A chain with continuesFromBackupId in the volume-backup list (a Disaster Readiness active standby continues its chain with incrementals) depends on that earlier chain; restore and validation replay every earlier chain back to the full snapshot, up to 1,000 snapshots per restore. The source environment is never overwritten.

For application environments, the new environment copies the source's current runtime configuration, including environment variables (secrets remain encrypted), startup settings, and security/network settings. Image environments deploy the source environment's current image directly, without a build or CLI code upload. The image and configuration are not historical snapshot metadata: the selected snapshot restores volume data only. A missing source image is rejected before creating the target.

Restores start with one container and autoscaling disabled. Selected resource sizing takes precedence over the source's CPU/memory. Custom hosts, shared NFS claims, preview lifecycle metadata, and previous restore intent are not copied. For a new App destination, deployment/build configuration such as port, health checks, Git repository and registry credential references is copied from the source App. The new App gets its own identity; solution ownership, additional services and lifecycle state are not copied. Same-App destinations continue to share App-level configuration.

Environment-variable values are copied verbatim; source-specific callback URLs, external-service connections, and identifiers are not automatically rewritten. Consider these connections before requesting a restore: image restores start a deployment immediately. CLI-source environments wait for their first CLI upload; Git-source environments start a build from their source branch. Managed databases retain their engine/version and database settings, but the restored environment belongs to a new App.

Snapshot and backup settings of the restored environment​

Optional target.backupSettings chooses how the new environment is protected. The dashboard's "Create environment from recovery point" dialog offers the same two choices, with the same default.

ValueEffect
copy (default when omitted)Copies the source's snapshot frequency, full snapshot period, recovery points during full snapshots, single-replica backup, and volume snapshot and database backup retention (days, size cap, and cleanup on/off). A customer-owned storage credential (your own bucket) is copied too, because the restore stays in the source account.
defaultsUses the platform defaults: a snapshot every 6 hours, a full snapshot every day, 7-day retention, and Quave-managed storage.

Never copied: the snapshot opt-out (the restored environment always takes snapshots), the permission to run cleanup on a customer-owned bucket (grant it again on the new environment), and internal tuning. Any other value is rejected with backupSettings must be one of: copy, defaults. before anything is created. Change the settings later with the snapshot options and retention endpoints.

{
"appEnvId": "SOURCE_APP_ENV_ID",
"backupId": "BACKUP_ID",
"target": {
"envName": "restored-db",
"appName": "Restored database",
"backupSettings": "defaults"
}
}

The accepted response includes the destination appId and appEnvId, region, createdNewApp, the applied backupSettings and, for a new App, its appName. Acceptance starts asynchronous work; check the environment deployment status before using it.

Secret revelation requires the account-level Secrets Access role; Admin alone does not grant it. Existing authentication, resource-access, MFA and API/MCP scope requirements still apply. See User Roles.