Idempotency

A network call can fail after the server has already done the work. If you simply send it again, you might do it twice. An idempotency key makes the retry safe.

Send an Idempotency-Key header on every write that creates something. It is always optional; over MCP a repeat of the same call is recognised for you. Choose a value that is unique for that one intended change, up to 200 characters. A random identifier or a name from your own data works well.

curl -s -X POST "https://app.konekt.so/api/v1/workspaces/$WS/campaigns" \
  -H "Authorization: Bearer $KEY" \
  -H "Idempotency-Key: october-campaign-1" \
  -H "Content-Type: application/json" \
  -d '{"name": "Hiring managers, October"}'

What happens on a repeat

The same key with the same body returns the saved answer, with the header Idempotent-Replay: true. Nothing is changed a second time.
The same key with a different body is refused with 422 and the code idempotency_key_reused.
The same key while the first call is still running is refused with 409 and the code idempotency_in_progress. Wait a moment and try again.
Saved answers are kept for 24 hours. A request that was queued for approval is saved too: the replay is the same 202.

Reads need no key. A reply into a conversation is also protected without one: the same text sent into the same conversation within ten minutes returns the first message and sends nothing more. A signing secret that is shown only once is not kept in the saved answer, so a replay shows secret: null.

Dry runs (dry_run: true) change nothing, use no key and leave no record.