Quickstart — First upload in 5 minutes

Install the SDK, connect a provider, and upload your first file through BlobRouter.

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

BlobRouter is a cloud optimization platform that starts with storage. This quickstart gets you to a successful routed upload. If you have not run an audit yet, start there instead.

New to BlobRouter? Start with the free AWS storage audit instead.

Connect AWS  →  Audit
Expected time ≈ 2 minutes

See your storage waste before installing the SDK.

Prerequisites

• An AWS account (for the free audit and/or S3 as a routing target)
• Node.js 18 or later
• A BlobRouter account at app.blobrouter.com

1. Install the SDK

npm install @blobrouter/sdk

2. Get your API key

1. Open the dashboard
2. Go to Providers → API key
3. Copy your key (br_live_…)

export BLOBROUTER_API_KEY=br_live_your_key_here

3. Connect at least one provider

Routing needs credentials for the providers you want to use (AWS S3, Cloudflare R2, and/or Backblaze B2).

• Prefer R2 for hot files → Connect Cloudflare R2
• Prefer B2 for archive → Connect Backblaze B2
• Still exploring waste on existing S3? → Connect AWS for audit

Save credentials in the dashboard under Providers. Keys are encrypted at rest (AES-256-GCM). BlobRouter never hosts your object bytes.

4. First upload

Create upload.mjs next to an example.jpg file:

import { BlobRouter } from "@blobrouter/sdk";
import { readFileSync } from "fs";

const storage = new BlobRouter({
  apiKey: process.env.BLOBROUTER_API_KEY,
});

const file = readFileSync("./example.jpg");

const result = await storage.upload(file, {
  fileName: "example.jpg",
  contentType: "image/jpeg",
  fileSizeBytes: file.length,
  priority: "hot", // routes to Cloudflare R2 when configured (zero egress)
});

console.log(`Routed to: ${result.provider}`);
console.log(`Saved vs AWS S3: $${result.savedVsAws.toFixed(4)}`);
console.log(`File ID: ${result.fileId}`);

Run it:

node upload.mjs

What happens under the hood — see Request lifecycle:

1. SDK calls POST /v1/upload/init
2. BlobRouter picks a provider and returns a presigned PUT URL
3. SDK uploads directly to the provider (BlobRouter never sees the bytes)
4. SDK calls POST /v1/upload/complete so BlobRouter can verify and record savings

5. View your savings

Open the dashboard → Savings to see routed files, estimated savings vs AWS S3, and provider mix.

Next steps

• Request lifecycle
• Architecture decisions
• Examples
• TypeScript SDK