> ## 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.

# Request lifecycle

> What happens from storage.upload() to a verified file on your provider.

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

This is the path of a single routed upload. BlobRouter never receives the file bytes.

```text theme={null}
Developer
    │
    ▼
storage.upload()          (SDK)
    │
    ▼
POST /v1/upload/init      (API key auth)
    │
    ▼
route()                   (priority + cost formula)
    │
    ▼
presigned PUT URL         (~1 hour expiry)
    │
    ▼
PUT → provider            (direct; not through BlobRouter)
    │
    ▼
POST /v1/upload/complete
    │
    ▼
HeadObject verify
    │
    ▼
Done                      (file active + usage recorded)
```

## Step by step

1. **`upload()`** — SDK validates local options and starts the control-plane sequence.
2. **`POST /v1/upload/init`** — Auth, plan checks, decrypt provider credentials, run routing engine, insert a `pending` file row, return `{ fileId, presignedUrl, provider, savedVsAws, routingWarning? }`.
3. **`route()`** — Deterministic. Hot prefers R2, archive prefers B2, cold uses the cost formula. Missing preferred provider → warn + fallback (never fail if any provider exists).
4. **Presigned URL** — Minted with *your* credentials against *your* bucket.
5. **`PUT`** — Client uploads directly to AWS / R2 / B2. Retries here are outside BlobRouter’s control; the SDK does not retry this PUT.
6. **`POST /v1/upload/complete`** — SDK tells BlobRouter the PUT finished.
7. **`HeadObject`** — API verifies the object exists at the expected size/key. Protects savings accuracy.
8. **Done** — Status becomes `active`; a `usage_events` row records GB routed.

## Failure points

| Where           | What you see                                    |
| --------------- | ----------------------------------------------- |
| Init auth       | `401 unauthorized`                              |
| No providers    | `400` / no providers configured                 |
| Plan / quota    | `402 plan_limit`                                |
| Rate limit      | `429` + `Retry-After`                           |
| Provider PUT    | SDK `upload_to_provider_failed`                 |
| Complete verify | `file_not_on_provider` if the object is missing |

## Related

* [Architecture](/architecture)
* [Retries](/api/retries)
* [TypeScript SDK](/sdk/typescript)