## Получить сведения о базе

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

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

Условия доступа к базе и лимиты запросов — [Когда база доступна](/docs/infra/database#когда-база-доступна) и [Лимиты](/docs/infra/database#лимиты).

## Параметры

| Параметр | Тип | Обяз. | Описание |
|----------|-----|:-----:|----------|
| `id` (path) | string (UUID) | да | ID приложения с `kind` равным `GALAXY_APP`. Список: [`GET /v1/infra/servers`](/docs/infra/servers/list) |
| `file` (query) | string | нет | Непустая строка до 1024 байт в UTF-8. Параметр игнорируется: список файлов, `defaultFile`, `defaultFileExists` и `lastBackup` от него не зависят. Файл по умолчанию берётся из `VIBE_DB_PATH` контейнера, иначе `app.db` |

Других параметров строки запроса эндпоинт не принимает: неизвестный параметр даёт `400 VALIDATION_ERROR`.

## Примеры

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

```bash
curl "https://vibecode.bitrix24.tech/v1/infra/servers/APP_ID/db" \
  -H "X-Api-Key: YOUR_API_KEY"
```

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

```bash
curl "https://vibecode.bitrix24.tech/v1/infra/servers/APP_ID/db" \
  -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`,
  { headers: { 'X-Api-Key': 'YOUR_API_KEY' } }
)
const { success, data, error } = await res.json()
if (!success) throw new Error(error.code)
if (!data.defaultFileExists) console.log('Приложение ещё не создало базу')
console.log(data.defaultFile, data.files)
```

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

```javascript
const res = await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${appId}/db`,
  {
    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)
console.log(data.defaultFile, data.files)
```

## Поля ответа

| Поле | Тип | Описание |
|------|-----|----------|
| `success` | boolean | `true` при успешном ответе |
| `data.files` | array | Найденные SQLite-файлы, по алфавиту. Пустой массив, если тома нет или в нём нет баз |
| `data.files[].file` | string | Путь к файлу относительно `/data`. Это значение передаётся в параметр `file` других эндпоинтов раздела |
| `data.files[].sizeBytes` | number | Размер основного файла базы в байтах, без файлов журнала `-wal` и `-shm` |
| `data.defaultFile` | string | Файл по умолчанию: значение `VIBE_DB_PATH` из контейнера приложения без префикса `/data/`, иначе `app.db` |
| `data.defaultFileExists` | boolean | Существует ли файл по умолчанию |
| `data.truncated` | boolean | `true`, если обход тома остановлен до конца: в томе больше 1000 записей, найдено 500 файлов, вложенность каталогов больше 8 уровней или список приблизился к 1 МиБ |
| `data.capabilities.read` | boolean | Чтение базы. Всегда `true` |
| `data.capabilities.write` | boolean | Запись в базу. `false` для ключа в режиме «только чтение» |
| `data.capabilities.backups` | boolean | Работа с копиями. Всегда `true` |
| `data.lastBackup` | object \| null | Последняя копия файла по умолчанию в статусе `COMPLETED`. `null`, если таких копий нет |
| `data.lastBackup.id` | string | ID копии. Передаётся в [`POST /db/restore`](/docs/infra/database/restore) |
| `data.lastBackup.sourceAppId` | string | ID приложения, с которого снята копия |
| `data.lastBackup.platformPaid` | boolean | `true`, если хранение копии оплачивает платформа |
| `data.lastBackup.captureScope` | string | Что скопировано. Всегда `SQLITE` — один файл базы |
| `data.lastBackup.status` | string | Статус копии. Здесь всегда `COMPLETED` |
| `data.lastBackup.triggerType` | string | Причина копии: `MANUAL`, `SCHEDULED`, `PRE_CHANGE`, `PRE_DELETE` |
| `data.lastBackup.file` | string \| null | Путь скопированного файла относительно `/data` |
| `data.lastBackup.sizeBytes` | string \| null | Размер копии в байтах, десятичное число строкой |
| `data.lastBackup.createdAt` | string (ISO 8601) | Когда копия поставлена в очередь |
| `data.lastBackup.completedAt` | string (ISO 8601) \| null | Когда копия готова |
| `data.lastBackup.expiresAt` | string (ISO 8601) \| null | Когда копия будет удалена |
| `data.lastBackup.errorCode` | string \| null | Код ошибки копии. У готовой копии `null` |

Те же поля у каждой копии в [списке копий](/docs/infra/database/backups).

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

```json
{
  "success": true,
  "data": {
    "files": [
      {
        "file": "app.db",
        "sizeBytes": 20480
      }
    ],
    "defaultFile": "app.db",
    "defaultFileExists": true,
    "truncated": false,
    "capabilities": {
      "read": true,
      "write": true,
      "backups": true
    },
    "lastBackup": {
      "id": "3f6d2a91-8b4e-4c17-a5d0-9e1b7c4f2a68",
      "sourceAppId": "7c2b1f08-3a4d-4e91-9b6c-2f5e8a1d0c33",
      "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
    }
  }
}
```

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

503 — на хосте галактики нет служебного образа для чтения базы:

```json
{
  "success": false,
  "error": {
    "code": "APP_DB_TOOL_UNAVAILABLE",
    "message": "Database reading infrastructure is unavailable, retry shortly",
    "details": {
      "retryable": true,
      "retryAfterSeconds": 1
    }
  }
}
```

Если код повторяется, проверьте [статус подготовки хоста](/docs/infra/database/prepare-status) и при необходимости [подготовьте хост](/docs/infra/database/prepare).

## Ошибки

| HTTP | Код | Описание |
|------|-----|----------|
| 400 | `VALIDATION_ERROR` | В строке запроса передан параметр кроме `file` либо `file` пустой или длиннее 1024 байт |
| 400 | `APP_DB_INVALID_FILE` | Переменная `VIBE_DB_PATH` в контейнере приложения указывает за пределы `/data` или содержит некорректный путь |
| 400 | `APP_DB_UNSUPPORTED_PLACEMENT` | Приложение размещено не в Галактике |
| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |
| 401 | `INVALID_API_KEY` | Ключ не опознан |
| 402 | `BILLING_FROZEN` | Хост галактики спит, а баланс заморожен — разбудить хост нельзя |
| 403 | `INFRA_SCOPE_REQUIRED` | У ключа нет скоупа `vibe:infra` |
| 403 | `APP_DB_DISABLED` | Работа с базой не включена для портала |
| 403 | `SERVER_WAKE_BLOCKED` | Хост галактики спит, и пробуждение для него запрещено |
| 404 | `NOT_FOUND` | Приложение не существует, удалено или недоступно этому ключу |
| 409 | `APP_DB_BUSY` | Хост занят другой операцией или не подключился за 10 секунд. Ответ несёт заголовок `Retry-After`. Если хост занят сборкой приложения, `error.details.holder` называет операцию и приложение. Пока хост галактики запускается после сна или создания, `error.details.hostState` равен `waking` |
| 429 | `RATE_LIMITED` | Превышен лимит запросов на чтение для портала — [Лимиты](/docs/infra/database#лимиты). Пауза — в заголовке `Retry-After` |
| 503 | `APP_DB_TOOL_UNAVAILABLE` | Хост не подготовлен к чтению базы или временно недоступен. Ответ несёт заголовок `Retry-After` |
| 503 | `user_self_deletion_pending` | Владелец ключа удаляет свой аккаунт на этом портале |

Полный список общих ошибок API — [Ошибки](/docs/errors).

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

- **В список попадают только базы SQLite.** Файл включается, если начинается с сигнатуры SQLite. Файлы журнала `-wal`, `-shm`, `-journal`, скрытые файлы и каталоги с точкой в начале имени и символьные ссылки пропускаются.

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

- [Получить схему базы](/docs/infra/database/schema)
- [Получить список копий базы](/docs/infra/database/backups)
- [Получить статус подготовки хоста](/docs/infra/database/prepare-status)
- [База данных приложения](/docs/infra/database)