Server-side API

/**
 * Uploads a blob into your store from your server
 * @param pathname - The pathname to upload the blob to, including the extension
 * @param body - The content of your blob (string, File, Blob, Buffer, Stream)
 * @param options - Configuration options
 * @returns Promise resolving to blob information
 */
function put(pathname: string, body: PutBody, options: PutCommandOptions): Promise<PutBlobResult>;

interface PutCommandOptions extends CommonCreateBlobOptions, WithUploadProgress {
  multipart?: boolean;
}

interface WithUploadProgress {
  onUploadProgress?: OnUploadProgressCallback;
}

import { put } from '@vercel/blob';

// Basic file upload
const result = await put('documents/report.pdf', fileBuffer, {
  access: 'public',
});

// Upload with random suffix to avoid conflicts
const result = await put('images/photo.jpg', imageFile, {
  access: 'public',
  addRandomSuffix: true,
  contentType: 'image/jpeg',
});

// Upload with progress tracking
const result = await put('videos/large-video.mp4', videoFile, {
  access: 'public',
  multipart: true, // Use multipart for large files
  onUploadProgress: ({ loaded, total, percentage }) => {
    console.log(`Upload progress: ${percentage}%`);
  },
});

// Upload with custom cache control
const result = await put('static/logo.png', logoFile, {
  access: 'public',
  cacheControlMaxAge: 86400, // 1 day in seconds
  allowOverwrite: true,
});

/**
 * Deletes one or multiple blobs from the store
 * @param urlOrPathname - URL(s) or pathname(s) of blob(s) to delete
 * @param options - Configuration options
 * @returns Promise that resolves when deletion is complete
 */
function del(urlOrPathname: string | string[], options?: BlobCommandOptions): Promise<void>;

import { del } from '@vercel/blob';

// Delete a single blob by pathname
await del('documents/old-report.pdf');

// Delete a single blob by URL
await del('https://example.public.blob.vercel-storage.com/file.txt');

// Delete multiple blobs
await del([
  'temp/file1.txt',
  'temp/file2.txt',
  'https://example.public.blob.vercel-storage.com/file3.txt'
]);

// Delete with custom token
await del('sensitive/data.json', {
  token: 'custom-token',
});

/**
 * Fetches blob metadata without downloading content
 * @param urlOrPathname - URL or pathname of the blob
 * @param options - Configuration options
 * @returns Promise resolving to blob metadata
 */
function head(urlOrPathname: string, options?: BlobCommandOptions): Promise<HeadBlobResult>;

interface HeadBlobResult {
  size: number;
  uploadedAt: Date;
  pathname: string;
  contentType: string;
  contentDisposition: string;
  url: string;
  downloadUrl: string;
  cacheControl: string;
}

import { head } from '@vercel/blob';

// Get blob metadata
const metadata = await head('documents/report.pdf');
console.log(`File size: ${metadata.size} bytes`);
console.log(`Uploaded: ${metadata.uploadedAt.toISOString()}`);
console.log(`Content type: ${metadata.contentType}`);

// Check if blob exists (will throw error if not found)
try {
  await head('maybe-exists.txt');
  console.log('File exists');
} catch (error) {
  if (error instanceof BlobNotFoundError) {
    console.log('File does not exist');
  }
}

/**
 * Lists blobs in the store
 * @param options - Listing configuration options
 * @returns Promise resolving to blob list
 */
function list(options?: ListCommandOptions): Promise<ListBlobResult | ListFoldedBlobResult>;

interface ListCommandOptions extends BlobCommandOptions {
  limit?: number;
  prefix?: string;
  cursor?: string;
  mode?: 'expanded' | 'folded';
}

interface ListBlobResult {
  blobs: ListBlobResultBlob[];
  cursor?: string;
  hasMore: boolean;
}

interface ListBlobResultBlob {
  url: string;
  downloadUrl: string;
  pathname: string;
  size: number;
  uploadedAt: Date;
}

interface ListFoldedBlobResult {
  blobs: ListBlobResultBlob[];
  folders: string[];
  cursor?: string;
  hasMore: boolean;
}

import { list } from '@vercel/blob';

// List all blobs
const { blobs, hasMore } = await list();
console.log(`Found ${blobs.length} blobs`);

// List with pagination
const { blobs, cursor, hasMore } = await list({ limit: 10 });
if (hasMore) {
  const nextPage = await list({ limit: 10, cursor });
}

// List blobs with prefix filter
const { blobs } = await list({ prefix: 'images/' });

// List in folded mode to see folders
const { blobs, folders } = await list({ mode: 'folded' });
console.log('Folders:', folders);

/**
 * Copies a blob to another location
 * @param fromUrlOrPathname - Source blob URL or pathname
 * @param toPathname - Destination pathname
 * @param options - Configuration options
 * @returns Promise resolving to copied blob information
 */
function copy(fromUrlOrPathname: string, toPathname: string, options: CopyCommandOptions): Promise<CopyBlobResult>;

type CopyCommandOptions = CommonCreateBlobOptions;

interface CopyBlobResult {
  url: string;
  downloadUrl: string;
  pathname: string;
  contentType: string;
  contentDisposition: string;
}

import { copy } from '@vercel/blob';

// Basic copy operation
const result = await copy('images/original.jpg', 'images/backup.jpg', {
  access: 'public',
});

// Copy with new content type
const result = await copy(
  'https://example.public.blob.vercel-storage.com/data.txt',
  'data/processed.json',
  {
    access: 'public',
    contentType: 'application/json',
  }
);

// Copy with random suffix
const result = await copy('templates/base.html', 'generated/page.html', {
  access: 'public',
  addRandomSuffix: true,
  allowOverwrite: false,
});

/**
 * Creates virtual folders in blob store for UI display purposes
 * @param pathname - Folder path (trailing slash added automatically)
 * @param options - Configuration options
 * @returns Promise resolving to folder information
 */
function createFolder(pathname: string, options?: BlobCommandOptions): Promise<CreateFolderResult>;

interface CreateFolderResult {
  pathname: string;
  url: string;
}

import { createFolder } from '@vercel/blob';

// Create a folder
const result = await createFolder('documents/2024');
console.log(`Created folder: ${result.pathname}`); // "documents/2024/"

// Create nested folders
await createFolder('projects/web-app/assets');

// Create folder with custom token
await createFolder('private/sensitive', {
  token: 'custom-read-write-token',
});

/**
 * Generates a download URL for a blob
 * @param blobUrl - The URL of the blob to generate a download URL for
 * @returns Download URL with download parameter appended
 */
function getDownloadUrl(blobUrl: string): string;

import { getDownloadUrl } from '@vercel/blob';

const blobUrl = 'https://example.public.blob.vercel-storage.com/document.pdf';
const downloadUrl = getDownloadUrl(blobUrl);
// Result: 'https://example.public.blob.vercel-storage.com/document.pdf?download=1'

// Use in HTML
const link = `<a href="${downloadUrl}" download>Download PDF</a>`;

interface PutCommandOptions extends CommonCreateBlobOptions, WithUploadProgress {
  multipart?: boolean;
}

interface CommonCreateBlobOptions extends BlobCommandOptions {
  access: 'public';
  addRandomSuffix?: boolean;        // Add random suffix to filename
  allowOverwrite?: boolean;         // Allow overwriting existing blobs
  contentType?: string;             // MIME type (auto-detected if not provided)
  cacheControlMaxAge?: number;      // Cache duration in seconds (default: 1 month)
}

interface BlobCommandOptions {
  token?: string;                   // API token (defaults to BLOB_READ_WRITE_TOKEN)
  abortSignal?: AbortSignal;       // Abort signal for cancellation
}

interface PutBlobResult {
  url: string;                      // Direct access URL
  downloadUrl: string;              // Download URL (adds ?download=1)
  pathname: string;                 // Blob pathname in store
  contentType: string;              // MIME type
  contentDisposition: string;       // Content disposition header
}

const MAXIMUM_PATHNAME_LENGTH = 950;  // Maximum allowed pathname length