Backups
API reference for backing up websites, apps and databases, restoring and downloading backups, backup schedules, and S3 or SFTP backup storage.
A backup is a copy of a website's files, an app's live release or a database dump, written by the server's agent. It stays on the server (in /var/backups/vaultpanel, readable by root only), and can also be copied to an S3-compatible bucket or another server over SFTP. Backups, restores and downloads are agent jobs tied to the backup.
Hosting customers reach /backups and /backup-schedules for what their own account owns (anything else is 404); /backup-storage is for staff. For the workflow, see Backups and Backup storage.
| Method | Path | Description |
|---|---|---|
| GET | /api/v1/backups | List backups |
| POST | /api/v1/backups | Back up now |
| GET | /api/v1/backups/:id | Get a backup |
| DELETE | /api/v1/backups/:id | Delete a backup |
| POST | /api/v1/backups/:id/restore | Restore a backup |
| POST | /api/v1/backups/:id/download | Prepare a download |
| GET | /api/v1/backups/:id/download | Download a backup |
| GET | /api/v1/backup-schedules | List schedules |
| PUT | /api/v1/backup-schedules | Save a schedule |
| DELETE | /api/v1/backup-schedules/:id | Delete a schedule |
| GET | /api/v1/backup-storage | List storage |
| POST | /api/v1/backup-storage | Add storage |
| GET | /api/v1/backup-storage/:id | Get storage |
| PUT | /api/v1/backup-storage/:id | Update storage |
| DELETE | /api/v1/backup-storage/:id | Delete storage |
| POST | /api/v1/backup-storage/:id/test | Check storage |
The backup object
| Field | Type | Description |
|---|---|---|
id, serverId, serverName | string | The backup and its server. |
resource | object | { type, id, name, exists }: website, application or database. exists is false once it was deleted. |
status | string | creating, completed, failed, deleting or missing (the file was removed by hand). |
trigger | string | manual, schedule or pre_restore (the safety copy taken before a restore). |
scheduleId | string or null | The schedule that made it. |
filePath | string or null | Where it is on the server. |
localCopy | boolean | false when it is kept only in its storage. |
storage | object or null | { id, name, key, stored, error } when it is copied to a storage. |
sizeBytes, sha256 | Size and checksum, once completed. | |
jobId | string | The job that made it. |
error | object or null | { code, message } when it failed. |
completedAt, lastRestoredAt | string or null | Timestamps. |
download | object | { ready, until, jobId }: a copy prepared on the panel for downloading. |
createdBy | object or null | { id, email }. |
List backups
/api/v1/backupsReturns backups a page at a time, newest first.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
serverId | string (UUID) | No | Only backups on this server. |
resourceType, resourceId | string | No | Only backups of this website, app or database. |
includeDatabases | boolean | No | With a website or app, also list the backups of the databases linked to it. |
status | string | No | A backup status. |
trigger | string | No | manual, schedule or pre_restore. |
storageId | string (UUID) | No | Only backups copied to this storage. |
search | string | No | Part of the website, app or database name. |
page, pageSize | integer | No | Page from 1; 1 to 100 per page (default 25). |
sort, order | string | No | createdAt (default) or size; desc (default) or asc. |
Example request
curl "https://panel.example.com/api/v1/backups?resourceType=website&resourceId=1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d&includeDatabases=true" \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const { items } = await panel.backups.list({
resourceType: 'website',
resourceId: '1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d',
includeDatabases: true,
});Response 200 OK
{
"success": true,
"data": {
"items": [
{
"id": "f0e1d2c3-…",
"serverId": "9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c",
"serverName": "web-1",
"resource": { "type": "website", "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "name": "example-com", "exists": true },
"status": "completed",
"trigger": "schedule",
"scheduleId": "5a6b7c8d-…",
"filePath": "/var/backups/vaultpanel/site/example-com/f0e1d2c3-….tar.gz",
"localCopy": true,
"storage": null,
"sizeBytes": 48234496,
"sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
"jobId": "…",
"error": null,
"completedAt": "2026-11-10T03:00:41.000Z",
"lastRestoredAt": null,
"download": { "ready": false, "until": null, "jobId": null },
"createdBy": null
}
],
"pagination": { "page": 1, "pageSize": 25, "total": 1, "totalPages": 1 }
},
"message": "OK",
"requestId": "…"
}Back up now
/api/v1/backupsStarts a backup (CREATE_BACKUP). A website backup holds every file in the site's folder; an app backup the live release, shared files, .env and deploy key; a database backup a compressed SQL dump of the whole database.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
resourceType | string | Yes | website, application or database. |
resourceId | string (UUID) | Yes | Its id. |
storageId | string (UUID) or null | No | Also copy the backup to this storage. Default null (on the server only). Not available to hosting customers. |
Example request
curl https://panel.example.com/api/v1/backups \
-X POST \
-H "Authorization: Bearer $VAULTPANEL_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "resourceType": "database", "resourceId": "7e8f9a0b-1c2d-4e3f-8a4b-5c6d7e8f9a0b" }'const { backup, job } = await panel.backups.create({
resourceType: 'database',
resourceId: '7e8f9a0b-1c2d-4e3f-8a4b-5c6d7e8f9a0b',
});
await panel.jobs.wait(job.id);Response 202 Accepted: { backup, job } with the backup in status creating, message Backing up.
Errors
| Status | Code | When |
|---|---|---|
| 403 | FORBIDDEN | A hosting customer asked for a storage. |
| 404 | NOT_FOUND | No such website, app or database, or not yours. |
| 409 | BACKUP_RUNNING | A backup of it is already running (details.jobId). |
| 409 | RESOURCE_NOT_READY | The website, app or database is not ready (still being created, or failed). |
| 409 | STORAGE_NOT_CHECKED | An SFTP storage was never checked, so its host key is unknown. |
| 409 | AGENT_OUTDATED | Copying to storage needs agent 0.13.0 or newer. |
| 422 | VALIDATION_ERROR | The storage no longer exists, or a field is invalid. |
Get a backup
/api/v1/backups/:idReturns the backup with its last 20 restores: { id, backupId, jobId, safetyBackupId, status, error, requestedBy, createdAt, finishedAt }, status being running, succeeded or failed.
Example request
curl https://panel.example.com/api/v1/backups/f0e1d2c3-b4a5-4968-8776-5a4b3c2d1e0f \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const backup = await panel.backups.get(backupId);Response 200 OK: the backup object with restores.
Delete a backup
/api/v1/backups/:idDeletes a completed backup's file on the server, and its copy in storage, with a DELETE_BACKUP job. Failed and missing backups have no file and are removed at once (job is null).
Example request
curl https://panel.example.com/api/v1/backups/f0e1d2c3-b4a5-4968-8776-5a4b3c2d1e0f \
-X DELETE \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const { job } = await panel.backups.remove(backupId);Response 202 Accepted: { job }, message Deleting the backup.
Errors
| Status | Code | When |
|---|---|---|
| 404 | NOT_FOUND | No backup with this id. |
| 409 | BACKUP_BUSY | The backup is still being written, deleted or restored. |
Restore a backup
/api/v1/backups/:id/restorePuts a completed backup back in place of the current files or data (RESTORE_BACKUP). By default the current state is backed up first, so the restore can be undone.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
safetyBackup | boolean | No | Back up the current state first. Default true. |
Example request
curl https://panel.example.com/api/v1/backups/f0e1d2c3-b4a5-4968-8776-5a4b3c2d1e0f/restore \
-X POST \
-H "Authorization: Bearer $VAULTPANEL_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "safetyBackup": true }'const { restore, job } = await panel.backups.restore(backupId, { safetyBackup: true });
await panel.jobs.wait(job.id);Response 202 Accepted
{
"success": true,
"data": {
"restore": {
"id": "2b3c4d5e-…",
"backupId": "f0e1d2c3-b4a5-4968-8776-5a4b3c2d1e0f",
"jobId": "…",
"safetyBackupId": "6c7d8e9f-…",
"status": "running",
"error": null,
"requestedBy": null,
"createdAt": "2026-11-10T11:00:00.000Z",
"finishedAt": null
},
"job": { "id": "…", "type": "RESTORE_BACKUP", "status": "queued" }
},
"message": "Restoring",
"requestId": "…"
}Errors
| Status | Code | When |
|---|---|---|
| 404 | NOT_FOUND | No backup with this id. |
| 409 | BACKUP_NOT_RESTORABLE | The backup is not completed. |
| 409 | RESOURCE_DELETED | The website, app or database was deleted; download the backup instead. |
| 409 | RESOURCE_NOT_READY | The website, app or database is not ready. |
| 409 | RESTORE_RUNNING | A restore of the same website, app or database is running. |
Prepare a download
/api/v1/backups/:id/downloadDownloads go through the panel: this copies the backup from the server to the panel (UPLOAD_BACKUP), where it is kept for 6 hours. When a copy is already there, it answers 200 with ready: true; otherwise 202 with the job to wait for (or the job already copying it). Backups larger than VAULTPANEL_BACKUP_DOWNLOAD_MAX_MB (10240 MB by default) cannot be downloaded through the panel.
Example request
curl https://panel.example.com/api/v1/backups/f0e1d2c3-b4a5-4968-8776-5a4b3c2d1e0f/download \
-X POST \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const prepared = await panel.request('POST', `/backups/${backupId}/download`);
if (!prepared.ready) await panel.jobs.wait(prepared.job.id);Response 202 Accepted, message Copying the backup to the panel
{ "success": true, "data": { "ready": false, "job": { "id": "…", "type": "UPLOAD_BACKUP", "status": "queued" } }, "message": "Copying the backup to the panel", "requestId": "…" }or 200 OK with { "ready": true, "backup": { … } }, message Ready to download.
Errors
| Status | Code | When |
|---|---|---|
| 409 | BACKUP_NOT_READY | The backup is not completed. |
| 409 | BACKUP_TOO_LARGE | Larger than the panel accepts; the message says where to copy it from instead. |
Download a backup
/api/v1/backups/:id/downloadSends the prepared copy as a file (Cache-Control: no-store), named after the website, app or database and the time: a .tar.gz for websites and apps, .sql.gz for databases. Each download is recorded in the audit log.
Example request
curl -OJ https://panel.example.com/api/v1/backups/f0e1d2c3-b4a5-4968-8776-5a4b3c2d1e0f/download \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"import { writeFile } from 'node:fs/promises';
const res = await fetch(`https://panel.example.com/api/v1/backups/${backupId}/download`, {
headers: { Authorization: `Bearer ${process.env.VAULTPANEL_TOKEN}` },
});
if (!res.ok) throw new Error(`Download failed: ${res.status}`);
await writeFile('backup.tar.gz', Buffer.from(await res.arrayBuffer()));Response 200 OK: the file. Errors use the usual JSON envelope.
Errors
| Status | Code | When |
|---|---|---|
| 409 | DOWNLOAD_NOT_READY | No prepared copy, or it expired: prepare the download again. |
List schedules
/api/v1/backup-schedulesReturns backup schedules a page at a time, next to run first. Each website, app or database has at most one.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
serverId | string (UUID) | No | Only schedules on this server. |
resourceType, resourceId | string | No | The schedule of this website, app or database. |
includeDatabases | boolean | No | With a website or app, also the schedules of its linked databases. |
page, pageSize | integer | No | Page from 1; 1 to 100 per page (default 25). |
sort, order | string | No | nextRunAt (default) or createdAt; asc (default) or desc. |
Example request
curl https://panel.example.com/api/v1/backup-schedules \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const { items } = await panel.backups.schedules.list();Response 200 OK
{
"success": true,
"data": {
"items": [
{
"id": "5a6b7c8d-…",
"serverId": "9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c",
"serverName": "web-1",
"resource": { "type": "website", "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "name": "example-com" },
"schedule": "0 3 * * *",
"description": "Every day at 03:00",
"timezone": "Europe/Berlin",
"keepCount": 7,
"storage": null,
"lastStorageError": null,
"enabled": true,
"nextRunAt": "2026-11-11T02:00:00.000Z",
"lastRunAt": "2026-11-10T02:00:00.000Z",
"lastBackupId": "f0e1d2c3-…",
"lastBackupStatus": "completed",
"createdAt": "2026-10-20T09:00:00.000Z",
"updatedAt": "2026-10-20T09:00:00.000Z"
}
],
"pagination": { "page": 1, "pageSize": 25, "total": 1, "totalPages": 1 }
},
"message": "OK",
"requestId": "…"
}Save a schedule
/api/v1/backup-schedulesCreates the schedule of a website, app or database, or replaces it. After each scheduled backup, the oldest scheduled backups beyond keepCount are deleted.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
resourceType | string | Yes | website, application or database. |
resourceId | string (UUID) | Yes | Its id. |
schedule | string | Yes | A five-field cron expression, such as 0 3 * * *. |
timezone | string | No | An IANA time zone. Default UTC. |
keepCount | integer | No | 1 to 100 scheduled backups kept. Default 7. |
enabled | boolean | No | Default true. |
storageId | string (UUID) or null | No | Also copy each backup to this storage. Hosting customers keep the destination staff chose. |
Example request
curl https://panel.example.com/api/v1/backup-schedules \
-X PUT \
-H "Authorization: Bearer $VAULTPANEL_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "resourceType": "website", "resourceId": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "schedule": "0 3 * * *", "timezone": "Europe/Berlin", "keepCount": 7 }'const { schedule } = await panel.backups.schedules.save({
resourceType: 'website',
resourceId: '1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d',
schedule: '0 3 * * *',
timezone: 'Europe/Berlin',
keepCount: 7,
});Response 200 OK: { schedule }, message Schedule saved.
Errors
| Status | Code | When |
|---|---|---|
| 404 | NOT_FOUND | No such website, app or database, or not yours. |
| 409 | STORAGE_NOT_CHECKED, AGENT_OUTDATED | The storage cannot be used from this server yet. |
| 422 | VALIDATION_ERROR | An invalid cron expression or time zone, or another invalid field. |
Delete a schedule
/api/v1/backup-schedules/:idDeletes the schedule. Backups it made are kept.
Example request
curl https://panel.example.com/api/v1/backup-schedules/5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d \
-X DELETE \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"await panel.backups.schedules.remove(scheduleId);Response 200 OK: data is null, message Schedule removed.
Errors
| Status | Code | When |
|---|---|---|
| 404 | NOT_FOUND | No schedule with this id. |
The storage object
| Field | Type | Description |
|---|---|---|
id, name | string | The storage. |
type | string | s3 or sftp. |
provider, providerLabel | string | aws, b2, wasabi, r2 or other, or sftp. |
endpoint, region, bucket, prefix, pathStyle, accessKeyId | S3 connection. The secret key is never returned. | |
host, port, username, path | SFTP connection. | |
publicKey | string | SFTP: the key pair the panel made; add this public key to the backup user's authorized_keys. |
hostKeyFingerprint | string or null | SFTP: the backup server's host key, pinned at the first check. |
keepLocal | boolean | Also keep each backup on its server. |
insecure | boolean | The S3 endpoint uses plain http://. |
test | object or null | The last check: { status, message, jobId, testedAt }. |
usage | object | { backups, bytes, schedules } kept in or using it. |
List storage
/api/v1/backup-storageReturns every storage with its usage.
Example request
curl https://panel.example.com/api/v1/backup-storage \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const { items } = await panel.backups.storage.list();Response 200 OK: { items } of storage objects.
Add storage
/api/v1/backup-storageAdds an S3-compatible bucket or an SFTP server. For SFTP, the panel makes a key pair and returns its publicKey; nothing secret is sent.
Request body (S3)
| Field | Type | Required | Description |
|---|---|---|---|
type | string | No | s3 (default). |
name | string | Yes | Up to 100 characters, unique. |
provider | string | No | aws, b2, wasabi, r2 or other (default). |
endpoint | string | Depends | The service's address, such as https://s3.us-east-1.amazonaws.com: no folder or bucket in it. May be blank for providers whose address follows from the region. |
region | string | Yes | Such as us-east-1 (auto for R2). |
bucket | string | Yes | 3 to 63 letters, digits, dots and hyphens. |
prefix | string | No | A folder inside the bucket. Default vaultpanel. |
pathStyle | boolean | No | Path-style addressing (MinIO, R2). Default false. |
accessKeyId | string | Yes | The access key ID. |
secretAccessKey | string | Yes | The secret key. |
keepLocal | boolean | No | Also keep each backup on its server. Default false. |
Request body (SFTP)
| Field | Type | Required | Description |
|---|---|---|---|
type | string | Yes | sftp. |
name | string | Yes | Up to 100 characters, unique. |
host | string | Yes | Host name or IP address. |
port | integer | No | Default 22. |
username | string | Yes | A user made for backups on that server, not root. |
path | string | No | A folder in the user's home, or an absolute one; created when needed. Default vaultpanel-backups. |
keepLocal | boolean | No | Also keep each backup on its server. Default false. |
Example request
curl https://panel.example.com/api/v1/backup-storage \
-X POST \
-H "Authorization: Bearer $VAULTPANEL_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"type": "s3",
"name": "Backblaze",
"provider": "b2",
"region": "us-west-004",
"bucket": "example-backups",
"accessKeyId": "'"$B2_KEY_ID"'",
"secretAccessKey": "'"$B2_APPLICATION_KEY"'"
}'const { storage } = await panel.backups.storage.create({
type: 'sftp',
name: 'Backup server',
host: 'backup.example.com',
username: 'backups',
});
console.log(storage.publicKey); // add to ~backups/.ssh/authorized_keysResponse 201 Created: { storage }, message Storage added.
Errors
| Status | Code | When |
|---|---|---|
| 422 | VALIDATION_ERROR | A missing secret key or endpoint, a name another storage has, or another invalid field. |
Get storage
/api/v1/backup-storage/:idReturns { storage } with its usage.
Example request
curl https://panel.example.com/api/v1/backup-storage/0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"const { storage } = await panel.backups.storage.get(storageId);Response 200 OK: { storage }.
Update storage
/api/v1/backup-storage/:idSaves the storage with the same fields as Add storage. type cannot change, and a blank secretAccessKey keeps the saved one. For SFTP, trustNewHostKey: true forgets the pinned host key so the next check trusts the new one; changing the host or port does the same. A changed connection is unchecked until the next check.
Example request
curl https://panel.example.com/api/v1/backup-storage/0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f \
-X PUT \
-H "Authorization: Bearer $VAULTPANEL_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "type": "sftp", "name": "Backup server", "host": "backup2.example.com", "username": "backups" }'await panel.backups.storage.update(storageId, {
type: 'sftp',
name: 'Backup server',
host: 'backup2.example.com',
username: 'backups',
});Response 200 OK: { storage }, message Storage saved.
Errors
| Status | Code | When |
|---|---|---|
| 404 | NOT_FOUND | No storage with this id. |
| 422 | VALIDATION_ERROR | The type changed, a name another storage has, or another invalid field. |
Delete storage
/api/v1/backup-storage/:idDeletes the storage. Refused while backups are kept there or schedules use it.
Example request
curl https://panel.example.com/api/v1/backup-storage/0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f \
-X DELETE \
-H "Authorization: Bearer $VAULTPANEL_TOKEN"await panel.backups.storage.remove(storageId);Response 200 OK: data is null, message Storage removed.
Errors
| Status | Code | When |
|---|---|---|
| 404 | NOT_FOUND | No storage with this id. |
| 409 | STORAGE_IN_USE | Backups are kept there or schedules use it (details has backups, bytes and schedules). |
Check storage
/api/v1/backup-storage/:id/testQueues a TEST_BACKUP_STORAGE job: the server writes a small test file to the storage and reads it back. For SFTP, the first check pins the backup server's host key. The result is saved as the storage's test.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
serverId | string (UUID) | Yes | The server to check from. Needs agent 0.13.0 or newer. |
Example request
curl https://panel.example.com/api/v1/backup-storage/0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f/test \
-X POST \
-H "Authorization: Bearer $VAULTPANEL_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "serverId": "9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c" }'const { job } = await panel.backups.storage.test(storageId, { serverId });
await panel.jobs.wait(job.id);Response 202 Accepted: { job }, message Checking the storage.
Errors
| Status | Code | When |
|---|---|---|
| 404 | NOT_FOUND | No storage with this id. |
| 409 | AGENT_OUTDATED | The server's agent is older than 0.13.0. |
| 422 | VALIDATION_ERROR | The server does not exist. |