Upstash Blob Quickstart - Upstash Documentation

Building with an AI coding agent?

Run npx upstash to install the Upstash MCP server and skills in Claude Code, Cursor, Codex, and other agents.

Upstash Blob is S3-compatible object storage. Each server SDK has a bucket client and an upload handler, and @upstash/blob has React hooks that upload from the browser straight to storage. This page builds a working file picker in React. The server code is Next.js App Router in TypeScript, FastAPI in Python, or net/http in Go. Other frameworks work the same way; see Other frameworks in TypeScript, Mounting it in Python and Mounting it in Go.

Setup#

npm install @upstash/blob

pnpm add @upstash/blob

yarn add @upstash/blob

bun add @upstash/blob

pip install upstash-blob

uv add upstash-blob

go get github.com/upstash/blob-go

upstash-blob is the Python server SDK and github.com/upstash/blob-go the Go one. The browser side is @upstash/blob whichever language runs the server, so a Python or Go app installs both.

Create a bucket in the Upstash Console and put its token in your environment.

.env

UPSTASH_BLOB_TOKEN=...

The console asks whether the bucket is public or private:

Public: every object has a public URL. For avatars, product images, anything a page links to directly.
Private: no public URL. Every read goes through a time-limited signed URL. For user documents, invoices, anything that must not be guessable.

Upload from your server#

// lib/reports.tsimport { Bucket } from "@upstash/blob"const bucket = Bucket.fromEnv()export async function saveReport(file: Blob) {  const blob = await bucket.put("reports/2026-01.pdf", file, {    contentType: "application/pdf",  })  return blob.url}

# app/reports.pyfrom pathlib import Pathfrom upstash_blob import Bucketbucket = Bucket.from_env()def save_report(pdf: Path) -> str | None:    blob = bucket.put("reports/2026-01.pdf", pdf, content_type="application/pdf")    return blob.url

// reports.gopackage reportsimport (	"context"	"os"	blob "github.com/upstash/blob-go")func SaveReport(	ctx context.Context, bucket *blob.Bucket, pdf *os.File,) (string, error) {	b, err := bucket.Put(ctx, "reports/2026-01.pdf", pdf, &blob.PutOptions{		ContentType: "application/pdf",	})	if err != nil {		return "", err	}	return b.URL, nil}

Bytes already on your server go to the bucket with put. The returned record’s URL is the public object URL, not set on a private bucket. See Writing, and the TypeScript SDK, Python SDK or Go SDK for setup details.

Upload from the browser#

Files a user picks go straight from the browser to storage. Your server only authorizes the upload and records the result, so the bytes never pass through it.

Write the upload handler

// lib/uploads.tsimport "server-only"import { uploadHandler } from "@upstash/blob"export const uploads = uploadHandler({  constraints: {    maxSize: "20mb",    contentTypes: ["image/*", "application/pdf"],  },  onBeforeUpload: ({ file }) => ({ path: `images/${file.name}` }),})

# app/uploads.pyfrom upstash_blob import AsyncUploadHandler, BeforeUploadResultuploads = AsyncUploadHandler(    max_size="20mb",    content_types=["image/*", "application/pdf"],    on_before_upload=lambda args: BeforeUploadResult(path=f"images/{args.file.name}"),)

// uploads.gouploads, err := blob.NewUploadHandler(blob.UploadHandlerOptions[struct{}]{	MaxSize:      20 * blob.MB,	ContentTypes: []string{"image/*", "application/pdf"},	OnBeforeUpload: func(		a blob.BeforeUploadArgs[struct{}],	) (blob.BeforeUploadResult, error) {		return blob.BeforeUploadResult{Path: "images/" + a.File.Name}, nil	},})

The handler runs on your server. It decides who may upload, where the object goes, and what happens once it lands. It never sees the bytes.

This one accepts anyone. Upload handler adds the auth check and the completion callback.

Mount it as a route

// app/api/upload/route.tsimport { uploads } from "@/lib/uploads"export const { GET, POST } = uploads

# app/main.py (FastAPI)from fastapi import FastAPIfrom upstash_blob.fastapi import upload_viewfrom app.uploads import uploadsapp = FastAPI()app.add_api_route("/api/upload", upload_view(uploads), methods=["GET", "POST"])

// main.gohttp.Handle("/api/upload", uploads)log.Fatal(http.ListenAndServe(":8080", nil))

POST runs the upload and GET serves the route’s constraints. The hooks look at /api/upload by default, so nothing else has to name a URL.

Bind the hooks to the handler

lib/upload-hooks.ts

"use client"import { uploadHooks } from "@upstash/blob/react"import type { uploads } from "./uploads"export const { useUpload } = uploadHooks<typeof uploads>()

uploadHooks<typeof uploads>() reads the handler’s type, so route names and completion data are checked at compile time. The import type is erased at build time and never pulls server code into the browser bundle.

A Python or Go handler has no type to bind to. Call uploadHooks() with no type parameter and pass the URL, useUpload("/api/upload"), in the next step. FastAPI + React has the whole app, including the dev proxy that puts /api on the page’s origin.

Upload a file

app/page.tsx

"use client"import { useUpload } from "@/lib/upload-hooks"export default function Page() {  const { start, upload, accept } = useUpload()  return (    <div>      <input        type="file"        accept={accept}        onChange={(e) => start({ file: e.target.files?.[0] })}      />      {upload && <p>{upload.status}</p>}      {upload?.pending && <progress value={upload.percent} max={100} />}      {upload?.status === "done" && (        <a href={upload.blob.url}>{upload.blob.path}</a>      )}      {upload?.status === "error" && <p>{upload.error.message}</p>}    </div>  )}

You get these without more code:

Multipart for large files. Past 16 MB the SDK switches to parts, with pause, resume and per-part retry. See Large files.
Retries. Failed parts back off and retry, and an expired signature is refreshed mid-upload.
A picker that matches the server. accept comes from the route’s own GET, so an oversized file is refused before any request goes out. See Constraints.
Progress. percent, status and pending read the same for one PUT or 200 parts.
Types end to end. With a TypeScript handler, whatever onUploadComplete returns is upload.blob.data on the client, typed.

Next steps#

Upload handler

Auth, routes, and the completion callback in full.

Upload client

useUpload, the record it renders, and the non-React client.

Writing

put, metadata, conditional writes and multipart from the server.

Recipes

Avatars, attachments and private documents, wired end to end.