API Reference

Backups

API reference for backing up websites, apps and databases, restoring and downloading backups, backup schedules, and S3 or SFTP backup storage.

Last updated

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.

MethodPathDescription
GET/api/v1/backupsList backups
POST/api/v1/backupsBack up now
GET/api/v1/backups/:idGet a backup
DELETE/api/v1/backups/:idDelete a backup
POST/api/v1/backups/:id/restoreRestore a backup
POST/api/v1/backups/:id/downloadPrepare a download
GET/api/v1/backups/:id/downloadDownload a backup
GET/api/v1/backup-schedulesList schedules
PUT/api/v1/backup-schedulesSave a schedule
DELETE/api/v1/backup-schedules/:idDelete a schedule
GET/api/v1/backup-storageList storage
POST/api/v1/backup-storageAdd storage
GET/api/v1/backup-storage/:idGet storage
PUT/api/v1/backup-storage/:idUpdate storage
DELETE/api/v1/backup-storage/:idDelete storage
POST/api/v1/backup-storage/:id/testCheck storage

The backup object

FieldTypeDescription
id, serverId, serverNamestringThe backup and its server.
resourceobject{ type, id, name, exists }: website, application or database. exists is false once it was deleted.
statusstringcreating, completed, failed, deleting or missing (the file was removed by hand).
triggerstringmanual, schedule or pre_restore (the safety copy taken before a restore).
scheduleIdstring or nullThe schedule that made it.
filePathstring or nullWhere it is on the server.
localCopybooleanfalse when it is kept only in its storage.
storageobject or null{ id, name, key, stored, error } when it is copied to a storage.
sizeBytes, sha256Size and checksum, once completed.
jobIdstringThe job that made it.
errorobject or null{ code, message } when it failed.
completedAt, lastRestoredAtstring or nullTimestamps.
downloadobject{ ready, until, jobId }: a copy prepared on the panel for downloading.
createdByobject or null{ id, email }.

List backups

GET/api/v1/backups
Auth
Session cookie (+ CSRF token) or API token
Permission
backups.read
Token scope
read

Returns backups a page at a time, newest first.

Query parameters

NameTypeRequiredDescription
serverIdstring (UUID)NoOnly backups on this server.
resourceType, resourceIdstringNoOnly backups of this website, app or database.
includeDatabasesbooleanNoWith a website or app, also list the backups of the databases linked to it.
statusstringNoA backup status.
triggerstringNomanual, schedule or pre_restore.
storageIdstring (UUID)NoOnly backups copied to this storage.
searchstringNoPart of the website, app or database name.
page, pageSizeintegerNoPage from 1; 1 to 100 per page (default 25).
sort, orderstringNocreatedAt (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

POST/api/v1/backups
Auth
Session cookie (+ CSRF token) or API token
Permission
backups.create
Token scope
manage

Starts 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

FieldTypeRequiredDescription
resourceTypestringYeswebsite, application or database.
resourceIdstring (UUID)YesIts id.
storageIdstring (UUID) or nullNoAlso 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

StatusCodeWhen
403FORBIDDENA hosting customer asked for a storage.
404NOT_FOUNDNo such website, app or database, or not yours.
409BACKUP_RUNNINGA backup of it is already running (details.jobId).
409RESOURCE_NOT_READYThe website, app or database is not ready (still being created, or failed).
409STORAGE_NOT_CHECKEDAn SFTP storage was never checked, so its host key is unknown.
409AGENT_OUTDATEDCopying to storage needs agent 0.13.0 or newer.
422VALIDATION_ERRORThe storage no longer exists, or a field is invalid.

Get a backup

GET/api/v1/backups/:id
Auth
Session cookie (+ CSRF token) or API token
Permission
backups.read
Token scope
read

Returns 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

DELETE/api/v1/backups/:id
Auth
Session cookie (+ CSRF token) or API token
Permission
backups.manage
Token scope
manage

Deletes 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

StatusCodeWhen
404NOT_FOUNDNo backup with this id.
409BACKUP_BUSYThe backup is still being written, deleted or restored.

Restore a backup

POST/api/v1/backups/:id/restore
Auth
Session cookie (+ CSRF token) or API token
Permission
backups.manage
Token scope
manage

Puts 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

FieldTypeRequiredDescription
safetyBackupbooleanNoBack 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

StatusCodeWhen
404NOT_FOUNDNo backup with this id.
409BACKUP_NOT_RESTORABLEThe backup is not completed.
409RESOURCE_DELETEDThe website, app or database was deleted; download the backup instead.
409RESOURCE_NOT_READYThe website, app or database is not ready.
409RESTORE_RUNNINGA restore of the same website, app or database is running.

Prepare a download

POST/api/v1/backups/:id/download
Auth
Session cookie (+ CSRF token) or API token
Permission
backups.manage
Token scope
manage

Downloads 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

StatusCodeWhen
409BACKUP_NOT_READYThe backup is not completed.
409BACKUP_TOO_LARGELarger than the panel accepts; the message says where to copy it from instead.

Download a backup

GET/api/v1/backups/:id/download
Auth
Session cookie (+ CSRF token) or API token
Permission
backups.manage
Token scope
manage

Sends 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

StatusCodeWhen
409DOWNLOAD_NOT_READYNo prepared copy, or it expired: prepare the download again.

List schedules

GET/api/v1/backup-schedules
Auth
Session cookie (+ CSRF token) or API token
Permission
backups.read
Token scope
read

Returns backup schedules a page at a time, next to run first. Each website, app or database has at most one.

Query parameters

NameTypeRequiredDescription
serverIdstring (UUID)NoOnly schedules on this server.
resourceType, resourceIdstringNoThe schedule of this website, app or database.
includeDatabasesbooleanNoWith a website or app, also the schedules of its linked databases.
page, pageSizeintegerNoPage from 1; 1 to 100 per page (default 25).
sort, orderstringNonextRunAt (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

PUT/api/v1/backup-schedules
Auth
Session cookie (+ CSRF token) or API token
Permission
backups.manage
Token scope
manage

Creates 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

FieldTypeRequiredDescription
resourceTypestringYeswebsite, application or database.
resourceIdstring (UUID)YesIts id.
schedulestringYesA five-field cron expression, such as 0 3 * * *.
timezonestringNoAn IANA time zone. Default UTC.
keepCountintegerNo1 to 100 scheduled backups kept. Default 7.
enabledbooleanNoDefault true.
storageIdstring (UUID) or nullNoAlso 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

StatusCodeWhen
404NOT_FOUNDNo such website, app or database, or not yours.
409STORAGE_NOT_CHECKED, AGENT_OUTDATEDThe storage cannot be used from this server yet.
422VALIDATION_ERRORAn invalid cron expression or time zone, or another invalid field.

Delete a schedule

DELETE/api/v1/backup-schedules/:id
Auth
Session cookie (+ CSRF token) or API token
Permission
backups.manage
Token scope
manage

Deletes 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

StatusCodeWhen
404NOT_FOUNDNo schedule with this id.

The storage object

FieldTypeDescription
id, namestringThe storage.
typestrings3 or sftp.
provider, providerLabelstringaws, b2, wasabi, r2 or other, or sftp.
endpoint, region, bucket, prefix, pathStyle, accessKeyIdS3 connection. The secret key is never returned.
host, port, username, pathSFTP connection.
publicKeystringSFTP: the key pair the panel made; add this public key to the backup user's authorized_keys.
hostKeyFingerprintstring or nullSFTP: the backup server's host key, pinned at the first check.
keepLocalbooleanAlso keep each backup on its server.
insecurebooleanThe S3 endpoint uses plain http://.
testobject or nullThe last check: { status, message, jobId, testedAt }.
usageobject{ backups, bytes, schedules } kept in or using it.

List storage

GET/api/v1/backup-storage
Auth
Session cookie (+ CSRF token) or API token
Permission
backups.read
Token scope
read

Returns 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

POST/api/v1/backup-storage
Auth
Session cookie (+ CSRF token) or API token
Permission
settings.manage
Token scope
full

Adds 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)

FieldTypeRequiredDescription
typestringNos3 (default).
namestringYesUp to 100 characters, unique.
providerstringNoaws, b2, wasabi, r2 or other (default).
endpointstringDependsThe 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.
regionstringYesSuch as us-east-1 (auto for R2).
bucketstringYes3 to 63 letters, digits, dots and hyphens.
prefixstringNoA folder inside the bucket. Default vaultpanel.
pathStylebooleanNoPath-style addressing (MinIO, R2). Default false.
accessKeyIdstringYesThe access key ID.
secretAccessKeystringYesThe secret key.
keepLocalbooleanNoAlso keep each backup on its server. Default false.

Request body (SFTP)

FieldTypeRequiredDescription
typestringYessftp.
namestringYesUp to 100 characters, unique.
hoststringYesHost name or IP address.
portintegerNoDefault 22.
usernamestringYesA user made for backups on that server, not root.
pathstringNoA folder in the user's home, or an absolute one; created when needed. Default vaultpanel-backups.
keepLocalbooleanNoAlso 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_keys

Response 201 Created: { storage }, message Storage added.

Errors

StatusCodeWhen
422VALIDATION_ERRORA missing secret key or endpoint, a name another storage has, or another invalid field.

Get storage

GET/api/v1/backup-storage/:id
Auth
Session cookie (+ CSRF token) or API token
Permission
backups.read
Token scope
read

Returns { 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

PUT/api/v1/backup-storage/:id
Auth
Session cookie (+ CSRF token) or API token
Permission
settings.manage
Token scope
full

Saves 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

StatusCodeWhen
404NOT_FOUNDNo storage with this id.
422VALIDATION_ERRORThe type changed, a name another storage has, or another invalid field.

Delete storage

DELETE/api/v1/backup-storage/:id
Auth
Session cookie (+ CSRF token) or API token
Permission
settings.manage
Token scope
full

Deletes 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

StatusCodeWhen
404NOT_FOUNDNo storage with this id.
409STORAGE_IN_USEBackups are kept there or schedules use it (details has backups, bytes and schedules).

Check storage

POST/api/v1/backup-storage/:id/test
Auth
Session cookie (+ CSRF token) or API token
Permission
settings.manage
Token scope
full

Queues 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

FieldTypeRequiredDescription
serverIdstring (UUID)YesThe 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

StatusCodeWhen
404NOT_FOUNDNo storage with this id.
409AGENT_OUTDATEDThe server's agent is older than 0.13.0.
422VALIDATION_ERRORThe server does not exist.