Idempotency

Every POST endpoint accepts an Idempotency-Key header. Sending one means a retried request (for example after a timeout or a dropped connection) cannot accidentally create a duplicate post, media asset, or webhook endpoint.

How it works

Idempotency-Key: 3f9b6c2e-3b9a-4b8a-9b2e-3f9b6c2e3b9a

• Use a UUID (or any sufficiently random string) as the key.
• The same key with the same request body, within 24 hours, returns the original stored response instead of processing the request again. The response carries Idempotent-Replayed: true.
• The same key with a different body returns 409 idempotency_conflict.
• A second request with the same key while the first is still processing returns 409 idempotency_in_progress.

curl -X POST https://api.getimma.com/v1/posts \
  -H "Authorization: Bearer imma_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f9b6c2e-3b9a-4b8a-9b2e-3f9b6c2e3b9a" \
  -d '{ "profile_id": "prof_01J...", "caption": "...", "media": ["med_01J..."], "targets": [{ "account_id": "acc_ig_..." }] }'

Batch requests

Posts batch applies the Idempotency-Key per item, combining the request's key with each item's index. This means a retried batch call that partially failed can be corrected (for example after fixing one item's media) without duplicating the items that already succeeded.

Practical advice

• Always send a key on every POST, not just ones you expect might be retried.
• Generate a new key per logical request, never reuse one key across genuinely different posts.
• If you must change a request after a failed attempt, use a new key; reusing the old key with different content returns idempotency_conflict by design.

Errors

See Errors for the shared error shape.