API Reference

R2

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Buckets

List Buckets

client.r2.buckets.list(BucketListParams { account_id, cursor, direction, 5 more } params, RequestOptionsoptions?): BucketListResponse { buckets }

GET/accounts/{account_id}/r2/buckets

Get Bucket

client.r2.buckets.get(stringbucketName, BucketGetParams { account_id, jurisdiction } params, RequestOptionsoptions?): Bucket { creation_date, jurisdiction, location, 2 more }

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

Create Bucket

client.r2.buckets.create(BucketCreateParams { account_id, name, locationHint, 2 more } params, RequestOptionsoptions?): Bucket { creation_date, jurisdiction, location, 2 more }

POST/accounts/{account_id}/r2/buckets

Patch Bucket

client.r2.buckets.edit(stringbucketName, BucketEditParams { account_id, storage_class, jurisdiction } params, RequestOptionsoptions?): Bucket { creation_date, jurisdiction, location, 2 more }

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

Delete Bucket

client.r2.buckets.delete(stringbucketName, BucketDeleteParams { account_id, jurisdiction } params, RequestOptionsoptions?): BucketDeleteResponse

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

ModelsExpand Collapse

Bucket { creation_date, jurisdiction, location, 2 more }

A single R2 bucket.

creation_date?: string

Creation timestamp.

jurisdiction?: "default" | "eu" | "fedramp"

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

One of the following:

"default"

"eu"

"fedramp"

location?: "apac" | "eeur" | "enam" | 3 more

Location of the bucket.

One of the following:

"apac"

"eeur"

"enam"

"weur"

"wnam"

"oc"

name?: string

Name of the bucket.

maxLength64

minLength3

storage_class?: "Standard" | "InfrequentAccess"

Storage class for newly uploaded objects, unless specified otherwise.

One of the following:

"Standard"

"InfrequentAccess"

BucketListResponse { buckets }

buckets?: Array<Bucket { creation_date, jurisdiction, location, 2 more } >

creation_date?: string

Creation timestamp.

jurisdiction?: "default" | "eu" | "fedramp"

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

One of the following:

"default"

"eu"

"fedramp"

location?: "apac" | "eeur" | "enam" | 3 more

Location of the bucket.

One of the following:

"apac"

"eeur"

"enam"

"weur"

"wnam"

"oc"

name?: string

Name of the bucket.

maxLength64

minLength3

storage_class?: "Standard" | "InfrequentAccess"

Storage class for newly uploaded objects, unless specified otherwise.

One of the following:

"Standard"

"InfrequentAccess"

BucketDeleteResponse = unknown

BucketsLifecycle

Get Object Lifecycle Rules

client.r2.buckets.lifecycle.get(stringbucketName, LifecycleGetParams { account_id, jurisdiction } params, RequestOptionsoptions?): LifecycleGetResponse { rules }

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

Put Object Lifecycle Rules

client.r2.buckets.lifecycle.update(stringbucketName, LifecycleUpdateParams { account_id, rules, jurisdiction } params, RequestOptionsoptions?): LifecycleUpdateResponse

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

ModelsExpand Collapse

LifecycleGetResponse { rules }

rules?: Array<Rule>

id: string

Unique identifier for this rule.

conditions: 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?: AbortMultipartUploadsTransition { condition }

Transition to abort ongoing multipart uploads.

condition?: Condition { maxAge, type }

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

maxAge: number

type: "Age"

deleteObjectsTransition?: DeleteObjectsTransition { condition }

Transition to delete objects.

condition?: R2LifecycleAgeCondition { maxAge, type } | R2LifecycleDateCondition { 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?: Array<StorageClassTransition>

Transitions to change the storage class of objects.

condition: R2LifecycleAgeCondition { maxAge, type } | R2LifecycleDateCondition { 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

client.r2.buckets.cors.get(stringbucketName, CORSGetParams { account_id, jurisdiction } params, RequestOptionsoptions?): CORSGetResponse { rules }

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

Put Bucket CORS Policy

client.r2.buckets.cors.update(stringbucketName, CORSUpdateParams { account_id, rules, jurisdiction } params, RequestOptionsoptions?): CORSUpdateResponse

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

Delete Bucket CORS Policy

client.r2.buckets.cors.delete(stringbucketName, CORSDeleteParams { account_id, jurisdiction } params, RequestOptionsoptions?): CORSDeleteResponse

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

ModelsExpand Collapse

CORSGetResponse { rules }

rules?: Array<Rule>

allowed: Allowed { methods, origins, headers }

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

methods: Array<"GET" | "PUT" | "POST" | 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<string>

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

headers?: Array<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?: string

Identifier for this rule.

exposeHeaders?: Array<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?: 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

client.r2.buckets.domains.custom.list(stringbucketName, CustomListParams { account_id, jurisdiction } params, RequestOptionsoptions?): CustomListResponse { domains }

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

Get Custom Domain Settings

client.r2.buckets.domains.custom.get(stringbucketName, stringdomain, CustomGetParams { account_id, jurisdiction } params, RequestOptionsoptions?): CustomGetResponse { domain, enabled, status, 4 more }

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

Attach Custom Domain To Bucket

client.r2.buckets.domains.custom.create(stringbucketName, CustomCreateParams { account_id, domain, enabled, 4 more } params, RequestOptionsoptions?): CustomCreateResponse { domain, enabled, ciphers, minTLS }

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

Configure Custom Domain Settings

client.r2.buckets.domains.custom.update(stringbucketName, stringdomain, CustomUpdateParams { account_id, ciphers, enabled, 2 more } params, RequestOptionsoptions?): CustomUpdateResponse { domain, ciphers, enabled, minTLS }

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

Remove Custom Domain From Bucket

client.r2.buckets.domains.custom.delete(stringbucketName, stringdomain, CustomDeleteParams { account_id, jurisdiction } params, RequestOptionsoptions?): CustomDeleteResponse { domain }

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

ModelsExpand Collapse

CustomListResponse { domains }

domains: Array<Domain>

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: Status { ownership, ssl }

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

Ownership status of the domain.

One of the following:

"pending"

"active"

"deactivated"

"blocked"

"error"

"unknown"

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

SSL certificate status.

One of the following:

"initializing"

"pending"

"active"

"deactivated"

"error"

"unknown"

ciphers?: Array<string>

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

minTLS?: "1.0" | "1.1" | "1.2" | "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?: string

Zone ID of the custom domain resides in.

zoneName?: 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: Status { ownership, ssl }

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

Ownership status of the domain.

One of the following:

"pending"

"active"

"deactivated"

"blocked"

"error"

"unknown"

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

SSL certificate status.

One of the following:

"initializing"

"pending"

"active"

"deactivated"

"error"

"unknown"

ciphers?: Array<string>

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

minTLS?: "1.0" | "1.1" | "1.2" | "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?: string

Zone ID of the custom domain resides in.

zoneName?: 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?: Array<string>

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

minTLS?: "1.0" | "1.1" | "1.2" | "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?: Array<string>

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

enabled?: boolean

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

minTLS?: "1.0" | "1.1" | "1.2" | "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

client.r2.buckets.domains.managed.list(stringbucketName, ManagedListParams { account_id, jurisdiction } params, RequestOptionsoptions?): ManagedListResponse { bucketId, domain, enabled }

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

Update r2.dev Domain of Bucket

client.r2.buckets.domains.managed.update(stringbucketName, ManagedUpdateParams { account_id, enabled, jurisdiction } params, RequestOptionsoptions?): ManagedUpdateResponse { bucketId, domain, enabled }

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

client.r2.buckets.eventNotifications.list(stringbucketName, EventNotificationListParams { account_id, jurisdiction } params, RequestOptionsoptions?): EventNotificationListResponse { bucketName, queues }

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

Get Event Notification Rule

client.r2.buckets.eventNotifications.get(stringbucketName, stringqueueId, EventNotificationGetParams { account_id, jurisdiction } params, RequestOptionsoptions?): EventNotificationGetResponse { queueId, queueName, rules }

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

Create Event Notification Rule

client.r2.buckets.eventNotifications.update(stringbucketName, stringqueueId, EventNotificationUpdateParams { account_id, rules, jurisdiction } params, RequestOptionsoptions?): EventNotificationUpdateResponse

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

Delete Event Notification Rules

client.r2.buckets.eventNotifications.delete(stringbucketName, stringqueueId, EventNotificationDeleteParams { account_id, jurisdiction } params, RequestOptionsoptions?): EventNotificationDeleteResponse

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

ModelsExpand Collapse

EventNotificationListResponse { bucketName, queues }

bucketName?: string

Name of the bucket.

queues?: Array<Queue>

List of queues associated with the bucket.

queueId?: string

Queue ID.

queueName?: string

Name of the queue.

rules?: Array<Rule>

actions: Array<"PutObject" | "CopyObject" | "DeleteObject" | 2 more>

Array of R2 object actions that will trigger notifications.

One of the following:

"PutObject"

"CopyObject"

"DeleteObject"

"CompleteMultipartUpload"

"LifecycleDeletion"

createdAt?: string

Timestamp when the rule was created.

description?: string

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

prefix?: string

Notifications will be sent only for objects with this prefix.

ruleId?: string

Rule ID.

suffix?: string

Notifications will be sent only for objects with this suffix.

EventNotificationGetResponse { queueId, queueName, rules }

queueId?: string

Queue ID.

queueName?: string

Name of the queue.

rules?: Array<Rule>

actions: Array<"PutObject" | "CopyObject" | "DeleteObject" | 2 more>

Array of R2 object actions that will trigger notifications.

One of the following:

"PutObject"

"CopyObject"

"DeleteObject"

"CompleteMultipartUpload"

"LifecycleDeletion"

createdAt?: string

Timestamp when the rule was created.

description?: string

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

prefix?: string

Notifications will be sent only for objects with this prefix.

ruleId?: string

Rule ID.

suffix?: string

Notifications will be sent only for objects with this suffix.

EventNotificationUpdateResponse = unknown

EventNotificationDeleteResponse = unknown

BucketsLocks

Get Bucket Lock Rules

client.r2.buckets.locks.get(stringbucketName, LockGetParams { account_id, jurisdiction } params, RequestOptionsoptions?): LockGetResponse { rules }

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

Put Bucket Lock Rules

client.r2.buckets.locks.update(stringbucketName, LockUpdateParams { account_id, rules, jurisdiction } params, RequestOptionsoptions?): LockUpdateResponse

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

ModelsExpand Collapse

LockGetResponse { rules }

rules?: Array<Rule>

id: string

Unique identifier for this rule.

condition: R2LockRuleAgeCondition { maxAgeSeconds, type } | R2LockRuleDateCondition { date, type } | R2LockRuleIndefiniteCondition { 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?: 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

client.r2.buckets.metrics.list(MetricListParams { account_id } params, RequestOptionsoptions?): MetricListResponse { infrequentAccess, standard }

GET/accounts/{account_id}/r2/metrics

ModelsExpand Collapse

MetricListResponse { infrequentAccess, standard }

Metrics based on the class they belong to.

infrequentAccess?: InfrequentAccess { published, uploaded }

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

published?: Published { metadataSize, objects, payloadSize }

Metrics on number of objects/amount of storage used.

metadataSize?: number

Amount of.

objects?: number

Number of objects stored.

payloadSize?: number

Amount of storage used by object data.

uploaded?: Uploaded { metadataSize, objects, payloadSize }

Metrics on number of objects/amount of storage used.

metadataSize?: number

Amount of.

objects?: number

Number of objects stored.

payloadSize?: number

Amount of storage used by object data.

standard?: Standard { published, uploaded }

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

published?: Published { metadataSize, objects, payloadSize }

Metrics on number of objects/amount of storage used.

metadataSize?: number

Amount of.

objects?: number

Number of objects stored.

payloadSize?: number

Amount of storage used by object data.

uploaded?: Uploaded { metadataSize, objects, payloadSize }

Metrics on number of objects/amount of storage used.

metadataSize?: number

Amount of.

objects?: number

Number of objects stored.

payloadSize?: number

Amount of storage used by object data.

BucketsSippy

Get Sippy Configuration

client.r2.buckets.sippy.get(stringbucketName, SippyGetParams { account_id, jurisdiction } params, RequestOptionsoptions?): Sippy { destination, enabled, source }

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

Enable Sippy

client.r2.buckets.sippy.update(stringbucketName, SippyUpdateParamsparams, RequestOptionsoptions?): Sippy { destination, enabled, source }

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

Disable Sippy

client.r2.buckets.sippy.delete(stringbucketName, SippyDeleteParams { account_id, jurisdiction } params, RequestOptionsoptions?): SippyDeleteResponse { enabled }

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

ModelsExpand Collapse

Provider = "r2"

Sippy { destination, enabled, source }

destination?: Destination { accessKeyId, account, bucket, provider }

Details about the configured destination bucket.

accessKeyId?: string

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

account?: string

bucket?: string

Name of the bucket on the provider.

provider?: Provider { }

enabled?: boolean

State of Sippy for this bucket.

source?: Source { bucket, bucketUrl, provider, region }

Details about the configured source bucket.

bucket?: string | null

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

bucketUrl?: string | null

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

provider?: "aws" | "gcs" | "s3"

One of the following:

"aws"

"gcs"

"s3"

region?: string | null

Region where the bucket resides (AWS only).

SippyDeleteResponse { enabled }

enabled?: false