REST API

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

Base URL: https://api.blobrouter.com Two auth styles:

API key — Authorization: Bearer br_live_… (SDK / router)
Dashboard JWT — Authorization: Bearer <supabase_access_token> (scanner, providers, analytics, billing, key rotate)

All JSON errors look like:

{ "error": "Human readable message", "code": "error_code" }

Responses include X-Request-ID. Rate limit exceeded returns 429 with Retry-After: 60.

Health

curl https://api.blobrouter.com/health

Router (API key)

Who am I

curl https://api.blobrouter.com/v1/me \
  -H "Authorization: Bearer $BLOBROUTER_API_KEY"

Init upload

curl -X POST https://api.blobrouter.com/v1/upload/init \
  -H "Authorization: Bearer $BLOBROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fileName": "example.jpg",
    "contentType": "image/jpeg",
    "fileSizeBytes": 12345,
    "priority": "hot"
  }'

Returns fileId, presignedUrl, provider, savedVsAws, optional routingWarning.

Complete upload

After you PUT the file to presignedUrl:

curl -X POST https://api.blobrouter.com/v1/upload/complete \
  -H "Authorization: Bearer $BLOBROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fileId":"FILE_UUID"}'

Get download URL

curl https://api.blobrouter.com/v1/file/FILE_UUID \
  -H "Authorization: Bearer $BLOBROUTER_API_KEY"

Delete file

curl -X DELETE https://api.blobrouter.com/v1/file/FILE_UUID \
  -H "Authorization: Bearer $BLOBROUTER_API_KEY"

Scanner (dashboard JWT)

Connect AWS

curl -X POST https://api.blobrouter.com/v1/scanner/connect \
  -H "Authorization: Bearer $DASHBOARD_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "roleArn": "arn:aws:iam::123456789012:role/BlobRouterScanner",
    "externalId": "YOUR_EXTERNAL_ID",
    "regions": ["us-east-1"]
  }'

Start scan

curl -X POST https://api.blobrouter.com/v1/scanner/scan \
  -H "Authorization: Bearer $DASHBOARD_JWT" \
  -H "Content-Type: application/json" \
  -d '{"connectionId":"CONNECTION_UUID"}'

Scan results

curl https://api.blobrouter.com/v1/scanner/results/SCAN_UUID \
  -H "Authorization: Bearer $DASHBOARD_JWT"

The JSON payload includes scan totals, buckets, and recommendations. When the Storage Decision Engine ran for that scan, the response also includes an additive decisionReport object (callouts, segment economics, and related fields). Older scans, or scans where the engine did not produce a report, omit decisionReport — legacy recommendations still appear. See Storage Decision Engine.

Scan history

curl https://api.blobrouter.com/v1/scanner/history \
  -H "Authorization: Bearer $DASHBOARD_JWT"

Approve recommendation

curl -X POST https://api.blobrouter.com/v1/scanner/recommendations/REC_UUID/approve \
  -H "Authorization: Bearer $DASHBOARD_JWT" \
  -H "Content-Type: application/json" \
  -d '{"targetProvider":"backblaze-b2"}'

Migration status

curl https://api.blobrouter.com/v1/scanner/migration/MIGRATION_UUID \
  -H "Authorization: Bearer $DASHBOARD_JWT"

Providers (dashboard JWT)

Save provider credentials

curl -X POST https://api.blobrouter.com/v1/providers \
  -H "Authorization: Bearer $DASHBOARD_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "cloudflare-r2",
    "accessKeyId": "...",
    "secretAccessKey": "...",
    "bucketName": "my-bucket",
    "region": "auto",
    "accountId": "CLOUDFLARE_ACCOUNT_ID"
  }'

Test provider

curl -X POST https://api.blobrouter.com/v1/providers/test \
  -H "Authorization: Bearer $DASHBOARD_JWT" \
  -H "Content-Type: application/json" \
  -d '{"provider":"cloudflare-r2"}'

Get API key

curl https://api.blobrouter.com/v1/providers/api-key \
  -H "Authorization: Bearer $DASHBOARD_JWT"

Regenerate API key

curl -X POST https://api.blobrouter.com/v1/providers/api-key/regenerate \
  -H "Authorization: Bearer $DASHBOARD_JWT" \
  -H "Content-Type: application/json" \
  -d '{}'

API key rotation (dashboard JWT)

Preferred rotation endpoint:

curl -X POST https://api.blobrouter.com/v1/keys/rotate \
  -H "Authorization: Bearer $DASHBOARD_JWT" \
  -H "Content-Type: application/json" \
  -d '{}'

Returns { "newApiKey": "br_live_…", "rotatedAt": "…" }. The previous key stops working immediately.

Analytics (dashboard JWT)

curl https://api.blobrouter.com/v1/analytics/summary \
  -H "Authorization: Bearer $DASHBOARD_JWT"

curl https://api.blobrouter.com/v1/analytics/monthly \
  -H "Authorization: Bearer $DASHBOARD_JWT"

curl "https://api.blobrouter.com/v1/analytics/routing-history?limit=10&offset=0" \
  -H "Authorization: Bearer $DASHBOARD_JWT"

Billing (dashboard JWT)

curl -X POST https://api.blobrouter.com/v1/billing/checkout \
  -H "Authorization: Bearer $DASHBOARD_JWT" \
  -H "Content-Type: application/json" \
  -d '{"plan":"starter"}'

curl -X POST https://api.blobrouter.com/v1/billing/portal \
  -H "Authorization: Bearer $DASHBOARD_JWT" \
  -H "Content-Type: application/json" \
  -d '{}'

Getting Started

Guides

Examples

SDK Reference

API

Concepts

Billing

Product

Health

Router (API key)

Who am I

Init upload

Complete upload

Get download URL

Delete file

Scanner (dashboard JWT)

Connect AWS

Start scan

Scan results

Scan history

Approve recommendation

Migration status

Providers (dashboard JWT)

Save provider credentials

Test provider

Get API key

Regenerate API key

API key rotation (dashboard JWT)

Analytics (dashboard JWT)

Billing (dashboard JWT)

​Health

​Router (API key)

​Who am I

​Init upload

​Complete upload

​Get download URL

​Delete file

​Scanner (dashboard JWT)

​Connect AWS

​Start scan

​Scan results

​Scan history

​Approve recommendation

​Migration status

​Providers (dashboard JWT)

​Save provider credentials

​Test provider

​Get API key

​Regenerate API key

​API key rotation (dashboard JWT)

​Analytics (dashboard JWT)

​Billing (dashboard JWT)

​Related

Health

Router (API key)

Who am I

Init upload

Complete upload

Get download URL

Delete file

Scanner (dashboard JWT)

Connect AWS

Start scan

Scan results

Scan history

Approve recommendation

Migration status

Providers (dashboard JWT)

Save provider credentials

Test provider

Get API key

Regenerate API key

API key rotation (dashboard JWT)

Analytics (dashboard JWT)

Billing (dashboard JWT)

Related