# Backups

URL: https://docs.vaultpanel.net/api-reference/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](https://docs.vaultpanel.net/guides/backups-and-automation/backups) and [Backup storage](https://docs.vaultpanel.net/guides/backups-and-automation/backup-storage).

| Method | Path | Description |
| --- | --- | --- |
| GET | `/api/v1/backups` | [List backups](https://docs.vaultpanel.net/api-reference/backups#list-backups) |
| POST | `/api/v1/backups` | [Back up now](https://docs.vaultpanel.net/api-reference/backups#back-up-now) |
| GET | `/api/v1/backups/:id` | [Get a backup](https://docs.vaultpanel.net/api-reference/backups#get-a-backup) |
| DELETE | `/api/v1/backups/:id` | [Delete a backup](https://docs.vaultpanel.net/api-reference/backups#delete-a-backup) |
| POST | `/api/v1/backups/:id/restore` | [Restore a backup](https://docs.vaultpanel.net/api-reference/backups#restore-a-backup) |
| POST | `/api/v1/backups/:id/download` | [Prepare a download](https://docs.vaultpanel.net/api-reference/backups#prepare-a-download) |
| GET | `/api/v1/backups/:id/download` | [Download a backup](https://docs.vaultpanel.net/api-reference/backups#download-a-backup) |
| GET | `/api/v1/backup-schedules` | [List schedules](https://docs.vaultpanel.net/api-reference/backups#list-schedules) |
| PUT | `/api/v1/backup-schedules` | [Save a schedule](https://docs.vaultpanel.net/api-reference/backups#save-a-schedule) |
| DELETE | `/api/v1/backup-schedules/:id` | [Delete a schedule](https://docs.vaultpanel.net/api-reference/backups#delete-a-schedule) |
| GET | `/api/v1/backup-storage` | [List storage](https://docs.vaultpanel.net/api-reference/backups#list-storage) |
| POST | `/api/v1/backup-storage` | [Add storage](https://docs.vaultpanel.net/api-reference/backups#add-storage) |
| GET | `/api/v1/backup-storage/:id` | [Get storage](https://docs.vaultpanel.net/api-reference/backups#get-storage) |
| PUT | `/api/v1/backup-storage/:id` | [Update storage](https://docs.vaultpanel.net/api-reference/backups#update-storage) |
| DELETE | `/api/v1/backup-storage/:id` | [Delete storage](https://docs.vaultpanel.net/api-reference/backups#delete-storage) |
| POST | `/api/v1/backup-storage/:id/test` | [Check storage](https://docs.vaultpanel.net/api-reference/backups#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

`GET /api/v1/backups` — Permission: backups.read — Token scope: read

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

```bash
curl "https://panel.example.com/api/v1/backups?resourceType=website&resourceId=1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d&includeDatabases=true" \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const { items } = await panel.backups.list({
  resourceType: 'website',
  resourceId: '1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d',
  includeDatabases: true,
});
```

**Response** `200 OK`

```json
{
  "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` — 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**

| 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**

```bash
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" }'
```

**JavaScript**

```js
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

`GET /api/v1/backups/:id` — 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**

```bash
curl https://panel.example.com/api/v1/backups/f0e1d2c3-b4a5-4968-8776-5a4b3c2d1e0f \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const backup = await panel.backups.get(backupId);
```

**Response** `200 OK`: the [backup object](https://docs.vaultpanel.net/api-reference/backups#the-backup-object) with `restores`.

## Delete a backup

`DELETE /api/v1/backups/:id` — 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**

```bash
curl https://panel.example.com/api/v1/backups/f0e1d2c3-b4a5-4968-8776-5a4b3c2d1e0f \
  -X DELETE \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
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

`POST /api/v1/backups/:id/restore` — 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**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `safetyBackup` | boolean | No | Back up the current state first. Default `true`. |

**Example request**

**cURL**

```bash
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 }'
```

**JavaScript**

```js
const { restore, job } = await panel.backups.restore(backupId, { safetyBackup: true });
await panel.jobs.wait(job.id);
```

**Response** `202 Accepted`

```json
{
  "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

`POST /api/v1/backups/:id/download` — 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**

```bash
curl https://panel.example.com/api/v1/backups/f0e1d2c3-b4a5-4968-8776-5a4b3c2d1e0f/download \
  -X POST \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
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`

```json
{ "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

`GET /api/v1/backups/:id/download` — 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**

```bash
curl -OJ https://panel.example.com/api/v1/backups/f0e1d2c3-b4a5-4968-8776-5a4b3c2d1e0f/download \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
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](https://docs.vaultpanel.net/api-reference/backups#prepare-a-download) again. |

## List schedules

`GET /api/v1/backup-schedules` — 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**

| 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**

```bash
curl https://panel.example.com/api/v1/backup-schedules \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const { items } = await panel.backups.schedules.list();
```

**Response** `200 OK`

```json
{
  "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` — 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**

| 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**

```bash
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 }'
```

**JavaScript**

```js
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

`DELETE /api/v1/backup-schedules/:id` — Permission: backups.manage — Token scope: manage

Deletes the schedule. Backups it made are kept.

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/backup-schedules/5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d \
  -X DELETE \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
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

`GET /api/v1/backup-storage` — Permission: backups.read — Token scope: read

Returns every storage with its `usage`.

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/backup-storage \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const { items } = await panel.backups.storage.list();
```

**Response** `200 OK`: `{ items }` of [storage objects](https://docs.vaultpanel.net/api-reference/backups#the-storage-object).

## Add storage

`POST /api/v1/backup-storage` — 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)**

| 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**

```bash
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"'"
  }'
```

**JavaScript**

```js
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**

| Status | Code | When |
| --- | --- | --- |
| 422 | `VALIDATION_ERROR` | A missing secret key or endpoint, a name another storage has, or another invalid field. |

## Get storage

`GET /api/v1/backup-storage/:id` — Permission: backups.read — Token scope: read

Returns `{ storage }` with its `usage`.

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/backup-storage/0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const { storage } = await panel.backups.storage.get(storageId);
```

**Response** `200 OK`: `{ storage }`.

## Update storage

`PUT /api/v1/backup-storage/:id` — Permission: settings.manage — Token scope: full

Saves the storage with the same fields as [Add storage](https://docs.vaultpanel.net/api-reference/backups#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](https://docs.vaultpanel.net/api-reference/backups#check-storage).

**Example request**

**cURL**

```bash
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" }'
```

**JavaScript**

```js
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

`DELETE /api/v1/backup-storage/:id` — Permission: settings.manage — Token scope: full

Deletes the storage. Refused while backups are kept there or schedules use it.

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/backup-storage/0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f \
  -X DELETE \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
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

`POST /api/v1/backup-storage/:id/test` — 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**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `serverId` | string (UUID) | Yes | The server to check from. Needs agent 0.13.0 or newer. |

**Example request**

**cURL**

```bash
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" }'
```

**JavaScript**

```js
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. |
