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

Update a row

PATCH /v1/infra/servers/:id/db/tables/:table/rows/:key

Changes column values in one row of a table in a Galaxy application's SQLite database. The row is addressed by an opaque key from the row-read response; the body carries only the columns being changed.

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

Parameters

Parameter Type Required Description
Parameterid (path) Typestring Requiredyes DescriptionID of an application with kind equal to GALAXY_APP. List: GET /v1/infra/servers
Parametertable (path) Typestring Requiredyes DescriptionExact table name from data.tables[].name in the GET /db/schema response, up to 256 bytes in UTF-8. The table must have editability.editable: true: views, virtual tables and tables with neither a primary key nor an available rowid cannot be edited
Parameterkey (path) Typestring Requiredyes DescriptionRow key — the data.rowKeys[i] item of the GET /db/tables/:table/rows response, aligned with the data.rows[i] row. A base64url string up to 1024 characters, inserted into the path as is. null in rowKeys means the row cannot be addressed: the key column value is null, a BLOB or too long. The key is built from the primary key or, if there is none, from rowid, unless a column with that name shadows it. Do not modify the key or write it to logs: it contains the values of the row's key columns

Request fields (body)

The body is strict JSON: fields not listed in the table below are rejected with 400 VALIDATION_ERROR. The body is limited to 64 KiB.

Field Type Required Description
Fieldfile Typestring Requiredno DescriptionRelative path to the database file inside the application volume, up to 1024 bytes in UTF-8. Defaults to the VIBE_DB_PATH value of the application container, or app.db if it is not set. Absolute paths, parent-directory traversal and symbolic links are not allowed. Must match the file key was read from
Fieldvalues Typeobject Requiredyes DescriptionNew values: the key is a column name from the schema, up to 256 bytes in UTF-8, the value is the cell. From 1 to 256 columns; the row's other columns are not changed. Row key columns from editability.keyColumns, generated columns and hidden columns cannot be passed. A column that currently holds a BLOB or a value longer than 64 KiB cannot be overwritten; other columns of this row can
Fieldvalues.<column> Typenull | number | string | object Required— Descriptionnull, a finite number, a string up to 64 KiB in UTF-8 or an object { "type": "integer", "value": "9223372036854775807" } for an exact 64-bit integer. An integer without the object is accepted only within ±9007199254740991. Booleans, arrays, BLOBs and other objects are not accepted

Examples

curl — personal key

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/infra/servers/7c2b1f08-3a4d-4e91-9b6c-2f5e8a1d0c33/db/tables/customers/rows/eyJ2IjoxLCJhcHBJZCI6IjdjMmIxZjA4LTNhNGQtNGU5MS05YjZjLTJmNWU4YTFkMGMzMyIsImZpbGUiOiJhcHAuZGIiLCJ0YWJsZSI6ImN1c3RvbWVycyIsImtpbmQiOiJwayIsImNvbHVtbnMiOlsiaWQiXSwidmFsdWVzIjpbeyJ0eXBlIjoiaW50ZWdlciIsInZhbHVlIjoiNCJ9XX0" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "values": {
      "email": "d2@example.com"
    }
  }'

curl — OAuth application

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/infra/servers/7c2b1f08-3a4d-4e91-9b6c-2f5e8a1d0c33/db/tables/customers/rows/eyJ2IjoxLCJhcHBJZCI6IjdjMmIxZjA4LTNhNGQtNGU5MS05YjZjLTJmNWU4YTFkMGMzMyIsImZpbGUiOiJhcHAuZGIiLCJ0YWJsZSI6ImN1c3RvbWVycyIsImtpbmQiOiJwayIsImNvbHVtbnMiOlsiaWQiXSwidmFsdWVzIjpbeyJ0eXBlIjoiaW50ZWdlciIsInZhbHVlIjoiNCJ9XX0" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "values": {
      "email": "d2@example.com"
    }
  }'

JavaScript — personal key

javascript 
// The key comes from data.rowKeys of the GET /db/tables/customers/rows response
const rowKey = 'eyJ2IjoxLCJhcHBJZCI6IjdjMmIxZjA4LTNhNGQtNGU5MS05YjZjLTJmNWU4YTFkMGMzMyIsImZpbGUiOiJhcHAuZGIiLCJ0YWJsZSI6ImN1c3RvbWVycyIsImtpbmQiOiJwayIsImNvbHVtbnMiOlsiaWQiXSwidmFsdWVzIjpbeyJ0eXBlIjoiaW50ZWdlciIsInZhbHVlIjoiNCJ9XX0'

const res = await fetch(`https://vibecode.bitrix24.com/v1/infra/servers/7c2b1f08-3a4d-4e91-9b6c-2f5e8a1d0c33/db/tables/customers/rows/${rowKey}`, {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    values: {
      email: 'd2@example.com',
    },
  }),
})

const { success, data, error } = await res.json()
if (res.status === 409 && error.code === 'APP_DB_BACKUP_NOT_READY') {
  // The protective backup is being prepared — retry after Retry-After seconds
  console.log('Retry in', res.headers.get('Retry-After'), 's')
} else {
  console.log('Rows updated:', data.rowCount)
}

JavaScript — OAuth application

javascript 
// The key comes from data.rowKeys of the GET /db/tables/customers/rows response
const rowKey = 'eyJ2IjoxLCJhcHBJZCI6IjdjMmIxZjA4LTNhNGQtNGU5MS05YjZjLTJmNWU4YTFkMGMzMyIsImZpbGUiOiJhcHAuZGIiLCJ0YWJsZSI6ImN1c3RvbWVycyIsImtpbmQiOiJwayIsImNvbHVtbnMiOlsiaWQiXSwidmFsdWVzIjpbeyJ0eXBlIjoiaW50ZWdlciIsInZhbHVlIjoiNCJ9XX0'

const res = await fetch(`https://vibecode.bitrix24.com/v1/infra/servers/7c2b1f08-3a4d-4e91-9b6c-2f5e8a1d0c33/db/tables/customers/rows/${rowKey}`, {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    values: {
      email: 'd2@example.com',
    },
  }),
})

const { success, data, error } = await res.json()
if (res.status === 409 && error.code === 'APP_DB_BACKUP_NOT_READY') {
  // The protective backup is being prepared — retry after Retry-After seconds
  console.log('Retry in', res.headers.get('Retry-After'), 's')
} else {
  console.log('Rows updated:', data.rowCount)
}

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.file Typestring DescriptionDatabase file in which the row was changed
Fielddata.table Typestring DescriptionTable name
Fielddata.rowCount Typenumber DescriptionNumber of rows changed, always 1
Fielddata.durationMs Typenumber DescriptionWrite execution time in the database, in milliseconds
Fielddata.backupId Typestring DescriptionID of the protective backup taken before the first row edit of the last 10 minutes. Row edits in this window share one backup, and restoring it undoes all of them. Backup list — GET /db/backups, restore — POST /db/restore

Response example

JSON 
{
  "success": true,
  "data": {
    "file": "app.db",
    "rowCount": 1,
    "durationMs": 1.336,
    "table": "customers",
    "backupId": "cb2fcdfd-bace-4932-a276-31d737337f3d"
  }
}

Error response example

409 — the id primary key column was passed in values:

JSON 
{
  "success": false,
  "error": {
    "code": "APP_DB_ROW_NOT_EDITABLE",
    "message": "Database row cannot be edited"
  }
}

Errors

HTTP Code Description
HTTP404 CodeAPP_DB_ROW_NOT_FOUND DescriptionNo row was found by the key: the row was deleted or its key value changed
HTTP409 CodeAPP_DB_ROW_NOT_EDITABLE DescriptionThe row cannot be changed: values contains a row key column, a generated column, a column that does not exist in the table, or a column with a BLOB or a value longer than 64 KiB. Also returned when the key does not match this application, file or table, the key matches more than one row, or the table is not editable
HTTP409 CodeAPP_DB_BACKUP_NOT_READY DescriptionThe protective backup is being prepared; the row was not changed. error.details contains backupId, retryable: true and retryAfterSeconds; the Retry-After header carries the same number of seconds, from 1 to 60. Retry the same request after the pause
HTTP409 CodeAPP_DB_BUSY DescriptionA deploy, migration or restore of the application or another database write is in progress, or waking the application or host is blocked. The Retry-After header is present
HTTP409 CodeAPP_DB_WAL_CLOSED DescriptionThe protective backup was not created: a running application has closed its database connection in WAL mode. The row was not changed; there is no Retry-After header. Configure the application to keep the connection open
HTTP400 CodeVALIDATION_ERROR DescriptionThe request failed validation: values is empty or missing, the body has an extra field, a value type or file is invalid, the table name is longer than 256 bytes, or the key is longer than 1024 characters or contains characters outside base64url
HTTP400 CodeAPP_DB_INVALID_FILE DescriptionThe file path does not point to a valid database file inside /data
HTTP400 CodeAPP_DB_UNSUPPORTED_PLACEMENT DescriptionThe application is not hosted in Galaxy
HTTP404 CodeAPP_DB_TABLE_NOT_FOUND DescriptionThe database has no :table table
HTTP404 CodeAPP_DB_NOT_FOUND DescriptionThere is no volume or database file: the application has not created a database yet
HTTP404 CodeNOT_FOUND DescriptionThe application was not found, was deleted or is not accessible to this key
HTTP413 CodePAYLOAD_TOO_LARGE DescriptionThe body exceeds 64 KiB or the full input of the service process exceeds 96 KiB
HTTP422 CodeAPP_DB_SQL_ERROR DescriptionThe database rejected the change; the transaction was rolled back. The cause is in error.details.reason, for example constraint_failed or type_mismatch
HTTP422 CodeAPP_DB_QUERY_TIMEOUT DescriptionThe write did not finish within 30 seconds; the transaction was rolled back
HTTP422 CodeAPP_DB_CORRUPT DescriptionThe database file is corrupted
HTTP422 CodeAPP_DB_BACKUP_TIMEOUT DescriptionThe protective backup did not finish within the allotted time; the row was not changed
HTTP422 CodeAPP_DB_BACKUP_INVALID DescriptionThe protective backup failed validation; the row was not changed
HTTP503 CodeAPP_DB_PRE_CHANGE_FAILED DescriptionThe protective backup was not created; the row was not changed. The error is reported once — the next call starts a new backup
HTTP503 CodeAPP_DB_WRITE_OUTCOME_UNKNOWN DescriptionThe database response was lost; the row may have been changed. retryable: false — do not retry automatically; check the row first
HTTP503 CodeAPP_DB_TOOL_UNAVAILABLE DescriptionThe host is not prepared or is temporarily unavailable. The Retry-After header is present
HTTP402 CodeBILLING_FROZEN DescriptionThe portal's billing is frozen
HTTP402 CodeBILLING_INSUFFICIENT DescriptionThe portal balance is insufficient to create a protective backup
HTTP403 CodeAPP_DB_READONLY_KEY DescriptionA read-only key cannot change the database
HTTP403 CodeAPP_DB_DISABLED DescriptionDatabase access is not enabled for the portal
HTTP403 CodeINFRA_SCOPE_REQUIRED DescriptionThe key lacks the vibe:infra scope
HTTP429 CodeRATE_LIMITED DescriptionThe write request limit for the portal was exceeded — Limits. The pause is in the Retry-After header
HTTP401 CodeMISSING_API_KEY DescriptionX-Api-Key is missing

Full list of common API errors — Errors.

Known specifics

There is no row version check. The update does not verify whether the row changed after it was read: when two edits to the same row run concurrently, the values from the last one are kept.

The key goes stale together with the schema. The key stores the table's set of key columns at read time. If the table's primary key has changed, earlier keys return 409 APP_DB_ROW_NOT_EDITABLE — read the rows again.

See also