Request lifecycle

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

​

Related

• Architecture
• Retries
• TypeScript SDK