Upload objects

Last updated Jul 29, 2026 There are several ways to upload objects to R2. Which approach you choose depends on the size of your objects and your performance requirements.

Choose an upload method

Note

Most S3-compatible SDKs and tools (such as rclone) automatically choose multipart upload for large files based on a configurable threshold. You do not typically need to implement multipart logic yourself when using the S3 API.

Upload via dashboard

To upload objects to your bucket from the Cloudflare dashboard:

1. In the Cloudflare dashboard, go to the R2 object storage page. Go to Overview ↗
2. Select your bucket.
3. Select Upload.
4. Drag and drop your file into the upload area or select from computer.

You will receive a confirmation message after a successful upload.

Create a folder

You can also create folders from the dashboard by selecting Create folder. This creates a zero-byte object with a key ending in / that acts as a placeholder. For more information on how folders work in R2, refer to Prefixes and folders.

Upload via Workers API

Use R2 bindings in Workers to upload objects server-side. Refer to Use R2 from Workers for instructions on setting up an R2 binding.

Single upload

Use put() to upload an object in a single request. This is the simplest approach for small to medium objects.

export default {
    async fetch(request, env) {
        try {
            const object = await env.MY_BUCKET.put("image.png", request.body, {
                httpMetadata: {
                    contentType: "image/png",
                },
            });

if (object === null) {
                return new Response("Precondition failed or upload returned null", {
                    status: 412,
                });
            }

return Response.json({
                key: object.key,
                size: object.size,
                etag: object.etag,
            });
        } catch (err) {
            return new Response(`Upload failed: ${err}`, { status: 500 });
        }
    },
};

export default {
    async fetch(request: Request, env: Env): Promise<Response> {
        try {
            const object = await env.MY_BUCKET.put("image.png", request.body, {
                httpMetadata: {
                    contentType: "image/png",
                },
            });

if (object === null) {
                return new Response("Precondition failed or upload returned null", {
                    status: 412,
                });
            }

return Response.json({
                key: object.key,
                size: object.size,
                etag: object.etag,
            });
        } catch (err) {
            return new Response(`Upload failed: ${err}`, { status: 500 });
        }
    },
} satisfies ExportedHandler<Env>;

Multipart upload

Use createMultipartUpload() and resumeMultipartUpload() for large files or when you need to upload parts in parallel. Each part must be at least 5 MiB (except the last part).

export default {
    async fetch(request, env) {
        const key = "large-file.bin";

// Create a new multipart upload
        const multipartUpload = await env.MY_BUCKET.createMultipartUpload(key);

try {
            // In a real application, these would be actual data chunks.
            // Each part except the last must be at least 5 MiB.
            const firstChunk = new Uint8Array(5 * 1024 * 1024); // placeholder
            const secondChunk = new Uint8Array(1024); // placeholder

const part1 = await multipartUpload.uploadPart(1, firstChunk);
            const part2 = await multipartUpload.uploadPart(2, secondChunk);

// Complete the upload with all parts
            const object = await multipartUpload.complete([part1, part2]);

return Response.json({
                key: object.key,
                etag: object.httpEtag,
            });
        } catch (err) {
            // Abort on failure so incomplete uploads do not count against storage
            await multipartUpload.abort();
            return new Response(`Multipart upload failed: ${err}`, { status: 500 });
        }
    },
};

export default {
    async fetch(request: Request, env: Env): Promise<Response> {
        const key = "large-file.bin";

// Create a new multipart upload
        const multipartUpload = await env.MY_BUCKET.createMultipartUpload(key);

try {
            // In a real application, these would be actual data chunks.
            // Each part except the last must be at least 5 MiB.
            const firstChunk = new Uint8Array(5 * 1024 * 1024); // placeholder
            const secondChunk = new Uint8Array(1024); // placeholder

const part1 = await multipartUpload.uploadPart(1, firstChunk);
            const part2 = await multipartUpload.uploadPart(2, secondChunk);

// Complete the upload with all parts
            const object = await multipartUpload.complete([part1, part2]);

return Response.json({
                key: object.key,
                etag: object.httpEtag,
            });
        } catch (err) {
            // Abort on failure so incomplete uploads do not count against storage
            await multipartUpload.abort();
            return new Response(`Multipart upload failed: ${err}`, { status: 500 });
        }
    },
} satisfies ExportedHandler<Env>;

In most cases, the multipart state (the uploadId and uploaded part ETags) is tracked by the client sending requests to your Worker. The following example exposes an HTTP API that a client application can call to create, upload parts for, and complete a multipart upload:

export default {
    async fetch(request, env) {
        const url = new URL(request.url);
        const key = url.pathname.slice(1);
        const action = url.searchParams.get("action");

if (!key || !action) {
            return new Response("Missing key or action", { status: 400 });
        }

switch (action) {
            // Step 1: Client calls POST /<key>?action=mpu-create
            case "mpu-create": {
                const upload = await env.MY_BUCKET.createMultipartUpload(key);
                return Response.json({ key: upload.key, uploadId: upload.uploadId });
            }

// Step 2: Client calls PUT /<key>?action=mpu-uploadpart&uploadId=...&partNumber=...
            case "mpu-uploadpart": {
                const uploadId = url.searchParams.get("uploadId");
                const partNumber = Number(url.searchParams.get("partNumber"));
                if (!uploadId || !partNumber || !request.body) {
                    return new Response("Missing uploadId, partNumber, or body", {
                        status: 400,
                    });
                }
                const upload = env.MY_BUCKET.resumeMultipartUpload(key, uploadId);
                try {
                    const part = await upload.uploadPart(partNumber, request.body);
                    return Response.json(part);
                } catch (err) {
                    return new Response(String(err), { status: 400 });
                }
            }

// Step 3: Client calls POST /<key>?action=mpu-complete&uploadId=...
            case "mpu-complete": {
                const uploadId = url.searchParams.get("uploadId");
                if (!uploadId) {
                    return new Response("Missing uploadId", { status: 400 });
                }
                const upload = env.MY_BUCKET.resumeMultipartUpload(key, uploadId);
                const body = await request.json();
                try {
                    const object = await upload.complete(body.parts);
                    return new Response(null, {
                        headers: { etag: object.httpEtag },
                    });
                } catch (err) {
                    return new Response(String(err), { status: 400 });
                }
            }

// Abort an in-progress upload
            case "mpu-abort": {
                const uploadId = url.searchParams.get("uploadId");
                if (!uploadId) {
                    return new Response("Missing uploadId", { status: 400 });
                }
                const upload = env.MY_BUCKET.resumeMultipartUpload(key, uploadId);
                try {
                    await upload.abort();
                } catch (err) {
                    return new Response(String(err), { status: 400 });
                }
                return new Response(null, { status: 204 });
            }

default:
                return new Response(`Unknown action: ${action}`, { status: 400 });
        }
    },
};

export default {
    async fetch(request: Request, env: Env): Promise<Response> {
        const url = new URL(request.url);
        const key = url.pathname.slice(1);
        const action = url.searchParams.get("action");

if (!key || !action) {
            return new Response("Missing key or action", { status: 400 });
        }

switch (action) {
            // Step 1: Client calls POST /<key>?action=mpu-create
            case "mpu-create": {
                const upload = await env.MY_BUCKET.createMultipartUpload(key);
                return Response.json({ key: upload.key, uploadId: upload.uploadId });
            }

// Step 2: Client calls PUT /<key>?action=mpu-uploadpart&uploadId=...&partNumber=...
            case "mpu-uploadpart": {
                const uploadId = url.searchParams.get("uploadId");
                const partNumber = Number(url.searchParams.get("partNumber"));
                if (!uploadId || !partNumber || !request.body) {
                    return new Response("Missing uploadId, partNumber, or body", {
                        status: 400,
                    });
                }
                const upload = env.MY_BUCKET.resumeMultipartUpload(key, uploadId);
                try {
                    const part = await upload.uploadPart(partNumber, request.body);
                    return Response.json(part);
                } catch (err) {
                    return new Response(String(err), { status: 400 });
                }
            }

// Step 3: Client calls POST /<key>?action=mpu-complete&uploadId=...
            case "mpu-complete": {
                const uploadId = url.searchParams.get("uploadId");
                if (!uploadId) {
                    return new Response("Missing uploadId", { status: 400 });
                }
                const upload = env.MY_BUCKET.resumeMultipartUpload(key, uploadId);
                const body = await request.json<{ parts: R2UploadedPart[] }>();
                try {
                    const object = await upload.complete(body.parts);
                    return new Response(null, {
                        headers: { etag: object.httpEtag },
                    });
                } catch (err) {
                    return new Response(String(err), { status: 400 });
                }
            }

// Abort an in-progress upload
            case "mpu-abort": {
                const uploadId = url.searchParams.get("uploadId");
                if (!uploadId) {
                    return new Response("Missing uploadId", { status: 400 });
                }
                const upload = env.MY_BUCKET.resumeMultipartUpload(key, uploadId);
                try {
                    await upload.abort();
                } catch (err) {
                    return new Response(String(err), { status: 400 });
                }
                return new Response(null, { status: 204 });
            }

default:
                return new Response(`Unknown action: ${action}`, { status: 400 });
        }
    },
} satisfies ExportedHandler<Env>;

For the complete Workers API reference, refer to Workers API reference.

Presigned URLs (Workers)

When you need clients (browsers, mobile apps) to upload directly to R2 without proxying through your Worker, generate a presigned URL server-side and hand it to the client:

import { AwsClient } from "aws4fetch";

export default {
    async fetch(request, env) {
        const r2 = new AwsClient({
            accessKeyId: env.R2_ACCESS_KEY_ID,
            secretAccessKey: env.R2_SECRET_ACCESS_KEY,
        });

// Generate a presigned PUT URL valid for 1 hour
        const url = new URL(
            "https://<ACCOUNT_ID>.r2.cloudflarestorage.com/my-bucket/image.png",
        );
        url.searchParams.set("X-Amz-Expires", "3600");

const signed = await r2.sign(new Request(url, { method: "PUT" }), {
            aws: { signQuery: true },
        });

// Return the signed URL to the client — they can PUT directly to R2
        return Response.json({ url: signed.url });
    },
};

import { AwsClient } from "aws4fetch";

interface Env {
    R2_ACCESS_KEY_ID: string;
    R2_SECRET_ACCESS_KEY: string;
}

export default {
    async fetch(request: Request, env: Env): Promise<Response> {
        const r2 = new AwsClient({
            accessKeyId: env.R2_ACCESS_KEY_ID,
            secretAccessKey: env.R2_SECRET_ACCESS_KEY,
        });

// Generate a presigned PUT URL valid for 1 hour
        const url = new URL(
            "https://<ACCOUNT_ID>.r2.cloudflarestorage.com/my-bucket/image.png",
        );
        url.searchParams.set("X-Amz-Expires", "3600");

const signed = await r2.sign(new Request(url, { method: "PUT" }), {
            aws: { signQuery: true },
        });

// Return the signed URL to the client — they can PUT directly to R2
        return Response.json({ url: signed.url });
    },
} satisfies ExportedHandler<Env>;

For full presigned URL documentation including GET, PUT, and security best practices, refer to Presigned URLs.

Upload via S3 API

Use S3-compatible SDKs to upload objects. You will need your account ID and R2 API token.

Single upload

import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
import { readFile } from "node:fs/promises";

const S3 = new S3Client({
    region: "auto",
    endpoint: `https://<ACCOUNT_ID>.r2.cloudflarestorage.com`,
    credentials: {
        accessKeyId: "<ACCESS_KEY_ID>",
        secretAccessKey: "<SECRET_ACCESS_KEY>",
    },
});

const fileContent = await readFile("./image.png");

const response = await S3.send(
    new PutObjectCommand({
        Bucket: "my-bucket",
        Key: "image.png",
        Body: fileContent,
        ContentType: "image/png",
    }),
);
console.log(`Uploaded successfully. ETag: ${response.ETag}`);

import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
import { readFile } from "node:fs/promises";

const S3 = new S3Client({
    region: "auto",
    endpoint: `https://<ACCOUNT_ID>.r2.cloudflarestorage.com`,
    credentials: {
        accessKeyId: "<ACCESS_KEY_ID>",
        secretAccessKey: "<SECRET_ACCESS_KEY>",
    },
});

const fileContent = await readFile("./image.png");

const response = await S3.send(
    new PutObjectCommand({
        Bucket: "my-bucket",
        Key: "image.png",
        Body: fileContent,
        ContentType: "image/png",
    }),
);
console.log(`Uploaded successfully. ETag: ${response.ETag}`);

import boto3

s3 = boto3.client(
    service_name="s3",
    endpoint_url="https://<ACCOUNT_ID>.r2.cloudflarestorage.com",
    aws_access_key_id="<ACCESS_KEY_ID>",
    aws_secret_access_key="<SECRET_ACCESS_KEY>",
    region_name="auto",
)

with open("./image.png", "rb") as f:
    response = s3.put_object(
        Bucket="my-bucket",
        Key="image.png",
        Body=f,
        ContentType="image/png",
    )
    print(f"Uploaded successfully. ETag: {response['ETag']}")

Multipart upload

Most S3 SDKs handle multipart uploads automatically when the file exceeds a configurable threshold. The examples below show both automatic (high-level) and manual (low-level) approaches.

Automatic multipart upload

The SDK splits the file and uploads parts in parallel.

```ts import { S3Client } from "@aws-sdk/client-s3"; import { Upload } from "@aws-sdk/lib-storage"; import { createReadStream } from "node:fs";