Database endpoints
Update a row conditionally
Write a row by primary key, with an optional version check through If-Match.
PUT /v1/tenants/{tenant}/rows/{schema}/{pk}
- Read the current rowKeep the version associated with that record.
- Send a conditional writeSupply the expected version through If-Match.
- Check success or conflictOn 409, read and reconcile the newer row.
Before you start
Use your database bearer token.
For a conditional update, read the row and use its _oc_row_version in If-Match. Without that header, the request is an unconditional upsert. Do not combine If-Match with expect=insert.
Path parameters
| Field | Type | Required |
|---|---|---|
tenant | string | Required |
schema | string | Required |
pk | string | Required |
Query parameters
| Field | Type | Required |
|---|---|---|
expect | string | Optional |
chunk | integer | Optional |
Headers
| Field | Type | Required | Description |
|---|---|---|---|
x-oc-db-user | string | Optional | Acting database user (role, grant and row-policy checks). Send with x-oc-db-key. |
x-oc-db-key | string | Optional | API key of the x-oc-db-user user. |
Request body
application/json
Limits and accepted values
- The full row as a JSON object keyed by column name;
- its primary key must match the path.
- Without an If-Match header this is an unconditional upsert.
- If-Match: <n> (bare or quoted) requires the row to be at version n (its _oc_row_version);
- If-Match: * requires the row to exist.
- A stale version answers 409 write_conflict with current_version;
- a missing row answers 412 precondition_failed.
- Weak or list-valued If-Match is refused (400), as is ?expect=insert combined with If-Match. ?expect=insert alone makes the write insert-only. ?chunk is accepted but only affects NDJSON ingest.
- Honors Idempotency-Key.
| Field | Type | Required | Description |
|---|---|---|---|
Fields | object | Optional | The full row as a JSON object keyed by column name; its primary key must match the path. Without an If-Match header this is an unconditional upsert. If-Match: <n> (bare or quoted) requires the row to be at version n (its _oc_row_version); If-Match: * requires the row to exist. A stale version answers 409 write_conflict with current_version; a missing row answers 412 precondition_failed. Weak or list-valued If-Match is refused (400), as is ?expect=insert combined with If-Match. ?expect=insert alone makes the write insert-only. ?chunk is accepted but only affects NDJSON ingest. Honors Idempotency-Key. |
Read the result
version is the row version after a successful write. A stale If-Match returns 409; read the current row and reconcile your change rather than overwriting it blindly. Without If-Match, the request is an unconditional upsert.
Response statuses
HTTP status reference
| Status | What to do |
|---|---|
| 200 | OK |
| 400 | Correct the request before retrying. |
| 401 | Check the credential and Authorization header. |
| 402 | Check feature access or available credits. |
| 403 | Check tenant access, roles and permissions. |
| 404 | Check the resource ID and API route. |
| 409 | Resolve the conflict before retrying. |
| 412 | Refresh the version or ETag before writing again. |
| 413 | Split or reduce the request body. |
| 415 | Send the required Content-Type. |
| 422 | Correct the values or unsupported combination. |
| 429 | Honor Retry-After when present; back off. |
| 500 | Check the outcome before retrying a write. |
| 501 | Check deployment support for this operation. |
| 503 | Honor Retry-After when present; check write outcomes. |