Для AI-агентов: markdown этой страницы — /docs-content/infra/database/backups.md индекс документации — /llms.txt

Получить список копий базы

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

Возвращает копии SQLite-базы приложения от новых к старым и состояние последнего восстановления базы. Список читается из истории платформы, поэтому запрос не будит хост и не обращается к контейнеру.

Параметры

Параметр Тип Обяз. По умолч. Описание
Параметрid (path) Типstring (UUID) Обяз.да По умолч.— ОписаниеID приложения с kind равным GALAXY_APP. Список: GET /v1/infra/servers
Параметрlimit (query) Типnumber Обяз.нет По умолч.50 ОписаниеЧисло копий на странице, от 1 до 100
Параметрcursor (query) Типstring Обяз.нет По умолч.— ОписаниеЗначение data.nextCursor из предыдущего ответа, без изменений. До 1024 символов: латинские буквы, цифры, - и _
ПараметрsourceAppId (query) Типstring Обяз.нет По умолч.значение id ОписаниеID другого приложения того же портала, копии которого нужно показать, в том числе удалённого. Список: GET /v1/infra/servers, ID удалённого приложения — поле sourceAppId его копий. Если у ключа нет доступа к данным этого приложения или такого приложения нет, data.items приходит пустым, а не ошибкой

Пагинация. Копии упорядочены по createdAt, при равенстве — по id, оба по убыванию. Номера страницы нет: следующую страницу запрашивайте с cursor, равным data.nextCursor. Значение null в data.nextCursor означает конец списка. Курсор действует только для того же приложения и того же sourceAppId. Общего числа копий ответ не содержит.

Примеры

curl — личный ключ

Terminal 
curl "https://vibecode.bitrix24.tech/v1/infra/servers/APP_ID/db/backups?limit=3" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth-приложение

Terminal 
curl "https://vibecode.bitrix24.tech/v1/infra/servers/APP_ID/db/backups?limit=3" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — личный ключ

javascript 
const res = await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${appId}/db/backups?limit=3`,
  { headers: { 'X-Api-Key': 'YOUR_API_KEY' } }
)
const { success, data, error } = await res.json()
if (!success) throw new Error(`${error.code}: ${error.message}`)

for (const copy of data.items) {
  console.log(copy.id, copy.triggerType, copy.status, copy.expiresAt)
}
if (data.restore) {
  console.log('Восстановление:', data.restore.status, data.restore.phase)
}
// Следующая страница: data.nextCursor в параметр cursor без изменений

JavaScript — OAuth-приложение

javascript 
const res = await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${appId}/db/backups?limit=3`,
  {
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
    },
  }
)
const { success, data, error } = await res.json()
if (!success) throw new Error(`${error.code}: ${error.message}`)

Поля ответа

Поле Тип Описание
Полеsuccess Типboolean Описаниеtrue при успехе
Полеdata.items Типarray ОписаниеКопии базы на текущей странице
Полеdata.items[].id Типstring ОписаниеID копии. Передаётся в backupId при восстановлении
Полеdata.items[].sourceAppId Типstring (UUID) ОписаниеID приложения, с базы которого снята копия
Полеdata.items[].platformPaid Типboolean Описаниеtrue — хранение копии оплачивает платформа, false — хранилище портала
Полеdata.items[].captureScope Типstring ОписаниеЧто скопировано. Для копий базы всегда SQLITE
Полеdata.items[].status Типstring ОписаниеQUEUED — копия в очереди, RUNNING — создаётся, COMPLETED — готова, FAILED — не удалась, EXPIRED — срок хранения истёк, FLAGGED — копирование остановлено и ждёт службы поддержки, DELETED — удалена
Полеdata.items[].triggerType Типstring ОписаниеMANUAL — ручная копия, SCHEDULED — ежедневная, PRE_CHANGE — защитная перед изменением базы, PRE_DELETE — перед удалением приложения
Полеdata.items[].file Типstring | null ОписаниеПуть скопированного файла относительно тома /data
Полеdata.items[].sizeBytes Типstring | null ОписаниеРазмер копии в байтах, десятичным числом в строке. null, пока копия не завершена
Полеdata.items[].createdAt Типstring ОписаниеВремя постановки копии в очередь, ISO 8601 в UTC
Полеdata.items[].completedAt Типstring | null ОписаниеВремя завершения копии, ISO 8601 в UTC. null, пока копия не завершена
Полеdata.items[].expiresAt Типstring | null ОписаниеВремя окончания хранения, ISO 8601 в UTC. null, пока копия не завершена
Полеdata.items[].errorCode Типstring | null ОписаниеПричина неудачи у копии в статусе FAILED: APP_DB_BUSY, APP_DB_WAL_CLOSED, APP_DB_BACKUP_TIMEOUT, APP_DB_CORRUPT, APP_DB_TOOL_UNAVAILABLE, APP_DB_BACKUP_INVALID. У причин без публичного кода — null
Полеdata.nextCursor Типstring | null ОписаниеКурсор следующей страницы. null — страниц больше нет
Полеdata.restore Типobject | null ОписаниеВосстановление базы этого приложения: идущее, а если такого нет — последнее. null, если базу приложения не восстанавливали. Не зависит от sourceAppId
Полеdata.restore.restoreId Типstring ОписаниеID восстановления из ответа POST /db/restore
Полеdata.restore.backupId Типstring ОписаниеID копии, из которой восстанавливается база
Полеdata.restore.targetAppId Типstring (UUID) ОписаниеID приложения, базу которого восстанавливают
Полеdata.restore.sourceAppId Типstring (UUID) ОписаниеID приложения, с базы которого снята копия
Полеdata.restore.status Типstring ОписаниеQUEUED — в очереди, RUNNING — выполняется, COMPLETED — база заменена, FAILED — восстановление не удалось
Полеdata.restore.phase Типstring | null ОписаниеШаг восстановления. Рабочий порядок: VALIDATE, PREPARE, PRE_CHANGE, STAGE, STOPPING, SWAPPING, VERIFY, STARTING, CLEANUP. CLEANUP остаётся и после завершения, при COMPLETED и при FAILED. ROLLBACK — возврат исходного файла после сбоя, RECOVERY_REQUIRED — восстановление остановлено и ждёт службы поддержки
Полеdata.restore.errorCode Типstring | null ОписаниеПричина неудачи, например APP_DB_RESTORE_FAILED. null, пока сбоя нет
Полеdata.restore.backupCreatedAt Типstring ОписаниеВремя создания копии-источника, ISO 8601 в UTC
Полеdata.restore.createdAt Типstring ОписаниеВремя приёма запроса на восстановление, ISO 8601 в UTC
Полеdata.restore.completedAt Типstring | null ОписаниеВремя завершения, ISO 8601 в UTC. null, пока восстановление идёт

Пример ответа

Первая страница из трёх копий (?limit=3), восстановлений не было:

JSON 
{
  "success": true,
  "data": {
    "restore": null,
    "items": [
      {
        "id": "9e4d2c1b-6a3f-4b8e-a7d5-0c1f2e3d4b5a",
        "sourceAppId": "5c0e8f2a-3d1b-4a7e-9f60-2b8c4d1e7a93",
        "platformPaid": false,
        "captureScope": "SQLITE",
        "status": "COMPLETED",
        "triggerType": "MANUAL",
        "file": "app.db",
        "sizeBytes": "937",
        "createdAt": "2026-10-20T08:26:17.942Z",
        "completedAt": "2026-10-20T08:28:00.046Z",
        "expiresAt": "2026-10-27T08:28:00.046Z",
        "errorCode": null
      },
      {
        "id": "1f7a3b9c-2e4d-4c6a-8b0e-5d9f7a1c3e2b",
        "sourceAppId": "5c0e8f2a-3d1b-4a7e-9f60-2b8c4d1e7a93",
        "platformPaid": false,
        "captureScope": "SQLITE",
        "status": "COMPLETED",
        "triggerType": "PRE_CHANGE",
        "file": "app.db",
        "sizeBytes": "937",
        "createdAt": "2026-10-20T08:23:15.565Z",
        "completedAt": "2026-10-20T08:25:00.061Z",
        "expiresAt": "2026-10-27T08:25:00.061Z",
        "errorCode": null
      },
      {
        "id": "4b8c6d2e-9f1a-4e3b-b5c7-7a2d0e6f8c19",
        "sourceAppId": "5c0e8f2a-3d1b-4a7e-9f60-2b8c4d1e7a93",
        "platformPaid": false,
        "captureScope": "SQLITE",
        "status": "COMPLETED",
        "triggerType": "PRE_CHANGE",
        "file": "app.db",
        "sizeBytes": "937",
        "createdAt": "2026-10-20T08:21:47.863Z",
        "completedAt": "2026-10-20T08:23:00.087Z",
        "expiresAt": "2026-10-27T08:23:00.087Z",
        "errorCode": null
      }
    ],
    "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2In0"
  }
}

После завершения восстановления (?limit=2). Первая в списке — защитная копия, которую платформа сохранила перед заменой файла:

JSON 
{
  "success": true,
  "data": {
    "restore": {
      "restoreId": "cm2r7x4k10003qv8n5d2b6w1z",
      "backupId": "9e4d2c1b-6a3f-4b8e-a7d5-0c1f2e3d4b5a",
      "targetAppId": "5c0e8f2a-3d1b-4a7e-9f60-2b8c4d1e7a93",
      "sourceAppId": "5c0e8f2a-3d1b-4a7e-9f60-2b8c4d1e7a93",
      "status": "COMPLETED",
      "phase": "CLEANUP",
      "errorCode": null,
      "backupCreatedAt": "2026-10-20T08:26:17.942Z",
      "createdAt": "2026-10-20T08:28:12.755Z",
      "completedAt": "2026-10-20T08:40:30.029Z"
    },
    "items": [
      {
        "id": "7d3e1a5b-8c2f-4d9a-9e6b-3f0a4c7d2e81",
        "sourceAppId": "5c0e8f2a-3d1b-4a7e-9f60-2b8c4d1e7a93",
        "platformPaid": false,
        "captureScope": "SQLITE",
        "status": "COMPLETED",
        "triggerType": "PRE_CHANGE",
        "file": "app.db",
        "sizeBytes": "937",
        "createdAt": "2026-10-20T08:30:30.278Z",
        "completedAt": "2026-10-20T08:32:00.080Z",
        "expiresAt": "2026-10-27T08:32:00.080Z",
        "errorCode": null
      },
      {
        "id": "9e4d2c1b-6a3f-4b8e-a7d5-0c1f2e3d4b5a",
        "sourceAppId": "5c0e8f2a-3d1b-4a7e-9f60-2b8c4d1e7a93",
        "platformPaid": false,
        "captureScope": "SQLITE",
        "status": "COMPLETED",
        "triggerType": "MANUAL",
        "file": "app.db",
        "sizeBytes": "937",
        "createdAt": "2026-10-20T08:26:17.942Z",
        "completedAt": "2026-10-20T08:28:00.046Z",
        "expiresAt": "2026-10-27T08:28:00.046Z",
        "errorCode": null
      }
    ],
    "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2In1"
  }
}

Пример ответа при ошибке

400 — курсор изменён или выдан для другого приложения-источника:

JSON 
{
  "success": false,
  "error": {
    "code": "APP_DB_INVALID_FILE",
    "message": "Invalid database file inside /data"
  }
}

Ошибки

HTTP Код Описание
HTTP400 КодAPP_DB_INVALID_FILE ОписаниеЗначение cursor не читается как курсор этого списка: изменено вручную или выдано для другого sourceAppId. Текст message говорит о файле, но в этом методе код относится к курсору. Начните обход заново без cursor
HTTP400 КодVALIDATION_ERROR ОписаниеНеизвестный параметр запроса, limit вне диапазона 1–100, недопустимые символы в cursor или sourceAppId
HTTP400 КодAPP_DB_UNSUPPORTED_PLACEMENT ОписаниеПриложение размещено не в Галактике
HTTP401 КодMISSING_API_KEY ОписаниеНе передан заголовок X-Api-Key
HTTP401 КодINVALID_API_KEY ОписаниеКлюч не опознан
HTTP403 КодINFRA_SCOPE_REQUIRED ОписаниеУ ключа нет скоупа vibe:infra
HTTP403 КодAPP_DB_DISABLED ОписаниеРабота с базой приложения не включена для портала
HTTP404 КодNOT_FOUND ОписаниеПриложения с таким id нет на портале, оно удалено или у ключа нет к нему доступа
HTTP429 КодRATE_LIMITED ОписаниеПревышен лимит запросов на чтение для портала — Лимиты. Пауза — в заголовке Retry-After
HTTP503 КодAPP_DB_TOOL_UNAVAILABLE ОписаниеПлатформа временно не может обслужить базу этого приложения. Повторите запрос позже
HTTP503 Кодuser_self_deletion_pending ОписаниеВладелец ключа запросил удаление своего аккаунта на портале. Доступ вернётся после отмены удаления

Полный список общих ошибок API — Ошибки.

Известные особенности

Ожидание копии и восстановления. Завершение ручной копии и восстановления проверяйте повторным вызовом этого списка: копию — по status элемента с нужным id, восстановление — по data.restore с нужным restoreId. Сколько это занимает — Создать копию базы и Восстановить базу из копии. Каждый опрос расходует лимит запросов на чтение, общий для всех чтений базы портала.

Остановка, которая ждёт поддержки. Копия в статусе FLAGGED и восстановление с фазой RECOVERY_REQUIRED сами не завершатся: восстановление в этом случае остаётся в статусе RUNNING. Повторные опросы ответ не изменят — обратитесь в службу поддержки и назовите id копии или restoreId.

Смотрите также