Run write SQL

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

Runs write SQL statements against the application's SQLite database in one transaction: changes rows, creates and alters tables, indexes and views.

Before each call, the platform saves a separate protective backup of the database — see Protective backups before writes. Access conditions — When the database is available.

Parameters

Request fields (body)

An unknown body field is rejected with 400 VALIDATION_ERROR.

The following in sql are rejected with 422 APP_DB_SQL_ERROR and reason not_permitted: transaction and savepoint control (BEGIN, COMMIT, ROLLBACK, SAVEPOINT), ATTACH and DETACH, PRAGMA, creating and dropping virtual tables, access to schemas other than main, including temporary tables, and the load_extension, readfile, writefile and fts3_tokenizer functions. VACUUM does not run either: the call runs inside a transaction, and the statement is rejected with 422 APP_DB_SQL_ERROR.

Examples

curl — personal key

curl -X POST "https://vibecode.bitrix24.com/v1/infra/servers/APP_ID/db/execute" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sql":"UPDATE notes SET body = ? WHERE id = ?","parameters":["updated",1]}'

curl — OAuth application

curl -X POST "https://vibecode.bitrix24.com/v1/infra/servers/APP_ID/db/execute" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sql":"UPDATE notes SET body = ? WHERE id = ?","parameters":["updated",1]}'

JavaScript — personal key

const url = `https://vibecode.bitrix24.com/v1/infra/servers/${appId}/db/execute`
const headers = { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json' }
const body = JSON.stringify({ sql: 'UPDATE notes SET body = ? WHERE id = ?', parameters: ['updated', 1] })

// Only 409 APP_DB_BACKUP_NOT_READY is retried: with this response the SQL has not run yet
const deadline = Date.now() + 180_000
let result
while (Date.now() < deadline) {
  const res = await fetch(url, { method: 'POST', headers, body })
  result = await res.json()
  if (res.status !== 409 || result.error?.code !== 'APP_DB_BACKUP_NOT_READY') break
  const seconds = Number(res.headers.get('Retry-After')) || 1
  await new Promise(resolve => setTimeout(resolve, Math.max(seconds, 3) * 1000))
}
if (!result.success) throw new Error(result.error.code)
console.log(result.data.rowCount, result.data.backupId)

JavaScript — OAuth application

const url = `https://vibecode.bitrix24.com/v1/infra/servers/${appId}/db/execute`
const headers = {
  'X-Api-Key': 'YOUR_APP_KEY',
  'Authorization': 'Bearer USER_SESSION_TOKEN',
  'Content-Type': 'application/json',
}
const body = JSON.stringify({ sql: 'UPDATE notes SET body = ? WHERE id = ?', parameters: ['updated', 1] })

const deadline = Date.now() + 180_000
let result
while (Date.now() < deadline) {
  const res = await fetch(url, { method: 'POST', headers, body })
  result = await res.json()
  if (res.status !== 409 || result.error?.code !== 'APP_DB_BACKUP_NOT_READY') break
  const seconds = Number(res.headers.get('Retry-After')) || 1
  await new Promise(resolve => setTimeout(resolve, Math.max(seconds, 3) * 1000))
}
if (!result.success) throw new Error(result.error.code)

Response fields

Response example

{
  "success": true,
  "data": {
    "file": "app.db",
    "rowCount": 1,
    "durationMs": 0.933,
    "statementCount": 1,
    "backupId": "d5e1b7a9-0f42-4c8d-9a3e-6b21c4f80e57"
  }
}

Error response example

422 — the PRAGMA journal_mode=DELETE statement is not permitted; the transaction was rolled back:

{
  "success": false,
  "error": {
    "code": "APP_DB_SQL_ERROR",
    "message": "SQL operation is not permitted",
    "details": {
      "reason": "not_permitted"
    }
  }
}

Errors

Full list of common API errors — Errors.

Known specifics

• The first call only prepares the protective backup. While there is no fresh backup for this file, the call queues its creation and returns 409 APP_DB_BACKUP_NOT_READY with details.backupId, details.retryAfterSeconds and a Retry-After header. Repeat the same request: once the backup is ready, the retry runs the SQL and returns the same ID in data.backupId. A ready backup waits 10 minutes for the retry; after that, the next call prepares a new one. How protective backups work — Protective backups before writes.
• Retries consume the write limit. Each retry after 409 counts toward the write request limit (Limits), so pause for at least three seconds, even when Retry-After is 1.
• A backup failure is reported once. If the protective backup was not created, the next call receives the cause with details.retryable: false, and the call after that queues a new backup.
• The whole call is one transaction. An error in any statement or exceeding 30 seconds rolls back all statements of the call. Rows returned by SELECT and RETURNING are read to the end and discarded: they are not included in the response. SQL and parameter values are not written to the audit log.
• Foreign keys are always enforced. For the duration of the call, the platform enables foreign key checks, even if the application itself does not. A referential integrity violation rolls back the call with reason constraint_failed.
• The application container is not started. The SQL is run by a service container on the host with the same /data volume.
• The AI agent tool retries only while the backup is not ready. The manage_app_db tool of the Vibecode MCP server with action: "execute" accepts serverId, file, sql, parameters and retries only 409 APP_DB_BACKUP_NOT_READY on its own. The total wait is 180 seconds; the pause follows Retry-After, but is no shorter than three seconds. The tool does not retry a network error or APP_DB_WRITE_OUTCOME_UNKNOWN. Cancelling the wait does not prove that an already sent write was rolled back.

See also

• Run a read-only SQL query
• List database backups
• Restore the database from a backup
• Get host preparation status
• Application database