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.

Update Snapshot Options

Updates the same customer-friendly recovery-point interval, full snapshot period 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

Field	Type	Required	Description
appEnvId	String	Either	The ID of the app environment.
envName	String	Either	The CLI environment name, as an alternative ID.
snapshotFrequency	Enum	At least one option	EVERY_HOUR, EVERY_2_HOURS, EVERY_4_HOURS, EVERY_6_HOURS, EVERY_8_HOURS, or EVERY_12_HOURS.
fullSnapshotPeriod	Enum	At least one option	How 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.
backupSingleReplicaOnly	Boolean	At least one option	true backs up one database replica; false backs up every replica.
snapshotBackupDisabled	Boolean	At least one option	true stops scheduled volume snapshots and keeps existing recovery points. false turns them back on at the stored interval.

Do not send snapshotSchedule or incrementalCount; 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.

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

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. The stored full snapshot period is used only while the stored interval is at least as frequent as the DR interval; when DR applies its shorter cadence, it also uses its own daily chain. 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
    }' \
    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
  },
  "applyResult": {
    "applied": true
  }
}

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

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

Field	Type	Required	Description
appEnvId	String	Either	The ID of the app environment.
envName	String	Either	The 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

Field	Type	Required	Description
appEnvId	String	Either	The ID of the app environment.
envName	String	Either	The CLI environment name, as an alternative ID.
backupKey	String	Yes	The 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. 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 and supply a non-empty target.appName to create a new App in the same account. Database restores always create a new App and require target.appName, even when createNewApp is omitted or false. Database additional services are not copied into the new App. Optional target.region selects the destination region; target.upTo selects a snapshot in the chain. 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.

The accepted response includes the destination appId and appEnvId, region, and createdNewApp. 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.