Idempotency - BlobRouter

BlobRouter v0.1 · Last updated: August 2026 · Architecture version: 2.0

Current behavior

BlobRouter v1 does not accept an Idempotency-Key header.

Operation	Idempotent?	Notes
`POST /v1/upload/init`	No	Each call creates a new `fileId` / pending row
Provider `PUT`	Provider-dependent	Same key overwrite semantics vary by provider
`POST /v1/upload/complete`	Effectively yes once active	Re-complete after success should be treated carefully; prefer one complete per init
`GET /v1/file/:id`	Yes	Safe to retry
`DELETE /v1/file/:id`	Yes after delete	May return already-deleted semantics
`POST /v1/scanner/scan`	Guarded	Concurrent scan may return `scan_already_running`
`POST /v1/keys/rotate`	No	Each call issues a new key

Guidance

Treat each upload() / init as a new object
On uncertain network after PUT, use fileId + complete carefully; do not blindly re-init
Prefer SDK retries for safe GETs and transient control-plane failures (Retries)

Idempotency keys are a likely v2 addition for init/complete.

⌘I