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

# Python SDK

> Complete reference for the blobrouter package — bytes, file-like uploads, retries, and errors.

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

Python client for the same control-plane API as the TypeScript SDK. Server-side only — keep API keys out of browsers and notebooks that sync publicly.

## Install

```bash theme={null}
pip install blobrouter
```

## Constructor

```python theme={null}
from blobrouter import BlobRouter

storage = BlobRouter(
    api_key="br_live_xxx",
    base_url="https://api.blobrouter.com",  # optional
    max_retries=3,  # optional, default 3
)
```

| Argument      | Default                      | Description               |
| ------------- | ---------------------------- | ------------------------- |
| `api_key`     | required                     | `br_live_…` / `br_test_…` |
| `base_url`    | `https://api.blobrouter.com` | API origin                |
| `max_retries` | `3`                          | Control-plane retries     |

## `upload(...)`

Accepts `bytes` **or** file-like `IO[bytes]`.

```python theme={null}
import os
from blobrouter import BlobRouter

storage = BlobRouter(api_key=os.environ["BLOBROUTER_API_KEY"])

with open("model_checkpoint.pt", "rb") as f:
    result = storage.upload(
        file=f,
        file_name="model_checkpoint.pt",
        content_type="application/octet-stream",
        file_size_bytes=os.path.getsize("model_checkpoint.pt"),
        priority="archive",
    )

print(result["file_id"], result["provider"], result["saved_vs_aws"])
```

**Returns** a dict:

| Key               | Type             |
| ----------------- | ---------------- |
| `file_id`         | `str`            |
| `url`             | `str`            |
| `provider`        | `str`            |
| `saved_vs_aws`    | `float`          |
| `routing_warning` | `str` (optional) |

Routing warnings are also emitted via Python’s `warnings.warn()`.

### Retry behavior

Same policy as TypeScript: retry API calls on network / `5xx` / `408` / `429`; never retry other `4xx`; never retry the provider PUT.

## PyTorch checkpoint example

```python theme={null}
import io
import os
import torch
from blobrouter import BlobRouter

storage = BlobRouter(api_key=os.environ["BLOBROUTER_API_KEY"])

buffer = io.BytesIO()
torch.save(model.state_dict(), buffer)
buffer.seek(0)

result = storage.upload(
    file=buffer,
    file_name="checkpoint_epoch_10.pt",
    content_type="application/octet-stream",
    file_size_bytes=buffer.getbuffer().nbytes,
    priority="archive",
)
print(result["file_id"], result["saved_vs_aws"])
```

## `get(file_id)` / `delete(file_id)`

```python theme={null}
got = storage.get(result["file_id"])
print(got["url"], got["expires_at"])

storage.delete(result["file_id"])
```

## Errors

```python theme={null}
from blobrouter import BlobRouter, BlobRouterError

try:
    storage.upload(...)
except BlobRouterError as err:
    print(err, err.code, err.status_code)
```

## Priority values

| Priority  | Typical route |
| --------- | ------------- |
| `hot`     | Cloudflare R2 |
| `cold`    | Cost formula  |
| `archive` | Backblaze B2  |