POST /replicate endpoint implements write-behind differential state replication. Instead of uploading a full snapshot on every change, you push compact encrypted block diffs — called chunks — along with a Merkle root that covers the full set. The server validates each chunk size, executes credit debits atomically, checks for split-brain conflicts, and confirms persistence. You can push multiple chunks in a single request to amortize round-trip latency.
Request
Request Body
Array of one or more replication chunk objects to append to the log. Each element must conform to the chunk schema below.
64-character SHA-256 hex hash representing the Merkle tree root computed over all chunks in this request.
Chunk Object Schema
Each object in thechunks array must include:
Monotonic sequence number for this chunk. Must not create gaps relative to the current replication head.
64-character SHA-256 hex hash of the packed block in
IV || ciphertext form. Used for idempotency and split-brain detection.Base64-encoded packed chunk block. The decoded size must not exceed 256 KB (
chunk_too_large is returned if it does).Example Request Body
Billing Costs
Billing is executed atomically using the
atomic_debit_credits_milli_v2 function. If any part of the transaction fails, the full debit is refunded automatically.
Idempotency and Split-Brain Conflict Detection
To guarantee absolute recall integrity, the database enforces a unique constraint on the(agent_id, sequence_number) pair for every chunk:
Idempotent retries: If a chunk’s sequence number is already registered and its block_hash matches exactly, the server recognises the request as a safe retry and returns 200 OK with { "idempotent": true } — no credits are charged and no duplicate record is written.
Split-brain conflict: If a chunk’s sequence number is already registered but the block_hash differs, the server detects a split-brain condition (two offline devices diverging on the same sequence slot) and rejects the write with 409 Conflict:
Response
200 OK — Standard
200 OK — Idempotent Replay
true when the submitted chunk was already registered with a matching block_hash. No new record was created and no credits were debited.