Bucket API - Upstash Documentation

The Bucket methods, their TypeScript options and what they return. Each section links to the concept page with the behaviour and defaults.

lib/blob.ts

import { Bucket } from "@upstash/blob"export const bucket = Bucket.fromEnv()

Building the client is on Overview. Every method runs on your server with the bucket token.

put#

put(path: string, body: PutBody, options?: PutOptions): Promise<CompletedBlob>

lib/reports.ts

import { bucket } from "@/lib/blob"export async function saveReport(pdf: Blob) {  const blob = await bucket.put("reports/q3.pdf", pdf, { contentType: "application/pdf" })  return blob.url}

Every option is optional. Behaviour and defaults are on Writing.

Option	Type	Description
`contentType`	`string`	What the object is stored as.
`contentTypes`	`string[]`	An allow list such as `["image/*", "application/pdf"]`. See Constraints.
`maxSize`	`Size`	Refuses a larger body with `too_large`.
`cache`	`CacheOption`	The `Cache-Control` this object is stored with. See Caching.
`metadata`	`Record<string, string>`	Custom key-value pairs. See Metadata.
`size`	`number`	The exact length in bytes, for a stream whose size is not otherwise known.
`allowOverwrite`	`boolean`	`false` refuses the write if something is already at the path. See Conditional writes.
`ifUnchanged`	`string`	An etag. The write fails with `conflict` if the object changed since you read it.
`multipart`	`boolean \| Size`	Where a body stops being one PUT. See Large bodies.

The result is a CompletedBlob:

const blob = await bucket.put("avatars/7.png", file, { contentType: "image/png" })blob.path          // 'avatars/7.png'blob.url           // https://b3f9a2c7d1e4.blob.upstash.io/avatars/7.pngblob.versionedUrl  // ...?v=%22d41d8...%22blob.size          // bytes storedblob.etag          // '"d41d8..."', what ifUnchanged takesblob.uploadedAt    // Dateblob.contentType   // 'image/png'

Bodies#

app/api/avatar/route.ts

import { bucket } from "@/lib/blob"export async function POST(request: Request) {  // A Request carries its own length and type, so nothing has to be declared.  const blob = await bucket.put("avatars/me.png", request, {    contentTypes: ["image/*"],    maxSize: "5mb",  })  return Response.json({ url: blob.url })}

PutBody is one of these. If the body does not carry its own length or type, declare size or contentType yourself.

Body	Carries its length	Carries a content type
`Request`	From its `content-length` header	From its `content-type` header
`Blob` / `File`	Yes	Yes, when `type` is set
`ArrayBuffer`	Yes	No
Typed array	Yes	No
`string`	Yes, once UTF-8 encoded	No
`ReadableStream<Uint8Array>`	No	No

An explicit contentType wins over what the body carries.

A Request with no body, or one that has already been read, throws empty_body. Anything else is a TypeError. A Request that arrived chunked has no content-length and counts as an unknown length, like a stream.

Streams#

// Buffer up to the cap. A stream that runs past it is cancelled with too_large.await bucket.put("export.csv", stream, { maxSize: "10mb" })// Stream straight through, nothing buffered. The declared size must be exact.await bucket.put("export.csv", stream, { size: 5000 })

A ReadableStream with neither throws length_required. Why is on Streams and unknown lengths.

uniquePath#

uniquePath(path: string): string

import { uniquePath } from "@upstash/blob"uniquePath(`users/${userId}/${file.name}`) // 'users/Alice_123/Q3 Report-3xK9mBqR.pdf'

Exported from @upstash/blob. The suffix rules are on Unique paths.

updateJson#

updateJson<T = unknown>(  path: string,  fn: (prev: T | null) => T | Promise<T>,  options?: UpdateJsonOptions,): Promise<BlobObject>

interface Settings {  theme: string}await bucket.updateJson<Settings>(  "u/7.json",  (prev) => ({ ...(prev ?? {}), theme: "dark" }),  { maxAttempts: 10, metadata: { owner: "u7" }, cache: "no-store" },)

Option	Type	Description
`maxAttempts`	`number`	How many read-transform-write rounds to try before throwing `conflict`.
`cache`	`CacheOption`	The `Cache-Control` the rewritten object is stored with.
`metadata`	`Record<string, string>`	Replaces the metadata on the object.

The loop and its defaults are on Updating JSON.

copy and move#

copy(from: string, to: string, options?: CopyOptions): Promise<BlobObject>move(from: string, to: string, options?: CopyOptions): Promise<BlobObject>

const archived = await bucket.copy("tmp/9f3c", "archive/2026/report.pdf")const moved = await bucket.move("tmp/9f3c", "reports/q3.pdf", { contentType: "application/pdf" })

Option	Type	Description
`contentType`	`string`	What the destination is stored as.
`cache`	`CacheOption`	The `Cache-Control` the destination is stored with.
`metadata`	`Record<string, string>`	Replaces the metadata outright.

What carries over from the source is on copy and move.

signedUploadUrl#

signedUploadUrl(path: string, options?: SignedUploadUrlOptions): Promise<SignedUploadUrl>

const upload = await bucket.signedUploadUrl("u/7/report.pdf", {  contentType: "application/pdf",  size: pdf.size,  expiresIn: "10m",})await fetch(upload.url, { method: "PUT", headers: upload.headers, body: pdf })

Returns { url: string, headers: Record<string, string>, expiresAt: Date }. Send headers verbatim.

Option	Type	Description
`expiresIn`	`Duration`	How long the link should live.
`contentType`	`string`	The `Content-Type` the upload must send, and what the object is stored as.
`cache`	`CacheOption`	The `Cache-Control` the object is stored with.
`metadata`	`Record<string, string>`	Written as `x-amz-meta-*`, under the same rules as `put`.
`size`	`Size`	Pins the body’s exact length.
`allowOverwrite`	`boolean`	`false` refuses the upload if something is already at the path.

Defaults and lifetimes are on Signed upload URLs.

get#

get(path: string): Promise<BlobDownload>

const res = await bucket.get("reports/2026-01.pdf")res.contentType  // 'application/pdf'res.size         // 184_302res.etag         // '"9f3c..."'res.metadata     // { owner: 'u7' }res.body         // ReadableStream<Uint8Array>

body is a ReadableStream<Uint8Array> and nothing is buffered for you. Wrap it in a Response for the usual conversions:

const text = await new Response((await bucket.get("notes/1.md")).body).text()const buffer = await new Response((await bucket.get("img/1.png")).body).arrayBuffer()

A missing object throws not_found. See get.

info and exists#

info(path: string): Promise<BlobInfo>exists(path: string): Promise<boolean>

const info = await bucket.info("reports/2026-01.pdf")info.size         // 184_302info.etag         // '"9f3c..."'info.contentType  // 'application/pdf'info.metadata     // { owner: 'u7' }info.uploadedAt   // Dateif (await bucket.exists("avatars/u7.png")) {  // ...}

See info and exists.

list#

list(options?: ListOptions): Promise<ListPage>

let cursor: string | undefinedconst paths: string[] = []do {  const page = await bucket.list({ prefix: "avatars/", limit: 1000, cursor })  for (const blob of page.blobs) paths.push(blob.path)  cursor = page.cursor} while (cursor)

Returns { blobs: BlobObject[], cursor: string | undefined }.

Option	Type	Description
`prefix`	`string`	Only keys starting with this.
`limit`	`number`	Page size.
`cursor`	`string`	The `cursor` from the previous page.

Defaults and paging are on list.

publicUrl#

publicUrl(path: string): Promise<string | undefined>

await bucket.publicUrl("avatars/u7.png")// 'https://b0f3a91c24d.blob.upstash.io/avatars/u7.png'

undefined on a private bucket. An empty path, or one with a . or .. segment, throws a TypeError. See Public URLs.

signedReadUrl#

signedReadUrl(path: string, options?: SignedReadUrlOptions): Promise<SignedReadUrl>

const { url, expiresAt } = await bucket.signedReadUrl("reports/2026-01.pdf", {  expiresIn: "2m",  downloadAs: "Report Q3.pdf",})

Returns { url: string, expiresAt: Date }. Cache the link until expiresAt, never until a deadline you compute from expiresIn.

Option	Type	Description
`expiresIn`	`Duration`	How long to ask for.
`downloadAs`	`string`	Save as this filename instead of displaying inline.
`contentType`	`string`	What storage answers with as `Content-Type`, overriding what was stored.

Defaults and lifetimes are on Signed read URLs.

del#

del(target: DeleteTarget): Promise<void>type DeleteTarget = string | string[] | { prefix: string; all?: boolean }

await bucket.del("avatars/me.png")                   // one pathawait bucket.del(["a.png", "b.png", "c.png"])        // an array of pathsawait bucket.del({ prefix: "tmp/" })                 // everything under a prefixawait bucket.del({ prefix: "", all: true })          // the whole bucket, on purpose

Anything else is refused with invalid_input. A path with a . or .. segment throws a TypeError. What each shape does and throws is on Deleting.

import { BlobError } from "@upstash/blob"try {  await bucket.del(paths)} catch (e) {  if (BlobError.is(e) && e.code === "partial_delete") {    await requeue(e.failed ?? []) // the paths still in the bucket    return  }  throw e}

Multipart cleanup#

listMultipartUploads(options?: { prefix?: string }): Promise<MultipartUpload[]>abortMultipartUpload(upload: { path: string; uploadId: string }): Promise<void>abortStaleMultipartUploads(options: { olderThan: Duration; prefix?: string }): Promise<MultipartUpload[]>interface MultipartUpload {  path: string  uploadId: string  initiatedAt: Date}

const uploads = await bucket.listMultipartUploads({ prefix: "uploads/" })await bucket.abortMultipartUpload({ path: "uploads/big.mp4", uploadId: "ABC..." })const aborted = await bucket.abortStaleMultipartUploads({ olderThan: "1d", prefix: "uploads/" })

olderThan is required. See Incomplete multipart uploads.

s3#

s3(): S3Config

A config for @aws-sdk/client-s3. See Using an S3 client.

Records#

Four record types come back from the SDK. They nest. What each field means is on Records.

Type	Fields	Returned by
`BlobObject`	`path`, `url?`, `versionedUrl?`, `size`, `etag`, `uploadedAt`	`list()`, `copy()`, `move()`, `updateJson()`
`CompletedBlob`	`BlobObject` plus `contentType`	`put()`, `onUploadComplete`, a finished browser upload
`BlobInfo`	`BlobObject` plus `contentType` and `metadata`	`info()`
`BlobDownload`	`BlobInfo` plus `body: ReadableStream<Uint8Array>`	`get()`

Field	Type
`path`	`string`
`url`	`string \| undefined`
`versionedUrl`	`string \| undefined`
`size`	`number`
`etag`	`string`
`uploadedAt`	`Date`
`contentType`	`string`
`metadata`	`Record<string, string>`

All four are exported as types from @upstash/blob.