Idempotency

Every create endpoint requires an Idempotency-Key header.

-H "Idempotency-Key: campaign-1001-square"

Idempotency is scoped to the API key. The same API key, key value, endpoint, and request body return the same job.

Same key, same body

Returns the existing job:

{
  "job": {
    "id": "f693e677-51e0-4ebe-80a0-ad06acbc4443",
    "api": "ad_creative",
    "status": "queued"
  }
}

Same key, different body

Returns:

{
  "error": {
    "code": "idempotency_conflict",
    "message": "This Idempotency-Key was already used with a different request body."
  },
  "request_id": "req_abc123"
}

Recommended keys

Use stable business identifiers:

catalog-sync-2026-06-28-page-4
shopify-product-8172-main-image-cleanup
ad-campaign-456-beverage-square-v1

Do not reuse the same key for unrelated work.

Getting started

Image API guides

Guides

Same key, same body

Same key, different body

Recommended keys

​Same key, same body

​Same key, different body

​Recommended keys

Same key, same body

Same key, different body

Recommended keys