Begin a transaction

Opens a multi-statement transaction at snapshot or serializable isolation and returns its id.

POST /v1/tenants/{tenant}/tx/begin

Open a snapshot for related operationsThis transaction HTTP API is marked as preview.

Choose the isolation levelRequest snapshot or serializable behavior.
Begin the transactionReceive a transaction ID and read snapshot marker.
Reuse the transaction IDKeep subsequent reads and writes in the same transaction.

Before you start

Use your database bearer token.

Connection setup

Keep the returned tx_id for later requests. Finish each open transaction with commit or rollback.

Path parameters

Field	Type	Required
`tenant`	`string`	Required

Query parameters

Field	Type	Required
`isolation`	`string`	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 body is optional and may be empty.
isolation is "snapshot_isolation" (default) or "serializable";
it may instead be sent as ?isolation=, and the two must agree.
Misspellings such as isolation_level are refused with 400.
Serializable is refused (501) on a sharded database.

Field	Type	Required
`isolation`	`string`	Optional

Read the result

Save tx_id and use it in subsequent transaction requests. read_ts is the snapshot marker, not a row count. The _preview marker identifies this transaction API as preview behavior.

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.
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.
501	Check deployment support for this operation.
503	Honor Retry-After when present; check write outcomes.

Request example

curl --include --request POST "${OC_BASE_URL}/v1/tenants/${OC_TENANT}/tx/begin" \
  --header "Authorization: Bearer ${OC_TOKEN}" \
  --header "Content-Type: application/json" \
  --data-binary '{
  "isolation": "snapshot_isolation"
}'

Response example

Examples use synthetic values to show the response format.

Response status

{
  "tx_id": "11111111-1111-4111-8111-111111111111",
  "read_ts": 100,
  "isolation": "snapshot_isolation",
  "_preview": true
}

Synthetic transaction id and read timestamp; substitute the returned id in later calls.

Download the OpenAPI specification for the complete response schemas.

Before you startCopy Anchor Link

Path parametersCopy Anchor Link

Query parametersCopy Anchor Link

HeadersCopy Anchor Link

Request bodyCopy Anchor Link

Read the resultCopy Anchor Link