API Reference

R2

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Buckets

List Buckets

GET/accounts/{account_id}/r2/buckets

Get Bucket

GET/accounts/{account_id}/r2/buckets/{bucket_name}

Create Bucket

POST/accounts/{account_id}/r2/buckets

Patch Bucket

PATCH/accounts/{account_id}/r2/buckets/{bucket_name}

Delete Bucket

DELETE/accounts/{account_id}/r2/buckets/{bucket_name}

ModelsExpand Collapse

Bucket { creation_date, jurisdiction, location, 2 more }

A single R2 bucket.

creation_date: optional string

Creation timestamp.

jurisdiction: optional "default" or "eu" or "fedramp"

Jurisdiction where objects in this bucket are guaranteed to be stored.

One of the following:

"default"

"eu"

"fedramp"

location: optional "apac" or "eeur" or "enam" or 3 more

Location of the bucket.

One of the following:

"apac"

"eeur"

"enam"

"weur"

"wnam"

"oc"

name: optional string

Name of the bucket.

maxLength64

minLength3

storage_class: optional "Standard" or "InfrequentAccess"

Storage class for newly uploaded objects, unless specified otherwise.

One of the following:

"Standard"

"InfrequentAccess"

BucketListResponse { buckets }

buckets: optional array of Bucket { creation_date, jurisdiction, location, 2 more }

creation_date: optional string

Creation timestamp.

jurisdiction: optional "default" or "eu" or "fedramp"

Jurisdiction where objects in this bucket are guaranteed to be stored.

One of the following:

"default"

"eu"

"fedramp"

location: optional "apac" or "eeur" or "enam" or 3 more

Location of the bucket.

One of the following:

"apac"

"eeur"

"enam"

"weur"

"wnam"

"oc"

name: optional string

Name of the bucket.

maxLength64

minLength3

storage_class: optional "Standard" or "InfrequentAccess"

Storage class for newly uploaded objects, unless specified otherwise.

One of the following:

"Standard"

"InfrequentAccess"

BucketDeleteResponse = unknown

BucketsLifecycle

Get Object Lifecycle Rules

GET/accounts/{account_id}/r2/buckets/{bucket_name}/lifecycle

Put Object Lifecycle Rules

PUT/accounts/{account_id}/r2/buckets/{bucket_name}/lifecycle

ModelsExpand Collapse

LifecycleGetResponse { rules }

rules: optional array of { id, conditions, enabled, 3 more }

id: string

Unique identifier for this rule.

conditions: { prefix }

Conditions that apply to all transitions of this rule.

prefix: string

Transitions will only apply to objects/uploads in the bucket that start with the given prefix, an empty prefix can be provided to scope rule to all objects/uploads.

enabled: boolean

Whether or not this rule is in effect.

abortMultipartUploadsTransition: optional { condition }

Transition to abort ongoing multipart uploads.

condition: optional { maxAge, type }

Condition for lifecycle transitions to apply after an object reaches an age in seconds.

maxAge: number

type: "Age"

deleteObjectsTransition: optional { condition }

Transition to delete objects.

condition: optional { maxAge, type } or { date, type }

Condition for lifecycle transitions to apply after an object reaches an age in seconds.

One of the following:

R2LifecycleAgeCondition { maxAge, type }

Condition for lifecycle transitions to apply after an object reaches an age in seconds.

maxAge: number

type: "Age"

R2LifecycleDateCondition { date, type }

Condition for lifecycle transitions to apply on a specific date.

date: string

formatdate-time

type: "Date"

storageClassTransitions: optional array of { condition, storageClass }

Transitions to change the storage class of objects.

condition: { maxAge, type } or { date, type }

Condition for lifecycle transitions to apply after an object reaches an age in seconds.

One of the following:

R2LifecycleAgeCondition { maxAge, type }

Condition for lifecycle transitions to apply after an object reaches an age in seconds.

maxAge: number

type: "Age"

R2LifecycleDateCondition { date, type }

Condition for lifecycle transitions to apply on a specific date.

date: string

formatdate-time

type: "Date"

storageClass: "InfrequentAccess"

LifecycleUpdateResponse = unknown

BucketsCORS

Get Bucket CORS Policy

GET/accounts/{account_id}/r2/buckets/{bucket_name}/cors

Put Bucket CORS Policy

PUT/accounts/{account_id}/r2/buckets/{bucket_name}/cors

Delete Bucket CORS Policy

DELETE/accounts/{account_id}/r2/buckets/{bucket_name}/cors

ModelsExpand Collapse

CORSGetResponse { rules }

rules: optional array of { allowed, id, exposeHeaders, maxAgeSeconds }

allowed: { methods, origins, headers }

Object specifying allowed origins, methods and headers for this CORS rule.

methods: array of "GET" or "PUT" or "POST" or 2 more

Specifies the value for the Access-Control-Allow-Methods header R2 sets when requesting objects in a bucket from a browser.

One of the following:

"GET"

"PUT"

"POST"

"DELETE"

"HEAD"

origins: array of string

Specifies the value for the Access-Control-Allow-Origin header R2 sets when requesting objects in a bucket from a browser.

headers: optional array of string

Specifies the value for the Access-Control-Allow-Headers header R2 sets when requesting objects in this bucket from a browser. Cross-origin requests that include custom headers (e.g. x-user-id) should specify these headers as AllowedHeaders.

id: optional string

Identifier for this rule.

exposeHeaders: optional array of string

Specifies the headers that can be exposed back, and accessed by, the JavaScript making the cross-origin request. If you need to access headers beyond the safelisted response headers, such as Content-Encoding or cf-cache-status, you must specify it here.

maxAgeSeconds: optional number

Specifies the amount of time (in seconds) browsers are allowed to cache CORS preflight responses. Browsers may limit this to 2 hours or less, even if the maximum value (86400) is specified.

CORSUpdateResponse = unknown

CORSDeleteResponse = unknown

BucketsDomains

BucketsDomainsCustom

List Custom Domains of Bucket

GET/accounts/{account_id}/r2/buckets/{bucket_name}/domains/custom

Get Custom Domain Settings

GET/accounts/{account_id}/r2/buckets/{bucket_name}/domains/custom/{domain}

Attach Custom Domain To Bucket

POST/accounts/{account_id}/r2/buckets/{bucket_name}/domains/custom

Configure Custom Domain Settings

PUT/accounts/{account_id}/r2/buckets/{bucket_name}/domains/custom/{domain}

Remove Custom Domain From Bucket

DELETE/accounts/{account_id}/r2/buckets/{bucket_name}/domains/custom/{domain}

ModelsExpand Collapse

CustomListResponse { domains }

domains: array of { domain, enabled, status, 4 more }

domain: string

Domain name of the custom domain to be added.

enabled: boolean

Whether this bucket is publicly accessible at the specified custom domain.

status: { ownership, ssl }

ownership: "pending" or "active" or "deactivated" or 3 more

Ownership status of the domain.

One of the following:

"pending"

"active"

"deactivated"

"blocked"

"error"

"unknown"

ssl: "initializing" or "pending" or "active" or 3 more

SSL certificate status.

One of the following:

"initializing"

"pending"

"active"

"deactivated"

"error"

"unknown"

ciphers: optional array of string

An allowlist of ciphers for TLS termination. These ciphers must be in the BoringSSL format.

minTLS: optional "1.0" or "1.1" or "1.2" or "1.3"

Minimum TLS Version the custom domain will accept for incoming connections. If not set, defaults to 1.0.

One of the following:

"1.0"

"1.1"

"1.2"

"1.3"

zoneId: optional string

Zone ID of the custom domain resides in.

zoneName: optional string

Zone that the custom domain resides in.

CustomGetResponse { domain, enabled, status, 4 more }

domain: string

Domain name of the custom domain to be added.

enabled: boolean

Whether this bucket is publicly accessible at the specified custom domain.

status: { ownership, ssl }

ownership: "pending" or "active" or "deactivated" or 3 more

Ownership status of the domain.

One of the following:

"pending"

"active"

"deactivated"

"blocked"

"error"

"unknown"

ssl: "initializing" or "pending" or "active" or 3 more

SSL certificate status.

One of the following:

"initializing"

"pending"

"active"

"deactivated"

"error"

"unknown"

ciphers: optional array of string

An allowlist of ciphers for TLS termination. These ciphers must be in the BoringSSL format.

minTLS: optional "1.0" or "1.1" or "1.2" or "1.3"

Minimum TLS Version the custom domain will accept for incoming connections. If not set, defaults to 1.0.

One of the following:

"1.0"

"1.1"

"1.2"

"1.3"

zoneId: optional string

Zone ID of the custom domain resides in.

zoneName: optional string

Zone that the custom domain resides in.

CustomCreateResponse { domain, enabled, ciphers, minTLS }

domain: string

Domain name of the affected custom domain.

enabled: boolean

Whether this bucket is publicly accessible at the specified custom domain.

ciphers: optional array of string

An allowlist of ciphers for TLS termination. These ciphers must be in the BoringSSL format.

minTLS: optional "1.0" or "1.1" or "1.2" or "1.3"

Minimum TLS Version the custom domain will accept for incoming connections. If not set, defaults to 1.0.

One of the following:

"1.0"

"1.1"

"1.2"

"1.3"

CustomUpdateResponse { domain, ciphers, enabled, minTLS }

domain: string

Domain name of the affected custom domain.

ciphers: optional array of string

An allowlist of ciphers for TLS termination. These ciphers must be in the BoringSSL format.

enabled: optional boolean

Whether this bucket is publicly accessible at the specified custom domain.

minTLS: optional "1.0" or "1.1" or "1.2" or "1.3"

Minimum TLS Version the custom domain will accept for incoming connections. If not set, defaults to 1.0.

One of the following:

"1.0"

"1.1"

"1.2"

"1.3"

CustomDeleteResponse { domain }

domain: string

Name of the removed custom domain.

BucketsDomainsManaged

Get r2.dev Domain of Bucket

GET/accounts/{account_id}/r2/buckets/{bucket_name}/domains/managed

Update r2.dev Domain of Bucket

PUT/accounts/{account_id}/r2/buckets/{bucket_name}/domains/managed

ModelsExpand Collapse

ManagedListResponse { bucketId, domain, enabled }

bucketId: string

Bucket ID.

maxLength32

domain: string

Domain name of the bucket’s r2.dev domain.

enabled: boolean

Whether this bucket is publicly accessible at the r2.dev domain.

ManagedUpdateResponse { bucketId, domain, enabled }

bucketId: string

Bucket ID.

maxLength32

domain: string

Domain name of the bucket’s r2.dev domain.

enabled: boolean

Whether this bucket is publicly accessible at the r2.dev domain.

BucketsEvent Notifications

List Event Notification Rules

GET/accounts/{account_id}/event_notifications/r2/{bucket_name}/configuration

Get Event Notification Rule

GET/accounts/{account_id}/event_notifications/r2/{bucket_name}/configuration/queues/{queue_id}

Create Event Notification Rule

PUT/accounts/{account_id}/event_notifications/r2/{bucket_name}/configuration/queues/{queue_id}

Delete Event Notification Rules

DELETE/accounts/{account_id}/event_notifications/r2/{bucket_name}/configuration/queues/{queue_id}

ModelsExpand Collapse

EventNotificationListResponse { bucketName, queues }

bucketName: optional string

Name of the bucket.

queues: optional array of { queueId, queueName, rules }

List of queues associated with the bucket.

queueId: optional string

Queue ID.

queueName: optional string

Name of the queue.

rules: optional array of { actions, createdAt, description, 3 more }

actions: array of "PutObject" or "CopyObject" or "DeleteObject" or 2 more

Array of R2 object actions that will trigger notifications.

One of the following:

"PutObject"

"CopyObject"

"DeleteObject"

"CompleteMultipartUpload"

"LifecycleDeletion"

createdAt: optional string

Timestamp when the rule was created.

description: optional string

A description that can be used to identify the event notification rule after creation.

prefix: optional string

Notifications will be sent only for objects with this prefix.

ruleId: optional string

Rule ID.

suffix: optional string

Notifications will be sent only for objects with this suffix.

EventNotificationGetResponse { queueId, queueName, rules }

queueId: optional string

Queue ID.

queueName: optional string

Name of the queue.

rules: optional array of { actions, createdAt, description, 3 more }

actions: array of "PutObject" or "CopyObject" or "DeleteObject" or 2 more

Array of R2 object actions that will trigger notifications.

One of the following:

"PutObject"

"CopyObject"

"DeleteObject"

"CompleteMultipartUpload"

"LifecycleDeletion"

createdAt: optional string

Timestamp when the rule was created.

description: optional string

A description that can be used to identify the event notification rule after creation.

prefix: optional string

Notifications will be sent only for objects with this prefix.

ruleId: optional string

Rule ID.

suffix: optional string

Notifications will be sent only for objects with this suffix.

EventNotificationUpdateResponse = unknown

EventNotificationDeleteResponse = unknown

BucketsLocks

Get Bucket Lock Rules

GET/accounts/{account_id}/r2/buckets/{bucket_name}/lock

Put Bucket Lock Rules

PUT/accounts/{account_id}/r2/buckets/{bucket_name}/lock

ModelsExpand Collapse

LockGetResponse { rules }

rules: optional array of { id, condition, enabled, prefix }

id: string

Unique identifier for this rule.

condition: { maxAgeSeconds, type } or { date, type } or { type }

Condition to apply a lock rule to an object for how long in seconds.

One of the following:

R2LockRuleAgeCondition { maxAgeSeconds, type }

Condition to apply a lock rule to an object for how long in seconds.

maxAgeSeconds: number

type: "Age"

R2LockRuleDateCondition { date, type }

Condition to apply a lock rule to an object until a specific date.

date: string

formatdate-time

type: "Date"

R2LockRuleIndefiniteCondition { type }

Condition to apply a lock rule indefinitely.

type: "Indefinite"

enabled: boolean

Whether or not this rule is in effect.

prefix: optional string

Rule will only apply to objects/uploads in the bucket that start with the given prefix, an empty prefix can be provided to scope rule to all objects/uploads.

LockUpdateResponse = unknown

BucketsMetrics

Get Account-Level Metrics

GET/accounts/{account_id}/r2/metrics

ModelsExpand Collapse

MetricListResponse { infrequentAccess, standard }

Metrics based on the class they belong to.

infrequentAccess: optional { published, uploaded }

Metrics based on what state they are in(uploaded or published).

published: optional { metadataSize, objects, payloadSize }

Metrics on number of objects/amount of storage used.

metadataSize: optional number

Amount of.

objects: optional number

Number of objects stored.

payloadSize: optional number

Amount of storage used by object data.

uploaded: optional { metadataSize, objects, payloadSize }

Metrics on number of objects/amount of storage used.

metadataSize: optional number

Amount of.

objects: optional number

Number of objects stored.

payloadSize: optional number

Amount of storage used by object data.

standard: optional { published, uploaded }

Metrics based on what state they are in(uploaded or published).

published: optional { metadataSize, objects, payloadSize }

Metrics on number of objects/amount of storage used.

metadataSize: optional number

Amount of.

objects: optional number

Number of objects stored.

payloadSize: optional number

Amount of storage used by object data.

uploaded: optional { metadataSize, objects, payloadSize }

Metrics on number of objects/amount of storage used.

metadataSize: optional number

Amount of.

objects: optional number

Number of objects stored.

payloadSize: optional number

Amount of storage used by object data.

BucketsSippy

Get Sippy Configuration

GET/accounts/{account_id}/r2/buckets/{bucket_name}/sippy

Enable Sippy

PUT/accounts/{account_id}/r2/buckets/{bucket_name}/sippy

Disable Sippy

DELETE/accounts/{account_id}/r2/buckets/{bucket_name}/sippy

ModelsExpand Collapse

Provider = "r2"

Sippy { destination, enabled, source }

destination: optional { accessKeyId, account, bucket, provider }

Details about the configured destination bucket.

accessKeyId: optional string

ID of the Cloudflare API token used when writing objects to this bucket.

account: optional string

bucket: optional string

Name of the bucket on the provider.

provider: optional Provider

enabled: optional boolean

State of Sippy for this bucket.

source: optional { bucket, bucketUrl, provider, region }

Details about the configured source bucket.

bucket: optional string

Name of the bucket on the provider (AWS, GCS only).

bucketUrl: optional string

S3-compatible URL (Generic S3-compatible providers only).

provider: optional "aws" or "gcs" or "s3"

One of the following:

"aws"

"gcs"

"s3"

region: optional string

Region where the bucket resides (AWS only).

SippyDeleteResponse { enabled }

enabled: optional false