0
# Server-side API
1

2
Server-side blob operations designed for backend execution with full API access, higher upload limits, and comprehensive management capabilities.
3

4
## Capabilities
5

6
### Upload Operations
7

8
#### put
9

10
Uploads a blob to the store from server with extensive configuration options.
11

12
```typescript { .api }
13
/**
14
 * Uploads a blob into your store from your server
15
 * @param pathname - The pathname to upload the blob to, including the extension
16
 * @param body - The content of your blob (string, File, Blob, Buffer, Stream)
17
 * @param options - Configuration options
18
 * @returns Promise resolving to blob information
19
 */
20
function put(pathname: string, body: PutBody, options: PutCommandOptions): Promise<PutBlobResult>;
21

22
interface PutCommandOptions extends CommonCreateBlobOptions, WithUploadProgress {
23
  multipart?: boolean;
24
}
25

26
interface WithUploadProgress {
27
  onUploadProgress?: OnUploadProgressCallback;
28
}
29
```
30

31
**Usage Examples:**
32

33
```typescript
34
import { put } from '@vercel/blob';
35

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

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

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

57
// Upload with custom cache control
58
const result = await put('static/logo.png', logoFile, {
59
  access: 'public',
60
  cacheControlMaxAge: 86400, // 1 day in seconds
61
  allowOverwrite: true,
62
});
63
```
64

65
### Management Operations
66

67
#### del
68

69
Deletes one or multiple blobs from the store.
70

71
```typescript { .api }
72
/**
73
 * Deletes one or multiple blobs from the store
74
 * @param urlOrPathname - URL(s) or pathname(s) of blob(s) to delete
75
 * @param options - Configuration options
76
 * @returns Promise that resolves when deletion is complete
77
 */
78
function del(urlOrPathname: string | string[], options?: BlobCommandOptions): Promise<void>;
79
```
80

81
**Usage Examples:**
82

83
```typescript
84
import { del } from '@vercel/blob';
85

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

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

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

99
// Delete with custom token
100
await del('sensitive/data.json', {
101
  token: 'custom-token',
102
});
103
```
104

105
#### head
106

107
Fetches blob metadata without downloading the content.
108

109
```typescript { .api }
110
/**
111
 * Fetches blob metadata without downloading content
112
 * @param urlOrPathname - URL or pathname of the blob
113
 * @param options - Configuration options
114
 * @returns Promise resolving to blob metadata
115
 */
116
function head(urlOrPathname: string, options?: BlobCommandOptions): Promise<HeadBlobResult>;
117

118
interface HeadBlobResult {
119
  size: number;
120
  uploadedAt: Date;
121
  pathname: string;
122
  contentType: string;
123
  contentDisposition: string;
124
  url: string;
125
  downloadUrl: string;
126
  cacheControl: string;
127
}
128
```
129

130
**Usage Examples:**
131

132
```typescript
133
import { head } from '@vercel/blob';
134

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

141
// Check if blob exists (will throw error if not found)
142
try {
143
  await head('maybe-exists.txt');
144
  console.log('File exists');
145
} catch (error) {
146
  if (error instanceof BlobNotFoundError) {
147
    console.log('File does not exist');
148
  }
149
}
150
```
151

152
#### list
153

154
Lists blobs in the store with pagination and filtering options.
155

156
```typescript { .api }
157
/**
158
 * Lists blobs in the store
159
 * @param options - Listing configuration options
160
 * @returns Promise resolving to blob list
161
 */
162
function list(options?: ListCommandOptions): Promise<ListBlobResult | ListFoldedBlobResult>;
163

164
interface ListCommandOptions extends BlobCommandOptions {
165
  limit?: number;
166
  prefix?: string;
167
  cursor?: string;
168
  mode?: 'expanded' | 'folded';
169
}
170

171
interface ListBlobResult {
172
  blobs: ListBlobResultBlob[];
173
  cursor?: string;
174
  hasMore: boolean;
175
}
176

177
interface ListBlobResultBlob {
178
  url: string;
179
  downloadUrl: string;
180
  pathname: string;
181
  size: number;
182
  uploadedAt: Date;
183
}
184

185
interface ListFoldedBlobResult {
186
  blobs: ListBlobResultBlob[];
187
  folders: string[];
188
  cursor?: string;
189
  hasMore: boolean;
190
}
191
```
192

193
**Usage Examples:**
194

195
```typescript
196
import { list } from '@vercel/blob';
197

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

202
// List with pagination
203
const { blobs, cursor, hasMore } = await list({ limit: 10 });
204
if (hasMore) {
205
  const nextPage = await list({ limit: 10, cursor });
206
}
207

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

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

216
#### copy
217

218
Copies a blob to another location within the store.
219

220
```typescript { .api }
221
/**
222
 * Copies a blob to another location
223
 * @param fromUrlOrPathname - Source blob URL or pathname
224
 * @param toPathname - Destination pathname
225
 * @param options - Configuration options
226
 * @returns Promise resolving to copied blob information
227
 */
228
function copy(fromUrlOrPathname: string, toPathname: string, options: CopyCommandOptions): Promise<CopyBlobResult>;
229

230
type CopyCommandOptions = CommonCreateBlobOptions;
231

232
interface CopyBlobResult {
233
  url: string;
234
  downloadUrl: string;
235
  pathname: string;
236
  contentType: string;
237
  contentDisposition: string;
238
}
239
```
240

241
**Usage Examples:**
242

243
```typescript
244
import { copy } from '@vercel/blob';
245

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

251
// Copy with new content type
252
const result = await copy(
253
  'https://example.public.blob.vercel-storage.com/data.txt',
254
  'data/processed.json',
255
  {
256
    access: 'public',
257
    contentType: 'application/json',
258
  }
259
);
260

261
// Copy with random suffix
262
const result = await copy('templates/base.html', 'generated/page.html', {
263
  access: 'public',
264
  addRandomSuffix: true,
265
  allowOverwrite: false,
266
});
267
```
268

269
### Organization Operations
270

271
#### createFolder
272

273
Creates virtual folders for UI organization purposes.
274

275
```typescript { .api }
276
/**
277
 * Creates virtual folders in blob store for UI display purposes
278
 * @param pathname - Folder path (trailing slash added automatically)
279
 * @param options - Configuration options
280
 * @returns Promise resolving to folder information
281
 */
282
function createFolder(pathname: string, options?: BlobCommandOptions): Promise<CreateFolderResult>;
283

284
interface CreateFolderResult {
285
  pathname: string;
286
  url: string;
287
}
288
```
289

290
**Usage Examples:**
291

292
```typescript
293
import { createFolder } from '@vercel/blob';
294

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

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

302
// Create folder with custom token
303
await createFolder('private/sensitive', {
304
  token: 'custom-read-write-token',
305
});
306
```
307

308
### Utility Functions
309

310
#### getDownloadUrl
311

312
Generates a download URL that forces browsers to download the file instead of displaying it inline.
313

314
```typescript { .api }
315
/**
316
 * Generates a download URL for a blob
317
 * @param blobUrl - The URL of the blob to generate a download URL for
318
 * @returns Download URL with download parameter appended
319
 */
320
function getDownloadUrl(blobUrl: string): string;
321
```
322

323
**Usage Examples:**
324

325
```typescript
326
import { getDownloadUrl } from '@vercel/blob';
327

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

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

336
## Common Options
337

338
### PutCommandOptions
339

340
```typescript { .api }
341
interface PutCommandOptions extends CommonCreateBlobOptions, WithUploadProgress {
342
  multipart?: boolean;
343
}
344
```
345

346
### CommonCreateBlobOptions
347

348
```typescript { .api }
349
interface CommonCreateBlobOptions extends BlobCommandOptions {
350
  access: 'public';
351
  addRandomSuffix?: boolean;        // Add random suffix to filename
352
  allowOverwrite?: boolean;         // Allow overwriting existing blobs
353
  contentType?: string;             // MIME type (auto-detected if not provided)
354
  cacheControlMaxAge?: number;      // Cache duration in seconds (default: 1 month)
355
}
356
```
357

358
### BlobCommandOptions
359

360
```typescript { .api }
361
interface BlobCommandOptions {
362
  token?: string;                   // API token (defaults to BLOB_READ_WRITE_TOKEN)
363
  abortSignal?: AbortSignal;       // Abort signal for cancellation
364
}
365
```
366

367
## Result Types
368

369
### PutBlobResult
370

371
```typescript { .api }
372
interface PutBlobResult {
373
  url: string;                      // Direct access URL
374
  downloadUrl: string;              // Download URL (adds ?download=1)
375
  pathname: string;                 // Blob pathname in store
376
  contentType: string;              // MIME type
377
  contentDisposition: string;       // Content disposition header
378
}
379
```
380

381
## Constants
382

383
```typescript { .api }
384
const MAXIMUM_PATHNAME_LENGTH = 950;  // Maximum allowed pathname length
385
```