> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blobrouter.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Idempotency

> What is and is not idempotent in BlobRouter v1.

<Info>
  **BlobRouter v0.1** · Last updated: August 2026 · Architecture version: **2.0**
</Info>

## 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](/api/retries))

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