1# Cloudflare R2 Object Storage
2 
3S3-compatible object storage with zero egress fees, optimized for large file storage and delivery.
4 
5## Overview
6 
7R2 provides:
8- S3-compatible API (Workers API + S3 REST)
9- Zero egress fees globally
10- Strong consistency for writes/deletes
11- Storage classes (Standard/Infrequent Access)
12- SSE-C encryption support
13 
14**Use cases:** Media storage, backups, static assets, user uploads, data lakes
15 
16## Quick Start
17 
18```bash
19wrangler r2 bucket create my-bucket --location=enam
20wrangler r2 object put my-bucket/file.txt --file=./local.txt
21```
22 
23```typescript
24// Upload
25await env.MY_BUCKET.put(key, data, {
26  httpMetadata: { contentType: 'image/jpeg' }
27});
28 
29// Download
30const object = await env.MY_BUCKET.get(key);
31if (object) return new Response(object.body);
32```
33 
34## Core Operations
35 
36| Method | Purpose | Returns |
37|--------|---------|---------|
38| `put(key, value, options?)` | Upload object | `R2Object \| null` |
39| `get(key, options?)` | Download object | `R2ObjectBody \| R2Object \| null` |
40| `head(key)` | Get metadata only | `R2Object \| null` |
41| `delete(keys)` | Delete object(s) | `Promise<void>` |
42| `list(options?)` | List objects | `R2Objects` |
43 
44## Storage Classes
45 
46- **Standard**: Frequent access, low latency reads
47- **InfrequentAccess**: 30-day minimum storage, retrieval fees, lower storage cost
48 
49## Event Notifications
50 
51R2 integrates with Cloudflare Queues for reactive workflows:
52 
53```typescript
54// wrangler.jsonc
55{
56  "event_notifications": [{
57    "queue": "r2-notifications",
58    "actions": ["PutObject", "DeleteObject"]
59  }]
60}
61 
62// Consumer
63async queue(batch: MessageBatch, env: Env) {
64  for (const message of batch.messages) {
65    const event = message.body; // { action, bucket, object, timestamps }
66    if (event.action === 'PutObject') {
67      // Process upload: thumbnail generation, virus scan, etc.
68    }
69  }
70}
71```
72 
73## Reading Order
74 
75**First-time users:** README → configuration.md → api.md → patterns.md  
76**Specific tasks:**
77- Setup: configuration.md
78- Client uploads: patterns.md (presigned URLs)
79- Public static site: patterns.md (public access + custom domain)
80- Processing uploads: README (event notifications) + queues reference
81- Debugging: gotchas.md
82 
83## In This Reference
84 
85- [configuration.md](./configuration.md) - Bindings, S3 SDK, CORS, lifecycles, token scopes
86- [api.md](./api.md) - Workers API, multipart, conditional requests, presigned URLs
87- [patterns.md](./patterns.md) - Streaming, caching, client uploads, public buckets
88- [gotchas.md](./gotchas.md) - List truncation, etag format, stream length, S3 SDK region
89 
90## See Also
91 
92- [workers](../workers/) - Worker runtime and fetch handlers
93- [kv](../kv/) - Metadata storage for R2 objects
94- [d1](../d1/) - Store R2 URLs in relational database
95- [queues](../queues/) - Process R2 uploads asynchronously
96