S3

R2 provides support for a S3-compatible API, which means you can use any S3 SDK, library, or tool to interact with your buckets. If you have existing code that works with S3, you can use it with R2 by changing the endpoint URL.

1. Create a bucket

A bucket stores your objects in R2. To create a new R2 bucket:

Wrangler CLI

1. Log in to your Cloudflare account:

   npx wrangler login

2. Create a bucket named my-bucket:

   npx wrangler r2 bucket create my-bucket

   If prompted, select the account you want to create the bucket in.

3. Verify the bucket was created:

   npx wrangler r2 bucket list

Dashboard

1. In the Cloudflare Dashboard, go to R2 object storage.

   Go to Overview

2. Select Create bucket.

3. Enter a name for your bucket.

4. Select a location for your bucket and a default storage class.

5. Select Create bucket.

2. Generate API credentials

To use the S3 API, you need to generate credentials and get an Access Key ID and Secret Access Key:

1. Go to the Cloudflare Dashboard ↗.
2. Select Storage & databases > R2 > Overview.
3. Select Manage in API Tokens.
4. Select Create Account API token or Create User API token
5. Choose Object Read & Write permission and Apply to specific buckets only to select the buckets you want to access.
6. Select Create API Token.
7. Copy the Access Key ID and Secret Access Key. Store these securely as you cannot view the secret again.

You also need your S3 API endpoint URL which you can find at the bottom of the Create API Token confirmation page once you have created your token, or on the R2 Overview page:

https://<ACCOUNT_ID>.r2.cloudflarestorage.com

3. Use an AWS SDK

The following examples show how to use Python and JavaScript SDKs. For other languages, refer to S3-compatible SDK examples for Go, Java, PHP, Ruby, and Rust.

Python (boto3)

1. Install boto3 ↗:

   pip install boto3

2. Create a test file to upload:

   echo 'Hello, R2!' > myfile.txt

3. Use your credentials to create an S3 client and interact with your bucket:

   Python

   import boto3
   
   s3 = boto3.client(
       service_name='s3',
       # Provide your R2 endpoint: https://<ACCOUNT_ID>.r2.cloudflarestorage.com
       endpoint_url='https://<ACCOUNT_ID>.r2.cloudflarestorage.com',
       # Provide your R2 Access Key ID and Secret Access Key
       aws_access_key_id='<ACCESS_KEY_ID>',
       aws_secret_access_key='<SECRET_ACCESS_KEY>',
       region_name='auto',  # Required by boto3, not used by R2
   )
   
   # Upload a file
   s3.upload_file('myfile.txt', 'my-bucket', 'myfile.txt')
   print('Uploaded myfile.txt')
   
   # Download a file
   s3.download_file('my-bucket', 'myfile.txt', 'downloaded.txt')
   print('Downloaded to downloaded.txt')
   
   # List objects
   response = s3.list_objects_v2(Bucket='my-bucket')
   for obj in response.get('Contents', []):
       print(f"Object: {obj['Key']}")

4. Save this as example.py and run it:

   python example.py

   Uploaded myfile.txt
   Downloaded to downloaded.txt
   Object: myfile.txt

Refer to boto3 examples for more operations.

JavaScript

1. Install the @aws-sdk/client-s3 ↗ package:

   npm install @aws-sdk/client-s3

2. Use your credentials to create an S3 client and interact with your bucket:

   JavaScript

   import {
     S3Client,
     PutObjectCommand,
     GetObjectCommand,
     ListObjectsV2Command,
   } from "@aws-sdk/client-s3";
   
   const s3 = new S3Client({
     region: "auto", // Required by AWS SDK, not used by R2
     // Provide your R2 endpoint: https://<ACCOUNT_ID>.r2.cloudflarestorage.com
     endpoint: "https://<ACCOUNT_ID>.r2.cloudflarestorage.com",
     credentials: {
       // Provide your R2 Access Key ID and Secret Access Key
       accessKeyId: "<ACCESS_KEY_ID>",
       secretAccessKey: "<SECRET_ACCESS_KEY>",
     },
   });
   
   // Upload a file
   await s3.send(
     new PutObjectCommand({
       Bucket: "my-bucket",
       Key: "myfile.txt",
       Body: "Hello, R2!",
     }),
   );
   console.log("Uploaded myfile.txt");
   
   // Download a file
   const response = await s3.send(
     new GetObjectCommand({
       Bucket: "my-bucket",
       Key: "myfile.txt",
     }),
   );
   const content = await response.Body.transformToString();
   console.log("Downloaded:", content);
   
   // List objects
   const list = await s3.send(
     new ListObjectsV2Command({
       Bucket: "my-bucket",
     }),
   );
   console.log(
     "Objects:",
     list.Contents.map((obj) => obj.Key),
   );

3. Save this as example.mjs and run it:

   node example.mjs

   Uploaded myfile.txt
   Downloaded: Hello, R2!
   Objects: [ 'myfile.txt' ]

Refer to AWS SDK for JavaScript examples for more operations.

Next steps

Presigned URLs Generate temporary URLs for private object access.

Public buckets Serve files directly over HTTP with a public bucket.

CORS Configure CORS for browser-based uploads.

Object lifecycles Set up lifecycle rules to automatically delete old objects.