1# R2 API Reference
2 
3## PUT (Upload)
4 
5```typescript
6// Basic
7await env.MY_BUCKET.put(key, value);
8 
9// With metadata
10await env.MY_BUCKET.put(key, value, {
11  httpMetadata: {
12    contentType: 'image/jpeg',
13    contentDisposition: 'attachment; filename="photo.jpg"',
14    cacheControl: 'max-age=3600'
15  },
16  customMetadata: { userId: '123', version: '2' },
17  storageClass: 'Standard', // or 'InfrequentAccess'
18  sha256: arrayBufferOrHex, // Integrity check
19  ssecKey: arrayBuffer32bytes // SSE-C encryption
20});
21 
22// Value types: ReadableStream | ArrayBuffer | string | Blob
23```
24 
25## GET (Download)
26 
27```typescript
28const object = await env.MY_BUCKET.get(key);
29if (!object) return new Response('Not found', { status: 404 });
30 
31// Body: arrayBuffer(), text(), json(), blob(), body (ReadableStream)
32 
33// Ranged reads
34const object = await env.MY_BUCKET.get(key, { range: { offset: 0, length: 1024 } });
35 
36// Conditional GET
37const object = await env.MY_BUCKET.get(key, { onlyIf: { etagMatches: '"abc123"' } });
38```
39 
40## HEAD (Metadata Only)
41 
42```typescript
43const object = await env.MY_BUCKET.head(key); // Returns R2Object without body
44```
45 
46## DELETE
47 
48```typescript
49await env.MY_BUCKET.delete(key);
50await env.MY_BUCKET.delete([key1, key2, key3]); // Batch (max 1000)
51```
52## LIST
53 
54```typescript
55const listed = await env.MY_BUCKET.list({
56  limit: 1000,
57  prefix: 'photos/',
58  cursor: cursorFromPrevious,
59  delimiter: '/',
60  include: ['httpMetadata', 'customMetadata']
61});
62 
63// Pagination (always use truncated flag)
64while (listed.truncated) {
65  const next = await env.MY_BUCKET.list({ cursor: listed.cursor });
66  listed.objects.push(...next.objects);
67  listed.truncated = next.truncated;
68  listed.cursor = next.cursor;
69}
70```
71 
72## Multipart Uploads
73 
74```typescript
75const multipart = await env.MY_BUCKET.createMultipartUpload(key, {
76  httpMetadata: { contentType: 'video/mp4' }
77});
78 
79const uploadedParts: R2UploadedPart[] = [];
80for (let i = 0; i < partCount; i++) {
81  const part = await multipart.uploadPart(i + 1, partData);
82  uploadedParts.push(part);
83}
84 
85const object = await multipart.complete(uploadedParts);
86// OR: await multipart.abort();
87 
88// Resume
89const multipart = env.MY_BUCKET.resumeMultipartUpload(key, uploadId);
90```
91 
92## Presigned URLs (S3 SDK)
93 
94```typescript
95import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';
96import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
97 
98const s3 = new S3Client({
99  region: 'auto',
100  endpoint: `https://${accountId}.r2.cloudflarestorage.com`,
101  credentials: { accessKeyId: env.R2_ACCESS_KEY_ID, secretAccessKey: env.R2_SECRET_ACCESS_KEY }
102});
103 
104const uploadUrl = await getSignedUrl(s3, new PutObjectCommand({ Bucket: 'my-bucket', Key: key }), { expiresIn: 3600 });
105return Response.json({ uploadUrl });
106```
107 
108## TypeScript Interfaces
109 
110```typescript
111interface R2Bucket {
112  head(key: string): Promise<R2Object | null>;
113  get(key: string, options?: R2GetOptions): Promise<R2ObjectBody | null>;
114  put(key: string, value: ReadableStream | ArrayBuffer | string | Blob, options?: R2PutOptions): Promise<R2Object | null>;
115  delete(keys: string | string[]): Promise<void>;
116  list(options?: R2ListOptions): Promise<R2Objects>;
117  createMultipartUpload(key: string, options?: R2MultipartOptions): Promise<R2MultipartUpload>;
118  resumeMultipartUpload(key: string, uploadId: string): R2MultipartUpload;
119}
120 
121interface R2Object {
122  key: string; version: string; size: number;
123  etag: string; httpEtag: string; // httpEtag is quoted, use for headers
124  uploaded: Date; httpMetadata?: R2HTTPMetadata;
125  customMetadata?: Record<string, string>;
126  storageClass: 'Standard' | 'InfrequentAccess';
127  checksums: R2Checksums;
128  writeHttpMetadata(headers: Headers): void;
129}
130 
131interface R2ObjectBody extends R2Object {
132  body: ReadableStream; bodyUsed: boolean;
133  arrayBuffer(): Promise<ArrayBuffer>; text(): Promise<string>;
134  json<T>(): Promise<T>; blob(): Promise<Blob>;
135}
136 
137interface R2HTTPMetadata {
138  contentType?: string; contentDisposition?: string;
139  contentEncoding?: string; contentLanguage?: string;
140  cacheControl?: string; cacheExpiry?: Date;
141}
142 
143interface R2PutOptions {
144  httpMetadata?: R2HTTPMetadata | Headers;
145  customMetadata?: Record<string, string>;
146  sha256?: ArrayBuffer | string; // Only ONE checksum allowed
147  storageClass?: 'Standard' | 'InfrequentAccess';
148  ssecKey?: ArrayBuffer;
149}
150 
151interface R2GetOptions {
152  onlyIf?: R2Conditional | Headers;
153  range?: R2Range | Headers;
154  ssecKey?: ArrayBuffer;
155}
156 
157interface R2ListOptions {
158  limit?: number; prefix?: string; cursor?: string; delimiter?: string;
159  startAfter?: string; include?: ('httpMetadata' | 'customMetadata')[];
160}
161 
162interface R2Objects {
163  objects: R2Object[]; truncated: boolean;
164  cursor?: string; delimitedPrefixes: string[];
165}
166 
167interface R2Conditional {
168  etagMatches?: string; etagDoesNotMatch?: string;
169  uploadedBefore?: Date; uploadedAfter?: Date;
170}
171 
172interface R2Range { offset?: number; length?: number; suffix?: number; }
173 
174interface R2Checksums {
175  md5?: ArrayBuffer; sha1?: ArrayBuffer; sha256?: ArrayBuffer;
176  sha384?: ArrayBuffer; sha512?: ArrayBuffer;
177}
178 
179interface R2MultipartUpload {
180  key: string;
181  uploadId: string;
182  uploadPart(partNumber: number, value: ReadableStream | ArrayBuffer | string | Blob): Promise<R2UploadedPart>;
183  abort(): Promise<void>;
184  complete(uploadedParts: R2UploadedPart[]): Promise<R2Object>;
185}
186 
187interface R2UploadedPart {
188  partNumber: number;
189  etag: string;
190}
191```
192 
193## CLI Operations
194 
195```bash
196wrangler r2 object put my-bucket/file.txt --file=./local.txt
197wrangler r2 object get my-bucket/file.txt --file=./download.txt
198wrangler r2 object delete my-bucket/file.txt
199wrangler r2 object list my-bucket --prefix=photos/
200```
201