Create a database backup

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

Queues a manual backup of the application's SQLite file. The backup is created in the background; the application keeps running during the backup.

Parameters

Request fields (body)

The body is optional: without a body or with an empty object {}, the default file is backed up. With the Content-Type: application/json header, the body cannot be empty — pass {}. 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/backups" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

curl — OAuth application

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

JavaScript — personal key

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

JavaScript — OAuth application

const res = await fetch(
  `https://vibecode.bitrix24.com/v1/infra/servers/${appId}/db/backups`,
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({}),
  }
)
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 backup has been queued but not created yet.

Response example

{
  "success": true,
  "data": {
    "backupId": "9e4d2c1b-6a3f-4b8e-a7d5-0c1f2e3d4b5a",
    "status": "QUEUED"
  }
}

Error response example

409 — a repeated request right after creating a backup; the previous backup of this application has not completed yet:

{
  "success": false,
  "error": {
    "code": "APP_DB_BUSY",
    "message": "The database is busy with a live write, retry shortly",
    "details": {
      "source": "sqlite",
      "retryable": true,
      "retryAfterSeconds": 1
    }
  }
}

Errors

Full list of common API errors — Errors.

Known specifics

Backup readiness. A 202 response does not mean the backup has been created. Poll GET /db/backups and look for the item with id equal to backupId: the backup is ready when status is COMPLETED, and if it is FAILED, errorCode gives the cause. On a test application with a 937-byte backup, the backup went from QUEUED to COMPLETED in 1 min 40 s.

One backup at a time. Until the application's previous backup completes, retries after details.retryAfterSeconds get the same 409 APP_DB_BUSY. The message text does not name the cause: with details.source equal to sqlite, it refers to a database write even when the database is occupied by an unfinished backup. Instead of retrying frequently, poll the backup list until the backup completes.

Where backups are stored, how long they live and how they are billed — Backups and retention.

See also

• List database backups
• Restore the database from a backup
• Get database information
• Application database