Transaction

POST /api/v1/transaction is the call Queen was built around. It writes a worker’s whole step (the acks of what it took, the events it produces, the KV state it changes, the timers it sets, where a consumer group should read next) as one entry of the replicated log, so all of it applies or none of it does. There is no outbox table to poll and no idempotency table to consult before you act: the step and its effects are the same write.

It answers HTTP 200 both when it commits (success: true) and when it rolls back (success: false with a reason), because a rollback is a verdict about your data, not a failure of the call. This page is every field, every result and every reason. For the model and the patterns built on it, read transactions first.

Request

{
  "operations": [],      // { "type": "ack" | "push", ... }, in order
  "requiredLeases": [],  // lease ids, strings
  "kv": [],              // { "op": "put" | "putIfAbsent" | ..., ... }
  "timers": [],          // { "op": "schedule" | "reschedule" | "cancel", ... }
  "positions": []        // { "queue", "consumerGroup", "partition", "offset" }
}

At least one of operations, kv, timers and positions must be non-empty. A kv or timer element inside operations is refused with 400, and so is a top-level field that is present but not an array.

Push operation

Either a list of items, or one item inline (queue, partition, payload on the operation).

Two items with the same (queue, partition, transactionId) in one call store one message; the second result says duplicate: true. An item whose transactionId is already in the partition’s dedup window rolls the whole transaction back with reason: "duplicate".

Ack operation

failed counts one attempt: the message is redelivered while the queue’s retryLimit lasts, then dead-lettered (or dropped with deadLetterQueue: false). retry releases it for redelivery without counting an attempt. dlq dead-letters it now.

How an ack finds its lease

Each ack gets at most one lease, found in this order:

1. its own leaseId;
2. otherwise the one lease named by requiredLeases and the other acks’ leaseIds together, when they all name the same lease;
3. otherwise none.

An ack with a lease is fenced. The lease must be the one the partition holds for that group, not expired, and the message must be inside the leased batch. If not (the lease expired, the message went to another worker, an earlier commit already acked it and released the lease), the whole transaction rolls back with reason: "rejected_ack".

An ack with no lease is not fenced. The broker skips the lease check: it acks the message even if another worker holds it. It still rolls back with rejected_ack when the message is not found after the group’s cursor, or was already acked with a failed, retry or dlq status. A completed ack of a message that was already acked is a no-op, and the rest of the transaction commits.

requiredLeases fences nothing on its own: it only supplies the lease of the acks in the same body. Every SDK puts each acked message’s leaseId on its ack as well as in requiredLeases, so a transaction that acks messages from two different pops is fenced by both leases. Over HTTP, put leaseId on every ack.

KV operations

The same operations as POST /api/v1/kv, without getPrefix.

Every put, putIfAbsent and incr carries exactly one expiry: ttlSeconds (an integer greater than 0) or forever: true; the JS SDK turns ttl: '30d' into ttlSeconds. A value is any JSON value of at most QUEEN_KV_MAX_VALUE_BYTES (64 KiB) as compact JSON. expect is a version number, and 0 means the key must not exist.

required: true turns an operation into a gate. If its precondition loses (exists, absent, version, limit, type), the whole transaction rolls back with reason: "kv_precondition". Without required, a lost precondition is applied: false in the results and the rest commits. The JS .once(ns, key) is putIfAbsent with required: true.

ns matches ^[a-z0-9][a-z0-9._-]{0,63}$, a key is 1 to 512 bytes with no NUL, and a key may be written once per call. A transaction carries at most 64 KV operations naming at most 256 keys.

Timer operations

The broker owns producerSub, messageId, deliverAt, attempts, the tenant fields and every field starting with _: a timer op that carries one is refused with 400. A (queue, timerKey) may appear once per call.

Positions

A position set here releases any lease the group holds on that partition. At most 16,384 per call.

Response

{ "transactionId": "0199a7c2-61f0-7b02-9a4c-0e5d3f2b8c11", "success": true, "results": [] }

results has one element per part, in one index space: the operations first, in order, then kv, then timers, then positions. Every element carries index and type; KV, timer and position results also carry opIndex, their place in their own array. The top-level transactionId is minted for this call; it is not a dedup key.

absent on a cancel means no pending timer has that key: it may already have fired.

Example

An order worker acks the event, records the order state, pushes a receipt, schedules a reminder and gates the whole step on a marker:

curl -s http://localhost:6632/api/v1/transaction \
  -H 'Content-Type: application/json' -d '{
  "operations": [
    { "type": "ack", "transactionId": "order-7-paid", "partitionId": "42",
      "consumerGroup": "billing", "leaseId": "0199a7c2-5e1b-7f3a-8c21-4d9e0b6a1f37" },
    { "type": "push", "items": [
      { "queue": "receipts", "partition": "customer-123",
        "transactionId": "receipt-order-7", "payload": { "orderId": "order-7", "total": 120.5 } } ] }
  ],
  "kv": [
    { "op": "put", "ns": "orders", "key": "order-7", "value": { "status": "paid" },
      "ttlSeconds": 2592000 },
    { "op": "putIfAbsent", "ns": "paid", "key": "order-7-paid", "value": true,
      "ttlSeconds": 86400, "required": true }
  ],
  "timers": [
    { "op": "schedule", "queue": "reminders", "timerKey": "order-7", "delayMs": 86400000,
      "txn": "reminder-order-7", "payload": "eyJvcmRlcklkIjoib3JkZXItNyJ9" }
  ]
}'

The commit:

{
  "transactionId": "0199a7c2-61f0-7b02-9a4c-0e5d3f2b8c11",
  "success": true,
  "results": [
    { "index": 0, "type": "ack", "success": true, "transactionId": "order-7-paid",
      "error": null, "dlq": false },
    { "index": 1, "type": "push", "success": true, "transactionId": "receipt-order-7",
      "messageId": "0199a7c2-61f1-7d55-b0e2-7a1c9e4f6d20", "queueName": "receipts" },
    { "index": 2, "op": "put", "applied": true, "key": "order-7",
      "value": { "status": "paid" }, "version": 90101, "opIndex": 0, "type": "kv" },
    { "index": 3, "op": "putIfAbsent", "applied": true, "key": "order-7-paid",
      "value": true, "version": 90102, "opIndex": 1, "type": "kv" },
    { "ok": true, "status": "scheduled", "queue": "reminders", "timerKey": "order-7",
      "txn": "reminder-order-7", "messageId": "0199a7c2-61f1-7d55-b0e2-8b3f0a2d4e71",
      "deliverAt": "2026-10-02T09:14:03.512887Z", "opIndex": 0, "index": 4, "type": "timer" }
  ]
}

If the same event comes back (the group was seeked back and pops it again under a new lease), the step runs again. Its receipt carries the same transactionId, so the step rolls back and writes nothing:

{
  "transactionId": "0199a7c3-0a2e-7c11-8d40-5f6e7a8b9c02",
  "success": false,
  "reason": "duplicate",
  "error": "QDUP a pushed message to receipts/customer-123 is a duplicate (original offset 17); the transaction rolled back",
  "results": []
}

Rollback reasons

A rolled-back transaction wrote nothing. The body is {transactionId, success: false, reason, error, results: []}. When several guards would fire, the reason is the first in this order: the acks (rejected_ack), the pushes (duplicate), the positions, the KV operations (kv_precondition), the timers.

A lost required KV operation adds the operation that lost:

{
  "transactionId": "0199a7c3-0a2e-7c11-8d40-5f6e7a8b9c02",
  "success": false,
  "reason": "kv_precondition",
  "error": "QKV a required KV precondition failed; the transaction rolled back",
  "results": [],
  "ok": false,
  "failedIndex": 3,
  "kvReason": "exists",
  "version": 90102,
  "value": true
}

failedIndex is in the same index space as results. The JS client returns this answer from commit(); every other success: false throws with error.reason set.

Some failures use the engine’s error body {"error", "code"} instead, with no reason: 413 name_too_long (a pushed queue or partition name over the key budget), 400 bad_request (a transactionId over 65,535 bytes), 429 overloaded, 503 retry, no_leader or timeout, 507 storage_full, 500 internal, and the 401/403 of authentication. See errors.

Retries

Inside one call, the broker retries a leader change itself, under the call’s request id, until the deadline (QUEEN_STMT_TIMEOUT_MS, 30 s), and a transaction that committed before the change is answered from its record and does not run again.

Across calls there is no client-supplied request id: a request you send again is a new transaction, and after a 503 or a lost connection the first attempt may have committed. If it did, the retry rolls back and writes nothing only because of what the body carries: a fenced ack whose lease the first commit released (rejected_ack), a pushed transactionId already in the partition (duplicate), or a required marker (kv_precondition). An ack with no lease does not stop it, because acking a message twice is a no-op.

Give every pushed item a deterministic transactionId, or gate the step with a required marker, so that a retry is harmless. A transaction made only of KV writes and timers, with no gate, runs again when retried: an incr counts twice, and a timer that already fired is scheduled again. The JS client retries 5xx answers itself (three attempts by default), so this applies to SDK calls too. See dedup.

Limits

• One call, one tenant. There is no interactive BEGIN and COMMIT: a transaction cannot read a value and branch on it. expect and required are the conditions it can carry.
• The timer horizon (QUEEN_TIMERS_MAX_HORIZON_S, 90 days), the 1 MiB timer payload ceiling and the 256-op cap of POST /api/v1/timers are not applied to the timers array of a transaction.
• Throughput and commit latency, measured against Kafka, Redpanda and Pulsar on the same machines, are on the transactions benchmark.
• An external side effect, such as an HTTP call to a payment provider, is outside the commit.