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 database backup files for an app environment. The response contains metadata only and does not include secret decryption material.

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",
  "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"
    }
  ]
}

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.