Make agent retries safe

Agents retry. Your agent asks Search Stack to insert ten products, the insert succeeds, the response is lost on the way back — and the agent sends it again. Without protection you have twenty records.

The fix: name the attempt

Send an idempotency key — any unique string identifying this attempt — in a header:

POST https://api.searchstack.dev/search-result/Demo/products/with-fields
X-API-Key: {your key}
Idempotency-Key: load-products-2026-07-17-batch-1
Content-Type: application/json

[ { "name": "Trail Runner 2", "brand": "Vireo", "price": 119 }, … ]

• The first request does the work, and Search Stack remembers the key.
• A retry with the same key is a no-op returning the first call's outcome.
• A different key is treated as a new, intentional insert.

Why it matters for agents especially

The header is forwarded through MCP, so an agent's writes get the same exactly-once guarantee your own code would — an agent that retries three times still leaves your list in the state it should be.

Go deeper: Write operations and safe retries in the reference.