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.

Update Snapshot Options

Updates the same customer-friendly recovery-point interval and replica coverage shown in the Snapshots tab. Quave ONE converts the selected interval to the exact low-level configuration sent to the Go API.

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.
backupSingleReplicaOnly	Boolean	At least one option	true backs up one database replica; false backs up every replica.

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

Example

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

Example Response

{
  "snapshotOptions": {
    "snapshotFrequency": "EVERY_4_HOURS",
    "recoveryPointIntervalLabel": "Every 4 hours",
    "backupSingleReplicaOnly": 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 admin 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

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.

Additive evidence fields are checks (known name, type, status, safe detail, measured durationMs when available), restore (phase and per-volume role/progress/file counts), 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.