What it does
POST /v1/transactions commits a list of puts and deletes as one atomic log record, provided the stated conditions hold when the writer reaches it. A client-supplied idempotency key makes a retry return the original outcome instead of repeating the change. Inside the engine, read-set validation gives interactive transactions snapshot isolation with first-committer-wins.
How it works
A request carries an optional idempotency key, a list of conditions and a list of mutations. Conditions are exists, missing and attr_eq (an attribute at a path equals a value). Mutations are put, delete and emit_event, which stages an outbox event in the same commit. A request may carry up to 256 conditions and 256 mutations. If every condition holds, all mutations commit as one log record; if any fails, nothing is written and the response is a 409 with a receipt whose status is rejected.
Conditions are evaluated on the single writer thread, against the state plus the requests staged earlier in the same batch. Two concurrent requests that both try to take the last unit of stock therefore cannot both succeed; a test runs exactly that race.
With an idempotency key, a retry of the same request returns a receipt with status replayed and the original sequence number, and applies nothing. The same key with a different payload is rejected with the error code idempotency_payload_mismatch. The stored identity covers both the mutations and the conditions, so changing a condition under a used key is also rejected. Receipts survive checkpoints and restarts, and keys are namespaced per project so two projects can use the same key text independently. When a request omits ids for puts and sends a key, the ids are derived from the key, so a retry targets the same records.
Inside the engine, begin() starts an optimistic transaction that reads from a pinned snapshot and records what it read. At commit the writer checks that nothing it read has changed, appeared or disappeared; if it has, the commit fails with a conflict and applies nothing. Isolation is snapshot isolation with first-committer-wins, and a write with no prior read of that key is last-writer-wins. The REST layer uses this internally, for example to claim unique-key reservations together with the record in one commit.
Tests record concurrent transaction histories and run an offline checker over them, for strict serializability on register and list-append workloads, in both the in-memory and disk entity profiles. A separate crash matrix kills a child process at each commit-path boundary of a mixed envelope and checks that the result is all or nothing.
Where you reach it
- HTTP
POST /v1/transactions - Library
Engine::transact, Engine::begin (optimistic transaction), Engine::transaction_receipt
Example
{
"idempotency_key": "order-7731-checkout",
"conditions": [
{ "type": "attr_eq", "id": "stock:sku-42", "path": "qty", "value": 3 },
{ "type": "missing", "id": "order:7731" }
],
"mutations": [
{ "op": "put", "id": "stock:sku-42", "kind": "stock", "attrs": { "qty": 2 } },
{ "op": "put", "id": "order:7731", "kind": "order", "attrs": { "sku": "sku-42", "qty": 1 } }
]
}Limits
- The route is a service-level surface. It needs a project service key or an operator key, not an end-user token, because it does not apply collection rules or row-level policies.
- The HTTP body supports the conditions exists, missing and attr_eq. Whole-attribute and whole-entity conditions exist in the engine library and not in the HTTP body.
- Interactive read-set transactions are an engine-library API. There is no multi-request interactive transaction over HTTP.
- Records of system kinds and reserved ids cannot be written through this route.
- The receipt has no commit timestamp today.
Evidence
- On this siteHTTP API reference
- TestsCovered in the engine repository by 6 OCC tests (stale read, phantom creation, concurrent increments), 8 transaction tests (replay as one commit, failed condition changes nothing, oversell race, size bound), 14 idempotency and request-fingerprint tests, 9 snapshot-anomaly tests, strict-serializability history tests, a crash matrix, and 17 HTTP tests for envelopes, idempotency and tenant scoping
Test coverage is listed as present in the engine repository at this edition. This page does not report test results.
KynetraDB is in private preview
Request a preview to try this against your own workload.