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
required
Array of one or more replication chunk objects to append to the log. Each element must conform to the chunk schema below.
string
required
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:
integer
required
Monotonic sequence number for this chunk. Must not create gaps relative to the current replication head.
string
required
64-character SHA-256 hex hash of the packed block in
IV || ciphertext form. Used for idempotency and split-brain detection.string
required
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
integer
Number of chunks successfully written to the replication log.
integer
Sequence number of the last accepted chunk.
string
Echo of the
merkle_root submitted in the request, confirming what the server recorded.200 OK — Idempotent Replay
boolean
true when the submitted chunk was already registered with a matching block_hash. No new record was created and no credits were debited.