Idempotency

How it works

Add an Idempotency-Key header — any unique string up to 255 characters, typically a UUID — to a POST request. Engage stores the result of the first request with that key for 24 hours. Repeating the request with the same key and the same body returns the original response (same status and body) without performing the action again.

curl https://api.engage.swastik.ai/v1/messages \
  -H "Authorization: Bearer $ENGAGE_API_KEY" \
  -H "Idempotency-Key: 5d2c8f0e-4b6a-4f7e-9c1d-2a3b4c5d6e7f" \
  -H "Content-Type: application/json" \
  -d '{"to":"+919812345678","type":"text","text":{"body":"Your OTP is 482913"}}'

Rules

• Keys are scoped to your organization.
• Reusing a key with a different request body returns 409 conflict.
• If the first request is still in progress, a concurrent retry receives 409 conflict; retry shortly after.
• Requests that fail validation (4xx) are not stored — fix the request and reuse the key.
• GET and DELETE are naturally idempotent and ignore the header.

Client references

Messages also accept a client_ref field — your own identifier (for example an order id). It is echoed back in the message object and in every message.status webhook, which makes reconciliation easy.