Restore the database from a backup

POST /v1/infra/servers/:id/db/restore

Replaces the application's SQLite file with the contents of a completed database backup. The restore runs in the background, and before the replacement the platform saves a protective backup of the current file.

Parameters

Request fields (body)

The body accepts no other fields and is limited to 4 KiB.

Examples

curl — personal key

curl -X POST "https://vibecode.bitrix24.com/v1/infra/servers/APP_ID/db/restore" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"backupId":"BACKUP_ID"}'

curl — OAuth application

curl -X POST "https://vibecode.bitrix24.com/v1/infra/servers/APP_ID/db/restore" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"backupId":"BACKUP_ID"}'

JavaScript — personal key

const res = await fetch(
  `https://vibecode.bitrix24.com/v1/infra/servers/${appId}/db/restore`,
  {
    method: 'POST',
    headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json' },
    body: JSON.stringify({ backupId }),
  }
)
const { success, data, error } = await res.json()
if (!success) throw new Error(`${error.code}: ${error.message}`)
// Restore progress is in data.restore of the GET /db/backups response with the same restoreId
console.log('Restore accepted:', data.restoreId)

JavaScript — OAuth application

const res = await fetch(
  `https://vibecode.bitrix24.com/v1/infra/servers/${appId}/db/restore`,
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ backupId }),
  }
)
const { success, data, error } = await res.json()
if (!success) throw new Error(`${error.code}: ${error.message}`)

Response fields

The HTTP status of a successful response is 202 Accepted: the restore has been queued, and the database has not been replaced yet.

Response example

{
  "success": true,
  "data": {
    "restoreId": "cm2r7x4k10003qv8n5d2b6w1z",
    "backupId": "9e4d2c1b-6a3f-4b8e-a7d5-0c1f2e3d4b5a",
    "targetAppId": "5c0e8f2a-3d1b-4a7e-9f60-2b8c4d1e7a93",
    "status": "QUEUED"
  }
}

Error response example

404 — there is no backup with this backupId:

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Server not found"
  }
}

Errors

Full list of common API errors — Errors.

Known specifics

Restore progress. A 202 response means only that the request was accepted. Read the state in data.restore of the GET /db/backups response, matching restoreId. On a test application, the restore took 12 minutes and went through the phases in order: VALIDATE, PREPARE, PRE_CHANGE, STAGE, STOPPING, SWAPPING, VERIFY, STARTING, CLEANUP. After completion, the database data matched the backup. The restore stays in status QUEUED while another restore is running on the platform or a backup or database write is in progress on the same host.

The database is busy until the restore ends. Until the restore completes, writes to this application's database and new backups return 409 APP_DB_BUSY. Reads also get 409 APP_DB_BUSY: on a live call, a read right after the restore started returned this response, and from the STOPPING phase reads are blocked until the restore ends.

Application restart. A running application is stopped in the STOPPING phase and started again in the STARTING phase. An application that was stopped before the restore stays stopped.

Protective backup before the replacement. In the PRE_CHANGE phase, the platform saves the current file as a backup with triggerType equal to PRE_CHANGE — it is visible in the backup list. To undo the restore, restore the database from this backup. If the protective backup could not be created, the restore ends with status FAILED and the file is not replaced. If the file specified by file does not exist yet, no protective backup is created.

Failure during the replacement. A failure in the VALIDATE, PREPARE or PRE_CHANGE phase does not touch the file. A failure in the phases from STAGE to VERIFY returns the original file through the ROLLBACK phase. In both cases, the restore ends with status FAILED and errorCode equal to APP_DB_RESTORE_FAILED. A failure in the STARTING phase or three failed ROLLBACK attempts move the restore to the RECOVERY_REQUIRED phase with status RUNNING without an automatic rollback: from the STARTING phase the application is already running on the restored database. Such a restore waits for support to intervene, and the application's database stays busy until then.

Database access conditions and backup retention rules — When the database is available and Backups and retention.

See also

• List database backups
• Create a database backup
• Protective backups before writes
• Application database