Buckets

List Buckets

r2.buckets.list() -> BucketListResponse

GET/accounts/{account_id}/r2/buckets

Get Bucket

r2.buckets.get(, ) -> Bucket

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

Create Bucket

r2.buckets.create() -> Bucket

POST/accounts/{account_id}/r2/buckets

Patch Bucket

r2.buckets.edit(, ) -> Bucket

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

Delete Bucket

r2.buckets.delete(, ) -> object

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

ModelsExpand Collapse

class Bucket: …

A single R2 bucket.

creation_date: Optional[str]

Creation timestamp.

jurisdiction: Optional[Literal["default", "eu", "fedramp"]]

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

One of the following:

"default"

"eu"

"fedramp"

location: Optional[Literal["apac", "eeur", "enam", 3 more]]

Location of the bucket.

One of the following:

"apac"

"eeur"

"enam"

"weur"

"wnam"

"oc"

name: Optional[str]

Name of the bucket.

maxLength64

minLength3

storage_class: Optional[Literal["Standard", "InfrequentAccess"]]

Storage class for newly uploaded objects, unless specified otherwise.

One of the following:

"Standard"

"InfrequentAccess"

class BucketListResponse: …

buckets: Optional[List[Bucket]]

creation_date: Optional[str]

Creation timestamp.

jurisdiction: Optional[Literal["default", "eu", "fedramp"]]

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

One of the following:

"default"

"eu"

"fedramp"

location: Optional[Literal["apac", "eeur", "enam", 3 more]]

Location of the bucket.

One of the following:

"apac"

"eeur"

"enam"

"weur"

"wnam"

"oc"

name: Optional[str]

Name of the bucket.

maxLength64

minLength3

storage_class: Optional[Literal["Standard", "InfrequentAccess"]]

Storage class for newly uploaded objects, unless specified otherwise.

One of the following:

"Standard"

"InfrequentAccess"

BucketsLifecycle

Get Object Lifecycle Rules

r2.buckets.lifecycle.get(, ) -> LifecycleGetResponse

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

Put Object Lifecycle Rules

r2.buckets.lifecycle.update(, ) -> object

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

ModelsExpand Collapse

class LifecycleGetResponse: …

rules: Optional[List[Rule]]

id: str

Unique identifier for this rule.

conditions: RuleConditions

Conditions that apply to all transitions of this rule.

prefix: str

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: bool

Whether or not this rule is in effect.

abort_multipart_uploads_transition: Optional[RuleAbortMultipartUploadsTransition]

Transition to abort ongoing multipart uploads.

condition: Optional[RuleAbortMultipartUploadsTransitionCondition]

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

max_age: int

type: Literal["Age"]

delete_objects_transition: Optional[RuleDeleteObjectsTransition]

Transition to delete objects.

condition: Optional[RuleDeleteObjectsTransitionCondition]

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

One of the following:

class RuleDeleteObjectsTransitionConditionR2LifecycleAgeCondition: …

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

max_age: int

type: Literal["Age"]

class RuleDeleteObjectsTransitionConditionR2LifecycleDateCondition: …

Condition for lifecycle transitions to apply on a specific date.

date: datetime

formatdate-time

type: Literal["Date"]

storage_class_transitions: Optional[List[RuleStorageClassTransition]]

Transitions to change the storage class of objects.

condition: RuleStorageClassTransitionCondition

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

One of the following:

class RuleStorageClassTransitionConditionR2LifecycleAgeCondition: …

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

max_age: int

type: Literal["Age"]

class RuleStorageClassTransitionConditionR2LifecycleDateCondition: …

Condition for lifecycle transitions to apply on a specific date.

date: datetime

formatdate-time

type: Literal["Date"]

storage_class: Literal["InfrequentAccess"]

BucketsCORS

Get Bucket CORS Policy

r2.buckets.cors.get(, ) -> CORSGetResponse

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

Put Bucket CORS Policy

r2.buckets.cors.update(, ) -> object

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

Delete Bucket CORS Policy

r2.buckets.cors.delete(, ) -> object

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

ModelsExpand Collapse

class CORSGetResponse: …

rules: Optional[List[Rule]]

allowed: RuleAllowed

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

methods: List[Literal["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: List[str]

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

headers: Optional[List[str]]

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[str]

Identifier for this rule.

expose_headers: Optional[List[str]]

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.

max_age_seconds: Optional[float]

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.

BucketsDomains

BucketsDomainsCustom

List Custom Domains of Bucket

r2.buckets.domains.custom.list(, ) -> CustomListResponse

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

Get Custom Domain Settings

r2.buckets.domains.custom.get(, ) -> CustomGetResponse

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

Attach Custom Domain To Bucket

r2.buckets.domains.custom.create(, ) -> CustomCreateResponse

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

Configure Custom Domain Settings

r2.buckets.domains.custom.update(, ) -> CustomUpdateResponse

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

Remove Custom Domain From Bucket

r2.buckets.domains.custom.delete(, ) -> CustomDeleteResponse

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

ModelsExpand Collapse

class CustomListResponse: …

domains: List[Domain]

domain: str

Domain name of the custom domain to be added.

enabled: bool

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

status: DomainStatus

ownership: Literal["pending", "active", "deactivated", 3 more]

Ownership status of the domain.

One of the following:

"pending"

"active"

"deactivated"

"blocked"

"error"

"unknown"

ssl: Literal["initializing", "pending", "active", 3 more]

SSL certificate status.

One of the following:

"initializing"

"pending"

"active"

"deactivated"

"error"

"unknown"

ciphers: Optional[List[str]]

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

min_tls: Optional[Literal["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"

zone_id: Optional[str]

Zone ID of the custom domain resides in.

zone_name: Optional[str]

Zone that the custom domain resides in.

class CustomGetResponse: …

domain: str

Domain name of the custom domain to be added.

enabled: bool

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

status: Status

ownership: Literal["pending", "active", "deactivated", 3 more]

Ownership status of the domain.

One of the following:

"pending"

"active"

"deactivated"

"blocked"

"error"

"unknown"

ssl: Literal["initializing", "pending", "active", 3 more]

SSL certificate status.

One of the following:

"initializing"

"pending"

"active"

"deactivated"

"error"

"unknown"

ciphers: Optional[List[str]]

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

min_tls: Optional[Literal["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"

zone_id: Optional[str]

Zone ID of the custom domain resides in.

zone_name: Optional[str]

Zone that the custom domain resides in.

class CustomCreateResponse: …

domain: str

Domain name of the affected custom domain.

enabled: bool

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

ciphers: Optional[List[str]]

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

min_tls: Optional[Literal["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"

class CustomUpdateResponse: …

domain: str

Domain name of the affected custom domain.

ciphers: Optional[List[str]]

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

enabled: Optional[bool]

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

min_tls: Optional[Literal["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"

class CustomDeleteResponse: …

domain: str

Name of the removed custom domain.

BucketsDomainsManaged

Get r2.dev Domain of Bucket

r2.buckets.domains.managed.list(, ) -> ManagedListResponse

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

Update r2.dev Domain of Bucket

r2.buckets.domains.managed.update(, ) -> ManagedUpdateResponse

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

ModelsExpand Collapse

class ManagedListResponse: …

bucket_id: str

Bucket ID.

maxLength32

domain: str

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

enabled: bool

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

class ManagedUpdateResponse: …

bucket_id: str

Bucket ID.

maxLength32

domain: str

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

enabled: bool

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

ModelsExpand Collapse

class EventNotificationListResponse: …

bucket_name: Optional[str]

Name of the bucket.

queues: Optional[List[Queue]]

List of queues associated with the bucket.

queue_id: Optional[str]

Queue ID.

queue_name: Optional[str]

Name of the queue.

rules: Optional[List[QueueRule]]

actions: List[Literal["PutObject", "CopyObject", "DeleteObject", 2 more]]

Array of R2 object actions that will trigger notifications.

One of the following:

"PutObject"

"CopyObject"

"DeleteObject"

"CompleteMultipartUpload"

"LifecycleDeletion"

created_at: Optional[str]

Timestamp when the rule was created.

description: Optional[str]

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

prefix: Optional[str]

Notifications will be sent only for objects with this prefix.

rule_id: Optional[str]

Rule ID.

suffix: Optional[str]

Notifications will be sent only for objects with this suffix.

class EventNotificationGetResponse: …

queue_id: Optional[str]

Queue ID.

queue_name: Optional[str]

Name of the queue.

rules: Optional[List[Rule]]

actions: List[Literal["PutObject", "CopyObject", "DeleteObject", 2 more]]

Array of R2 object actions that will trigger notifications.

One of the following:

"PutObject"

"CopyObject"

"DeleteObject"

"CompleteMultipartUpload"

"LifecycleDeletion"

created_at: Optional[str]

Timestamp when the rule was created.

description: Optional[str]

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

prefix: Optional[str]

Notifications will be sent only for objects with this prefix.

rule_id: Optional[str]

Rule ID.

suffix: Optional[str]

Notifications will be sent only for objects with this suffix.

BucketsLocks

Get Bucket Lock Rules

r2.buckets.locks.get(, ) -> LockGetResponse

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

Put Bucket Lock Rules

r2.buckets.locks.update(, ) -> object

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

ModelsExpand Collapse

class LockGetResponse: …

rules: Optional[List[Rule]]

id: str

Unique identifier for this rule.

condition: RuleCondition

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

One of the following:

class RuleConditionR2LockRuleAgeCondition: …

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

max_age_seconds: int

type: Literal["Age"]

class RuleConditionR2LockRuleDateCondition: …

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

date: datetime

formatdate-time

type: Literal["Date"]

class RuleConditionR2LockRuleIndefiniteCondition: …

Condition to apply a lock rule indefinitely.

type: Literal["Indefinite"]

enabled: bool

Whether or not this rule is in effect.

prefix: Optional[str]

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.

BucketsMetrics

Get Account-Level Metrics

r2.buckets.metrics.list() -> MetricListResponse

GET/accounts/{account_id}/r2/metrics

ModelsExpand Collapse

class MetricListResponse: …

Metrics based on the class they belong to.

infrequent_access: Optional[InfrequentAccess]

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

published: Optional[InfrequentAccessPublished]

Metrics on number of objects/amount of storage used.

metadata_size: Optional[float]

Amount of.

objects: Optional[float]

Number of objects stored.

payload_size: Optional[float]

Amount of storage used by object data.

uploaded: Optional[InfrequentAccessUploaded]

Metrics on number of objects/amount of storage used.

metadata_size: Optional[float]

Amount of.

objects: Optional[float]

Number of objects stored.

payload_size: Optional[float]

Amount of storage used by object data.

standard: Optional[Standard]

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

published: Optional[StandardPublished]

Metrics on number of objects/amount of storage used.

metadata_size: Optional[float]

Amount of.

objects: Optional[float]

Number of objects stored.

payload_size: Optional[float]

Amount of storage used by object data.

uploaded: Optional[StandardUploaded]

Metrics on number of objects/amount of storage used.

metadata_size: Optional[float]

Amount of.

objects: Optional[float]

Number of objects stored.

payload_size: Optional[float]

Amount of storage used by object data.

ModelsExpand Collapse

Literal["r2"]

class Sippy: …

destination: Optional[Destination]

Details about the configured destination bucket.

access_key_id: Optional[str]

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

account: Optional[str]

bucket: Optional[str]

Name of the bucket on the provider.

provider: Optional[Provider]

enabled: Optional[bool]

State of Sippy for this bucket.

source: Optional[Source]

Details about the configured source bucket.

bucket: Optional[str]

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

bucket_url: Optional[str]

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

provider: Optional[Literal["aws", "gcs", "s3"]]

One of the following:

"aws"

"gcs"

"s3"

region: Optional[str]

Region where the bucket resides (AWS only).

class SippyDeleteResponse: …

enabled: Optional[Literal[false]]

Buckets

ModelsExpand Collapse

BucketsLifecycle

ModelsExpand Collapse

BucketsCORS

ModelsExpand Collapse

BucketsDomains

BucketsDomainsCustom

ModelsExpand Collapse

BucketsDomainsManaged

ModelsExpand Collapse

BucketsEvent Notifications

ModelsExpand Collapse

BucketsLocks

ModelsExpand Collapse

BucketsMetrics

ModelsExpand Collapse

BucketsSippy

ModelsExpand Collapse