For AI agents: markdown of this page — /docs-content-en/infra/database.md documentation index — /llms.txt

Application database

Endpoints for working with the SQLite database of a Galaxy application: reading the schema and rows, SQL queries, row edits, database backups and restoring from a backup. The database lives in the container's persistent /data volume, and the platform works with it without stopping the application.

Scope: vibe:infra

Get database information

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

Returns the SQLite files in the application's data volume, the default file, the capabilities available to the key and the latest completed backup of the default file. Call it before reading the schema and rows to find out which file to open.

Database access conditions and request limits — When the database is available and Limits.

Parameters

Parameter Type Required Description
Parameterid (path) Typestring (UUID) Requiredyes DescriptionID of an application with kind equal to GALAXY_APP. List: GET /v1/infra/servers
Parameterfile (query) Typestring Requiredno DescriptionNon-empty string of at most 1024 UTF-8 bytes. This request ignores it: the file list, defaultFile, defaultFileExists and lastBackup do not depend on it. The default file comes from the container's VIBE_DB_PATH, or app.db when unset

The endpoint accepts no other query string parameters: an unknown parameter returns 400 VALIDATION_ERROR.

Examples

curl — personal key

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

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/infra/servers/APP_ID/db" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const res = await fetch(
  `https://vibecode.bitrix24.com/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('The application has not created a database yet')
console.log(data.defaultFile, data.files)

JavaScript — OAuth application

javascript 
const res = await fetch(
  `https://vibecode.bitrix24.com/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)

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on success
Fielddata.files Typearray DescriptionDiscovered SQLite files, in alphabetical order. An empty array if there is no volume or it contains no databases
Fielddata.files[].file Typestring DescriptionFile path relative to /data. Pass this value in the file parameter of the other endpoints in this section
Fielddata.files[].sizeBytes Typenumber DescriptionSize of the main database file in bytes, excluding the -wal and -shm journal files
Fielddata.defaultFile Typestring DescriptionDefault file: the VIBE_DB_PATH value from the application container without the /data/ prefix, otherwise app.db
Fielddata.defaultFileExists Typeboolean DescriptionWhether the default file exists
Fielddata.truncated Typeboolean Descriptiontrue if the volume scan stopped early: the volume has more than 1000 entries, 500 files were found, directory nesting exceeds 8 levels or the list approached 1 MiB
Fielddata.capabilities.read Typeboolean DescriptionDatabase reads. Always true
Fielddata.capabilities.write Typeboolean DescriptionDatabase writes. false for a read-only key
Fielddata.capabilities.backups Typeboolean DescriptionWorking with backups. Always true
Fielddata.lastBackup Typeobject | null DescriptionLatest backup of the default file with status COMPLETED. null if there are no such backups
Fielddata.lastBackup.id Typestring DescriptionBackup ID. Pass it to POST /db/restore
Fielddata.lastBackup.sourceAppId Typestring DescriptionID of the application the backup was taken from
Fielddata.lastBackup.platformPaid Typeboolean Descriptiontrue if the platform pays for storing the backup
Fielddata.lastBackup.captureScope Typestring DescriptionWhat was backed up. Always SQLITE — a single database file
Fielddata.lastBackup.status Typestring DescriptionBackup status. Always COMPLETED here
Fielddata.lastBackup.triggerType Typestring DescriptionBackup reason: MANUAL, SCHEDULED, PRE_CHANGE, PRE_DELETE
Fielddata.lastBackup.file Typestring | null DescriptionPath of the backed-up file relative to /data
Fielddata.lastBackup.sizeBytes Typestring | null DescriptionBackup size in bytes, a decimal number as a string
Fielddata.lastBackup.createdAt Typestring (ISO 8601) DescriptionWhen the backup was queued
Fielddata.lastBackup.completedAt Typestring (ISO 8601) | null DescriptionWhen the backup became ready
Fielddata.lastBackup.expiresAt Typestring (ISO 8601) | null DescriptionWhen the backup will be deleted
Fielddata.lastBackup.errorCode Typestring | null DescriptionBackup error code. null for a completed backup

Each backup in the backup list has the same fields.

Response example

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

Error response example

503 — the galaxy host has no service image for reading the database:

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

If the error persists, check the host preparation status and, if needed, prepare the host.

Errors

HTTP Code Description
HTTP400 CodeVALIDATION_ERROR DescriptionA query string parameter other than file was passed, or file is empty or longer than 1024 bytes
HTTP400 CodeAPP_DB_INVALID_FILE DescriptionThe VIBE_DB_PATH variable in the application container points outside /data or contains an invalid path
HTTP400 CodeAPP_DB_UNSUPPORTED_PLACEMENT DescriptionThe application is not hosted in Galaxy
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing
HTTP401 CodeINVALID_API_KEY DescriptionThe key is not recognized
HTTP402 CodeBILLING_FROZEN DescriptionThe galaxy host is asleep and the balance is frozen — the host cannot be woken
HTTP403 CodeINFRA_SCOPE_REQUIRED DescriptionThe key lacks the vibe:infra scope
HTTP403 CodeAPP_DB_DISABLED DescriptionDatabase access is not enabled for the portal
HTTP403 CodeSERVER_WAKE_BLOCKED DescriptionThe galaxy host is asleep and waking it is blocked
HTTP404 CodeNOT_FOUND DescriptionThe application does not exist, was deleted or is not accessible to this key
HTTP409 CodeAPP_DB_BUSY DescriptionThe host is busy with another operation or did not connect within 10 seconds. The response carries a Retry-After header. If the host is busy building an application, error.details.holder names the operation and the application. While the galaxy host is starting after sleep or creation, error.details.hostState is waking
HTTP429 CodeRATE_LIMITED DescriptionThe read request limit for the portal was exceeded — Limits. The pause is in the Retry-After header
HTTP503 CodeAPP_DB_TOOL_UNAVAILABLE DescriptionThe host is not prepared for database reads or is temporarily unavailable. The response carries a Retry-After header
HTTP503 Codeuser_self_deletion_pending DescriptionThe key owner is deleting their account on this portal

Full list of common API errors — Errors.

Known specifics

  • Only SQLite databases are listed. A file is included if it starts with the SQLite signature. The -wal, -shm and -journal journal files, hidden files and directories whose names start with a dot, and symbolic links are skipped.

See also