Prepare the host

POST /v1/infra/servers/:id/app-db/prepare

Starts preparing the galaxy host for working with the application database: installs missing packages and the service image for reading the database. Preparation runs in the background. Track its progress with the host preparation status.

Parameters

The request body may be empty or {}, no larger than 4096 bytes. Any body field and any query string parameter are rejected with 400 VALIDATION_ERROR.

Examples

curl — personal key

curl -X POST "https://vibecode.bitrix24.com/v1/infra/servers/APP_ID/app-db/prepare" \
  -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/app-db/prepare" \
  -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}/app-db/prepare`,
  {
    method: 'POST',
    headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json' },
    body: '{}',
  }
)
const { success, data, error } = await res.json()
if (!success) throw new Error(error.code)
// 202 — preparation is running, poll GET at the same address. 200 — the host is already ready
console.log(res.status, data.state)

JavaScript — OAuth application

const res = await fetch(
  `https://vibecode.bitrix24.com/v1/infra/servers/${appId}/app-db/prepare`,
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
      'Content-Type': 'application/json',
    },
    body: '{}',
  }
)
const { success, data, error } = await res.json()

Response fields

Response example

Preparation started, HTTP 202:

{
  "success": true,
  "data": {
    "state": "preparing",
    "missing": ["image"],
    "steps": [
      { "id": "disk", "state": "pending" },
      { "id": "python3", "state": "present" },
      { "id": "zstd", "state": "present" },
      { "id": "age", "state": "present" },
      { "id": "curl", "state": "present" },
      { "id": "image", "state": "pending" },
      { "id": "verify", "state": "pending" }
    ]
  }
}

The host is already ready, HTTP 200:

{
  "success": true,
  "data": {
    "state": "ready",
    "steps": [
      { "id": "disk", "state": "done" },
      { "id": "python3", "state": "present" },
      { "id": "zstd", "state": "present" },
      { "id": "age", "state": "present" },
      { "id": "curl", "state": "present" },
      { "id": "image", "state": "present" },
      { "id": "verify", "state": "done" }
    ],
    "missing": []
  }
}

Error response example

400 — a field was passed in the body:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid preparation parameters"
  }
}

Errors

If the preparation itself fails, the cause is not returned as an error of this call. It comes as the failed state with data.errorCode in the preparation status.

Full list of common API errors — Errors.

Known specifics

• What is installed on the host. Only the missing python3, zstd, age, curl and the pinned service image for reading the database. Packages are installed, with signature verification, from the Ubuntu repositories configured on the host. The installation plan is checked before each package: upgrading or removing already installed packages is not allowed. Packages do not start or restart services, the host is not rebooted, and the application and Docker are not restarted. At least 6 GiB of free space is required on the root partition and on the Docker images partition. Preparation is limited to 15 minutes.
• The platform performs the preparation. Commands reach the host through the platform's service channel. Neither you nor the application needs access to the host for this.
• Repeated call. While preparation is running, the call starts nothing and returns the current state with HTTP 202. After failed, the call starts preparation again; components already installed are skipped. If the start response was lost, check the preparation status first rather than retrying the start automatically.
• Preparation also starts without this call. A new galaxy host starts it on its own at first boot. Creating a database backup — manual, daily or protective — also starts preparation on a host that is not ready, unless the previous preparation ended with LOW_DISK, DPKG_BROKEN, APT_PLAN_UNSAFE or UNSUPPORTED_HOST. This call starts it even after such codes.
• Duration. On a test host where the packages were already installed and only the service image was downloaded, preparation took less than 10 seconds.

See also

• Get host preparation status
• Get database information
• Create a database backup
• Application database