Idempotency

Ensure safe retries with idempotency keys.

Include an Idempotency-Key header on JSON requests that create work or request signed access. Reusing the same key with the same method, path, and JSON request returns the original successful response instead of creating a duplicate operation. Reusing a key with a different request returns a conflict.

Idempotent POST requestBash
curl -X POST https://api.omtx.ai/v2/data-access/shards \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Idempotency-Key: export-$(date +%s)" \
  -H "Content-Type: application/json" \
  -d '{"protein_uuid":"YOUR_GENERATED_PROTEIN_UUID"}'

Notes

  • Use UUIDs or timestamps for unique keys.
  • Same key plus same request returns the cached response.
  • Same key plus different request returns 409 idempotency_key_reused_with_different_request.
  • Required on current POST/PUT/DELETE routes that create or update work, including data access, diligence, and Hub launches.
  • POST /v2/artifacts/upload is the current exception; the SDK artifact helpers do not take idempotency_key= today.