Cloudflare R2 is an S3-compatible object storage service with zero egress fees. Use the API to manage buckets and configure storage settings.
Overview
Access the R2 API:
import Cloudflare from 'cloudflare';
const client = new Cloudflare({
apiToken: process.env.CLOUDFLARE_API_TOKEN,
});
// Access R2 resources
const r2 = client.r2;
Buckets
Manage R2 storage buckets.
Create a bucket
Create a new R2 bucket.
const bucket = await client.r2.buckets.create({
account_id: '023e105f4ecef8ad9ca31a8372d0c353',
name: 'my-bucket',
});
Your Cloudflare account ID
Bucket name (3-63 characters, lowercase, alphanumeric, and hyphens)
Data jurisdiction for the bucket (e.g., ‘eu’ for EU data residency)
Storage class: ‘Standard’ or ‘InfrequentAccess’
ISO 8601 timestamp when the bucket was created
The bucket’s location/jurisdiction
List buckets
Retrieve all R2 buckets in your account.
const buckets = await client.r2.buckets.list({
account_id: '023e105f4ecef8ad9ca31a8372d0c353',
});
Your Cloudflare account ID
Filter buckets by jurisdiction
Number of buckets per page (default: 1000, max: 1000)
Get a bucket
Retrieve details about a specific bucket.
const bucket = await client.r2.buckets.get(
'my-bucket',
{ account_id: '023e105f4ecef8ad9ca31a8372d0c353' }
);
Your Cloudflare account ID
Update a bucket
Update bucket configuration.
const bucket = await client.r2.buckets.edit(
'my-bucket',
{
account_id: '023e105f4ecef8ad9ca31a8372d0c353',
storage_class: 'InfrequentAccess',
}
);
Your Cloudflare account ID
Storage class: ‘Standard’ or ‘InfrequentAccess’
Delete a bucket
Delete an R2 bucket. The bucket must be empty.
await client.r2.buckets.delete(
'my-bucket',
{ account_id: '023e105f4ecef8ad9ca31a8372d0c353' }
);
The bucket name to delete
Your Cloudflare account ID
CORS
Manage Cross-Origin Resource Sharing (CORS) policies.
Get CORS configuration
Retrieve the CORS configuration for a bucket.
const cors = await client.r2.buckets.cors.get(
'my-bucket',
{ account_id: '023e105f4ecef8ad9ca31a8372d0c353' }
);
Update CORS configuration
Set CORS rules for a bucket.
const cors = await client.r2.buckets.cors.update(
'my-bucket',
{
account_id: '023e105f4ecef8ad9ca31a8372d0c353',
rules: [
{
allowed_origins: ['https://example.com'],
allowed_methods: ['GET', 'PUT'],
allowed_headers: ['*'],
max_age_seconds: 3600,
},
],
}
);
Array of CORS rule objects
Array of allowed origin URLs
Array of allowed HTTP methods
Array of allowed headers (use [’*’] for all headers)
Cache duration for preflight requests in seconds
Delete CORS configuration
Remove CORS configuration from a bucket.
await client.r2.buckets.cors.delete(
'my-bucket',
{ account_id: '023e105f4ecef8ad9ca31a8372d0c353' }
);
Lifecycle policies
Manage object lifecycle rules.
Get lifecycle configuration
const lifecycle = await client.r2.buckets.lifecycle.get(
'my-bucket',
{ account_id: '023e105f4ecef8ad9ca31a8372d0c353' }
);
Update lifecycle configuration
Set lifecycle rules to automatically delete or transition objects.
const lifecycle = await client.r2.buckets.lifecycle.update(
'my-bucket',
{
account_id: '023e105f4ecef8ad9ca31a8372d0c353',
rules: [
{
id: 'delete-old-logs',
status: 'Enabled',
prefix: 'logs/',
expiration: {
days: 30,
},
},
],
}
);
Array of lifecycle rule objects
Unique identifier for the rule
Rule status: ‘Enabled’ or ‘Disabled’
Object key prefix to match
Number of days after which objects expire
Event notifications
Configure event notifications to trigger Workers or send to queues.
Get event notifications
const notifications = await client.r2.buckets.eventNotifications.get(
'my-bucket',
{ account_id: '023e105f4ecef8ad9ca31a8372d0c353' }
);
Update event notifications
const notifications = await client.r2.buckets.eventNotifications.update(
'my-bucket',
{
account_id: '023e105f4ecef8ad9ca31a8372d0c353',
rules: [
{
prefix: 'uploads/',
suffix: '.jpg',
actions: ['PutObject'],
queue_id: 'queue-id',
},
],
}
);
Array of event notification rules
Array of S3 event types (e.g., ‘PutObject’, ‘DeleteObject’)
Cloudflare Queue ID to send notifications to
Temporary credentials
Generate temporary S3-compatible credentials for bucket access.
Create temporary credentials
const credentials = await client.r2.temporaryCredentials.create({
account_id: '023e105f4ecef8ad9ca31a8372d0c353',
bucket_name: 'my-bucket',
permissions: ['read', 'write'],
ttl_seconds: 3600,
});
Your Cloudflare account ID
Array of permissions: ‘read’, ‘write’, or ‘delete’
Time-to-live in seconds (default: 3600, max: 43200)
S3-compatible access key ID
S3-compatible secret access key
Session token for temporary credentials
ISO 8601 timestamp when credentials expire
Using R2 in Workers
Bind an R2 bucket to your Worker:
const version = await client.workers.beta.workers.versions.create(
workerId,
{
account_id: accountId,
main_module: 'worker.mjs',
compatibility_date: '2024-03-01',
bindings: [
{
type: 'r2_bucket',
name: 'BUCKET',
bucket_name: 'my-bucket',
},
],
modules: [...],
}
);
export default {
async fetch(request, env) {
// Put an object
await env.BUCKET.put('key', 'value');
// Get an object
const object = await env.BUCKET.get('key');
const text = await object.text();
// List objects
const list = await env.BUCKET.list();
return new Response(text);
},
};
Super Slurper
Migrate data from other cloud providers to R2.
Get Super Slurper configuration
const config = await client.r2.superSlurper.get(
'my-bucket',
{ account_id: '023e105f4ecef8ad9ca31a8372d0c353' }
);