Skip to main content
Backup endpoints let you manage bot configuration backups. All endpoints are restricted to API key callers or bot-owner OAuth users.

​
GET /backups/export

Downloads the current bot configuration as a JSON file. Sensitive fields (API keys, tokens) are redacted with a placeholder. Authentication: API key or bot-owner JWT Bearer token required.

​
Response

Returns a JSON file with Content-Disposition: attachment and a timestamped filename.
​
config
object
The current bot configuration with sensitive fields redacted.
​
exportedAt
string
ISO 8601 timestamp of the export.
​
version
integer
Backup schema version.

​
Example

curl -H "x-api-secret: YOUR_SECRET" \
  https://volvox.bot/api/v1/backups/export \
  -o config-backup.json

{
  "config": {
    "ai": { "enabled": true, "model": "claude-3-5-sonnet", "apiKey": "[REDACTED]" }
  },
  "exportedAt": "2026-03-21T10:00:00.000Z",
  "version": 1
}

​
POST /backups/import

Applies configuration from a previously exported JSON payload. Redacted values ([REDACTED] placeholder) are skipped automatically to preserve live secrets. Authentication: API key or bot-owner JWT Bearer token required.

​
Request body

​
config
object
required
The config object to import (from an export payload).
​
exportedAt
string
Optional ISO 8601 export timestamp for provenance.
​
version
integer
Optional backup schema version.

​
Response fields

​
applied
array
List of config paths that were successfully applied.
​
skipped
array
List of config paths that were skipped (for example, redacted values).
​
failed
array
List of objects describing paths that failed to apply.

​
Example

curl -X POST \
  -H "x-api-secret: YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d @config-backup.json \
  https://volvox.bot/api/v1/backups/import

{
  "applied": ["ai.enabled", "ai.model"],
  "skipped": ["ai.apiKey"],
  "failed": []
}

​
GET /backups

Returns metadata for all stored config backups, sorted newest first. Authentication: API key or bot-owner JWT Bearer token required.

​
Response fields

Returns an array of backup metadata objects.
​
id
string
Backup ID (filename without the .json extension).
​
filename
string
Full filename of the backup file.
​
createdAt
string
ISO 8601 creation timestamp.
​
size
integer
File size in bytes.

​
Example

curl -H "x-api-secret: YOUR_SECRET" \
  https://volvox.bot/api/v1/backups

[
  {
    "id": "backup-2026-03-21T10-00-00-000Z",
    "filename": "backup-2026-03-21T10-00-00-000Z.json",
    "createdAt": "2026-03-21T10:00:00.000Z",
    "size": 8192
  }
]

​
POST /backups

Creates an immediate manual backup of the current configuration. Authentication: API key or bot-owner JWT Bearer token required.

​
Response fields

​
id
string
The new backup ID.
​
size
integer
File size in bytes.
​
createdAt
string
ISO 8601 creation timestamp.

​
Example

curl -X POST \
  -H "x-api-secret: YOUR_SECRET" \
  https://volvox.bot/api/v1/backups

{
  "id": "backup-2026-03-21T10-00-00-000Z",
  "size": 8192,
  "createdAt": "2026-03-21T10:00:00.000Z"
}

​
GET /backups/:id/download

Streams a specific backup JSON file for download by its ID. Authentication: API key or bot-owner JWT Bearer token required.

​
Path parameters

​
id
string
required
The backup ID (filename without the .json extension).

​
Response

Returns the backup JSON file with Content-Disposition: attachment.

​
Example

curl -H "x-api-secret: YOUR_SECRET" \
  "https://volvox.bot/api/v1/backups/backup-2026-03-21T10-00-00-000Z/download" \
  -o restore-point.json

​
POST /backups/:id/restore

Restores the live configuration from a stored backup. Redacted sensitive values are skipped to preserve the current live secrets. Authentication: API key or bot-owner JWT Bearer token required.
Restoring a backup will overwrite the current live configuration. Ensure you create a backup of the current state before restoring.

​
Path parameters

​
id
string
required
The backup ID to restore.

​
Response fields

Same shape as POST /backups/import: applied, skipped, and failed arrays.

​
Example

curl -X POST \
  -H "x-api-secret: YOUR_SECRET" \
  "https://volvox.bot/api/v1/backups/backup-2026-03-21T10-00-00-000Z/restore"

{
  "applied": ["ai.enabled", "ai.model", "welcome.enabled"],
  "skipped": ["ai.apiKey"],
  "failed": []
}

​
POST /backups/prune

Deletes backups that exceed the retention policy. Defaults to keeping the last 7 daily and 4 weekly backups. Authentication: API key or bot-owner JWT Bearer token required.

​
Request body

​
daily
integer
Number of daily backups to keep. Default: 7.
​
weekly
integer
Number of weekly backups to keep. Default: 4.

​
Response fields

​
deleted
array
List of backup IDs that were deleted.
​
count
integer
Number of backups deleted.

​
Example

curl -X POST \
  -H "x-api-secret: YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"daily": 5, "weekly": 2}' \
  https://volvox.bot/api/v1/backups/prune

{
  "deleted": ["backup-2026-02-01T10-00-00-000Z", "backup-2026-01-15T10-00-00-000Z"],
  "count": 2
}

Build docs developers (and LLMs) love

Get started for freeTalk to us