# Buckets ## List Buckets `r2.buckets.list(BucketListParams**kwargs) -> BucketListResponse` **get** `/accounts/{account_id}/r2/buckets` Lists all R2 buckets on your account. ### Parameters - `account_id: str` Account ID. - `cursor: Optional[str]` Pagination cursor received during the last List Buckets call. R2 buckets are paginated using cursors instead of page numbers. - `direction: Optional[Literal["asc", "desc"]]` Direction to order buckets. - `"asc"` - `"desc"` - `name_contains: Optional[str]` Bucket names to filter by. Only buckets with this phrase in their name will be returned. - `order: Optional[Literal["name"]]` Field to order buckets by. - `"name"` - `per_page: Optional[float]` Maximum number of buckets to return in a single call. - `start_after: Optional[str]` Bucket name to start searching after. Buckets are ordered lexicographically. - `jurisdiction: Optional[Literal["default", "eu", "fedramp"]]` Jurisdiction where objects in this bucket are guaranteed to be stored. - `"default"` - `"eu"` - `"fedramp"` ### Returns - `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. - `"default"` - `"eu"` - `"fedramp"` - `location: Optional[Literal["apac", "eeur", "enam", 3 more]]` Location of the bucket. - `"apac"` - `"eeur"` - `"enam"` - `"weur"` - `"wnam"` - `"oc"` - `name: Optional[str]` Name of the bucket. - `storage_class: Optional[Literal["Standard", "InfrequentAccess"]]` Storage class for newly uploaded objects, unless specified otherwise. - `"Standard"` - `"InfrequentAccess"` ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) buckets = client.r2.buckets.list( account_id="023e105f4ecef8ad9ca31a8372d0c353", ) print(buckets.buckets) ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ "string" ], "result": { "buckets": [ { "creation_date": "creation_date", "jurisdiction": "default", "location": "apac", "name": "example-bucket", "storage_class": "Standard" } ] }, "success": true, "result_info": { "cursor": "1-JTdCJTIydiUyMiUzQTElMkMlMjJzdGFydEFmdGVyJTIyJTNBJTIyZGF2aWRwdWJsaWMlMjIlN0Q=", "per_page": 20 } } ``` ## Get Bucket `r2.buckets.get(strbucket_name, BucketGetParams**kwargs) -> Bucket` **get** `/accounts/{account_id}/r2/buckets/{bucket_name}` Gets properties of an existing R2 bucket. ### Parameters - `account_id: str` Account ID. - `bucket_name: str` Name of the bucket. - `jurisdiction: Optional[Literal["default", "eu", "fedramp"]]` Jurisdiction where objects in this bucket are guaranteed to be stored. - `"default"` - `"eu"` - `"fedramp"` ### Returns - `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. - `"default"` - `"eu"` - `"fedramp"` - `location: Optional[Literal["apac", "eeur", "enam", 3 more]]` Location of the bucket. - `"apac"` - `"eeur"` - `"enam"` - `"weur"` - `"wnam"` - `"oc"` - `name: Optional[str]` Name of the bucket. - `storage_class: Optional[Literal["Standard", "InfrequentAccess"]]` Storage class for newly uploaded objects, unless specified otherwise. - `"Standard"` - `"InfrequentAccess"` ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) bucket = client.r2.buckets.get( bucket_name="example-bucket", account_id="023e105f4ecef8ad9ca31a8372d0c353", ) print(bucket.creation_date) ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ "string" ], "result": { "creation_date": "creation_date", "jurisdiction": "default", "location": "apac", "name": "example-bucket", "storage_class": "Standard" }, "success": true } ``` ## Create Bucket `r2.buckets.create(BucketCreateParams**kwargs) -> Bucket` **post** `/accounts/{account_id}/r2/buckets` Creates a new R2 bucket. ### Parameters - `account_id: str` Account ID. - `name: str` Name of the bucket. - `location_hint: Optional[Literal["apac", "eeur", "enam", 3 more]]` Location of the bucket. - `"apac"` - `"eeur"` - `"enam"` - `"weur"` - `"wnam"` - `"oc"` - `storage_class: Optional[Literal["Standard", "InfrequentAccess"]]` Storage class for newly uploaded objects, unless specified otherwise. - `"Standard"` - `"InfrequentAccess"` - `jurisdiction: Optional[Literal["default", "eu", "fedramp"]]` Jurisdiction where objects in this bucket are guaranteed to be stored. - `"default"` - `"eu"` - `"fedramp"` ### Returns - `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. - `"default"` - `"eu"` - `"fedramp"` - `location: Optional[Literal["apac", "eeur", "enam", 3 more]]` Location of the bucket. - `"apac"` - `"eeur"` - `"enam"` - `"weur"` - `"wnam"` - `"oc"` - `name: Optional[str]` Name of the bucket. - `storage_class: Optional[Literal["Standard", "InfrequentAccess"]]` Storage class for newly uploaded objects, unless specified otherwise. - `"Standard"` - `"InfrequentAccess"` ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) bucket = client.r2.buckets.create( account_id="023e105f4ecef8ad9ca31a8372d0c353", name="example-bucket", ) print(bucket.creation_date) ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ "string" ], "result": { "creation_date": "creation_date", "jurisdiction": "default", "location": "apac", "name": "example-bucket", "storage_class": "Standard" }, "success": true } ``` ## Patch Bucket `r2.buckets.edit(strbucket_name, BucketEditParams**kwargs) -> Bucket` **patch** `/accounts/{account_id}/r2/buckets/{bucket_name}` Updates properties of an existing R2 bucket. ### Parameters - `account_id: str` Account ID. - `bucket_name: str` Name of the bucket. - `storage_class: Literal["Standard", "InfrequentAccess"]` Storage class for newly uploaded objects, unless specified otherwise. - `"Standard"` - `"InfrequentAccess"` - `jurisdiction: Optional[Literal["default", "eu", "fedramp"]]` Jurisdiction where objects in this bucket are guaranteed to be stored. - `"default"` - `"eu"` - `"fedramp"` ### Returns - `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. - `"default"` - `"eu"` - `"fedramp"` - `location: Optional[Literal["apac", "eeur", "enam", 3 more]]` Location of the bucket. - `"apac"` - `"eeur"` - `"enam"` - `"weur"` - `"wnam"` - `"oc"` - `name: Optional[str]` Name of the bucket. - `storage_class: Optional[Literal["Standard", "InfrequentAccess"]]` Storage class for newly uploaded objects, unless specified otherwise. - `"Standard"` - `"InfrequentAccess"` ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) bucket = client.r2.buckets.edit( bucket_name="example-bucket", account_id="023e105f4ecef8ad9ca31a8372d0c353", storage_class="Standard", ) print(bucket.creation_date) ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ "string" ], "result": { "creation_date": "creation_date", "jurisdiction": "default", "location": "apac", "name": "example-bucket", "storage_class": "Standard" }, "success": true } ``` ## Delete Bucket `r2.buckets.delete(strbucket_name, BucketDeleteParams**kwargs) -> object` **delete** `/accounts/{account_id}/r2/buckets/{bucket_name}` Deletes an existing R2 bucket. ### Parameters - `account_id: str` Account ID. - `bucket_name: str` Name of the bucket. - `jurisdiction: Optional[Literal["default", "eu", "fedramp"]]` Jurisdiction where objects in this bucket are guaranteed to be stored. - `"default"` - `"eu"` - `"fedramp"` ### Returns - `object` ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) bucket = client.r2.buckets.delete( bucket_name="example-bucket", account_id="023e105f4ecef8ad9ca31a8372d0c353", ) print(bucket) ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ "string" ], "result": {}, "success": true } ``` ## Domain Types ### Bucket - `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. - `"default"` - `"eu"` - `"fedramp"` - `location: Optional[Literal["apac", "eeur", "enam", 3 more]]` Location of the bucket. - `"apac"` - `"eeur"` - `"enam"` - `"weur"` - `"wnam"` - `"oc"` - `name: Optional[str]` Name of the bucket. - `storage_class: Optional[Literal["Standard", "InfrequentAccess"]]` Storage class for newly uploaded objects, unless specified otherwise. - `"Standard"` - `"InfrequentAccess"` ### Bucket List Response - `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. - `"default"` - `"eu"` - `"fedramp"` - `location: Optional[Literal["apac", "eeur", "enam", 3 more]]` Location of the bucket. - `"apac"` - `"eeur"` - `"enam"` - `"weur"` - `"wnam"` - `"oc"` - `name: Optional[str]` Name of the bucket. - `storage_class: Optional[Literal["Standard", "InfrequentAccess"]]` Storage class for newly uploaded objects, unless specified otherwise. - `"Standard"` - `"InfrequentAccess"` # Lifecycle ## Get Object Lifecycle Rules `r2.buckets.lifecycle.get(strbucket_name, LifecycleGetParams**kwargs) -> LifecycleGetResponse` **get** `/accounts/{account_id}/r2/buckets/{bucket_name}/lifecycle` Get object lifecycle rules for a bucket. ### Parameters - `account_id: str` Account ID. - `bucket_name: str` Name of the bucket. - `jurisdiction: Optional[Literal["default", "eu", "fedramp"]]` Jurisdiction where objects in this bucket are guaranteed to be stored. - `"default"` - `"eu"` - `"fedramp"` ### Returns - `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"]` - `"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. - `class RuleDeleteObjectsTransitionConditionR2LifecycleAgeCondition: …` Condition for lifecycle transitions to apply after an object reaches an age in seconds. - `max_age: int` - `type: Literal["Age"]` - `"Age"` - `class RuleDeleteObjectsTransitionConditionR2LifecycleDateCondition: …` Condition for lifecycle transitions to apply on a specific date. - `date: datetime` - `type: Literal["Date"]` - `"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. - `class RuleStorageClassTransitionConditionR2LifecycleAgeCondition: …` Condition for lifecycle transitions to apply after an object reaches an age in seconds. - `max_age: int` - `type: Literal["Age"]` - `"Age"` - `class RuleStorageClassTransitionConditionR2LifecycleDateCondition: …` Condition for lifecycle transitions to apply on a specific date. - `date: datetime` - `type: Literal["Date"]` - `"Date"` - `storage_class: Literal["InfrequentAccess"]` - `"InfrequentAccess"` ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) lifecycle = client.r2.buckets.lifecycle.get( bucket_name="example-bucket", account_id="023e105f4ecef8ad9ca31a8372d0c353", ) print(lifecycle.rules) ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ "string" ], "result": { "rules": [ { "id": "Expire all objects older than 24 hours", "conditions": { "prefix": "prefix" }, "enabled": true, "abortMultipartUploadsTransition": { "condition": { "maxAge": 0, "type": "Age" } }, "deleteObjectsTransition": { "condition": { "maxAge": 0, "type": "Age" } }, "storageClassTransitions": [ { "condition": { "maxAge": 0, "type": "Age" }, "storageClass": "InfrequentAccess" } ] } ] }, "success": true } ``` ## Put Object Lifecycle Rules `r2.buckets.lifecycle.update(strbucket_name, LifecycleUpdateParams**kwargs) -> object` **put** `/accounts/{account_id}/r2/buckets/{bucket_name}/lifecycle` Set the object lifecycle rules for a bucket. ### Parameters - `account_id: str` Account ID. - `bucket_name: str` Name of the bucket. - `rules: Optional[Iterable[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"]` - `"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. - `class RuleDeleteObjectsTransitionConditionR2LifecycleAgeCondition: …` Condition for lifecycle transitions to apply after an object reaches an age in seconds. - `max_age: int` - `type: Literal["Age"]` - `"Age"` - `class RuleDeleteObjectsTransitionConditionR2LifecycleDateCondition: …` Condition for lifecycle transitions to apply on a specific date. - `date: Union[str, datetime]` - `type: Literal["Date"]` - `"Date"` - `storage_class_transitions: Optional[Iterable[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. - `class RuleStorageClassTransitionConditionR2LifecycleAgeCondition: …` Condition for lifecycle transitions to apply after an object reaches an age in seconds. - `max_age: int` - `type: Literal["Age"]` - `"Age"` - `class RuleStorageClassTransitionConditionR2LifecycleDateCondition: …` Condition for lifecycle transitions to apply on a specific date. - `date: Union[str, datetime]` - `type: Literal["Date"]` - `"Date"` - `storage_class: Literal["InfrequentAccess"]` - `"InfrequentAccess"` - `jurisdiction: Optional[Literal["default", "eu", "fedramp"]]` Jurisdiction where objects in this bucket are guaranteed to be stored. - `"default"` - `"eu"` - `"fedramp"` ### Returns - `object` ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) lifecycle = client.r2.buckets.lifecycle.update( bucket_name="example-bucket", account_id="023e105f4ecef8ad9ca31a8372d0c353", ) print(lifecycle) ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ "string" ], "result": {}, "success": true } ``` ## Domain Types ### Lifecycle Get Response - `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"]` - `"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. - `class RuleDeleteObjectsTransitionConditionR2LifecycleAgeCondition: …` Condition for lifecycle transitions to apply after an object reaches an age in seconds. - `max_age: int` - `type: Literal["Age"]` - `"Age"` - `class RuleDeleteObjectsTransitionConditionR2LifecycleDateCondition: …` Condition for lifecycle transitions to apply on a specific date. - `date: datetime` - `type: Literal["Date"]` - `"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. - `class RuleStorageClassTransitionConditionR2LifecycleAgeCondition: …` Condition for lifecycle transitions to apply after an object reaches an age in seconds. - `max_age: int` - `type: Literal["Age"]` - `"Age"` - `class RuleStorageClassTransitionConditionR2LifecycleDateCondition: …` Condition for lifecycle transitions to apply on a specific date. - `date: datetime` - `type: Literal["Date"]` - `"Date"` - `storage_class: Literal["InfrequentAccess"]` - `"InfrequentAccess"` # CORS ## Get Bucket CORS Policy `r2.buckets.cors.get(strbucket_name, CORSGetParams**kwargs) -> CORSGetResponse` **get** `/accounts/{account_id}/r2/buckets/{bucket_name}/cors` Get the CORS policy for a bucket. ### Parameters - `account_id: str` Account ID. - `bucket_name: str` Name of the bucket. - `jurisdiction: Optional[Literal["default", "eu", "fedramp"]]` Jurisdiction where objects in this bucket are guaranteed to be stored. - `"default"` - `"eu"` - `"fedramp"` ### Returns - `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. - `"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. ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) cors = client.r2.buckets.cors.get( bucket_name="example-bucket", account_id="023e105f4ecef8ad9ca31a8372d0c353", ) print(cors.rules) ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ "string" ], "result": { "rules": [ { "allowed": { "methods": [ "GET" ], "origins": [ "http://localhost:3000" ], "headers": [ "x-requested-by" ] }, "id": "Allow Local Development", "exposeHeaders": [ "Content-Encoding" ], "maxAgeSeconds": 3600 } ] }, "success": true } ``` ## Put Bucket CORS Policy `r2.buckets.cors.update(strbucket_name, CORSUpdateParams**kwargs) -> object` **put** `/accounts/{account_id}/r2/buckets/{bucket_name}/cors` Set the CORS policy for a bucket. ### Parameters - `account_id: str` Account ID. - `bucket_name: str` Name of the bucket. - `rules: Optional[Iterable[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. - `"GET"` - `"PUT"` - `"POST"` - `"DELETE"` - `"HEAD"` - `origins: SequenceNotStr[str]` Specifies the value for the Access-Control-Allow-Origin header R2 sets when requesting objects in a bucket from a browser. - `headers: Optional[SequenceNotStr[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[SequenceNotStr[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. - `jurisdiction: Optional[Literal["default", "eu", "fedramp"]]` Jurisdiction where objects in this bucket are guaranteed to be stored. - `"default"` - `"eu"` - `"fedramp"` ### Returns - `object` ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) cors = client.r2.buckets.cors.update( bucket_name="example-bucket", account_id="023e105f4ecef8ad9ca31a8372d0c353", ) print(cors) ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ "string" ], "result": {}, "success": true } ``` ## Delete Bucket CORS Policy `r2.buckets.cors.delete(strbucket_name, CORSDeleteParams**kwargs) -> object` **delete** `/accounts/{account_id}/r2/buckets/{bucket_name}/cors` Delete the CORS policy for a bucket. ### Parameters - `account_id: str` Account ID. - `bucket_name: str` Name of the bucket. - `jurisdiction: Optional[Literal["default", "eu", "fedramp"]]` Jurisdiction where objects in this bucket are guaranteed to be stored. - `"default"` - `"eu"` - `"fedramp"` ### Returns - `object` ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) cors = client.r2.buckets.cors.delete( bucket_name="example-bucket", account_id="023e105f4ecef8ad9ca31a8372d0c353", ) print(cors) ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ "string" ], "result": {}, "success": true } ``` ## Domain Types ### CORS Get Response - `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. - `"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. # Domains # Custom ## List Custom Domains of Bucket `r2.buckets.domains.custom.list(strbucket_name, CustomListParams**kwargs) -> CustomListResponse` **get** `/accounts/{account_id}/r2/buckets/{bucket_name}/domains/custom` Gets a list of all custom domains registered with an existing R2 bucket. ### Parameters - `account_id: str` Account ID. - `bucket_name: str` Name of the bucket. - `jurisdiction: Optional[Literal["default", "eu", "fedramp"]]` Jurisdiction where objects in this bucket are guaranteed to be stored. - `"default"` - `"eu"` - `"fedramp"` ### Returns - `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. - `"pending"` - `"active"` - `"deactivated"` - `"blocked"` - `"error"` - `"unknown"` - `ssl: Literal["initializing", "pending", "active", 3 more]` SSL certificate status. - `"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. - `"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. ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) customs = client.r2.buckets.domains.custom.list( bucket_name="example-bucket", account_id="023e105f4ecef8ad9ca31a8372d0c353", ) print(customs.domains) ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ "string" ], "result": { "domains": [ { "domain": "prefix.example-domain.one.com", "enabled": false, "status": { "ownership": "deactivated", "ssl": "pending" }, "ciphers": [ "string" ], "minTLS": "1.0", "zoneId": "36ca64a6d92827b8a6b90be344bb1bfd", "zoneName": "example-domain.one.com" }, { "domain": "prefix.example-domain.two.com", "enabled": true, "status": { "ownership": "active", "ssl": "active" }, "ciphers": [ "string" ], "minTLS": "1.0", "zoneId": "d9d28585d5f8f5b0f857b055bf574f19", "zoneName": "zoneName" } ] }, "success": true } ``` ## Get Custom Domain Settings `r2.buckets.domains.custom.get(strdomain, CustomGetParams**kwargs) -> CustomGetResponse` **get** `/accounts/{account_id}/r2/buckets/{bucket_name}/domains/custom/{domain}` Get the configuration for a custom domain on an existing R2 bucket. ### Parameters - `account_id: str` Account ID. - `bucket_name: str` Name of the bucket. - `domain: str` Name of the custom domain. - `jurisdiction: Optional[Literal["default", "eu", "fedramp"]]` Jurisdiction where objects in this bucket are guaranteed to be stored. - `"default"` - `"eu"` - `"fedramp"` ### Returns - `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. - `"pending"` - `"active"` - `"deactivated"` - `"blocked"` - `"error"` - `"unknown"` - `ssl: Literal["initializing", "pending", "active", 3 more]` SSL certificate status. - `"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. - `"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. ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) custom = client.r2.buckets.domains.custom.get( domain="example-domain/custom-domain.com", account_id="023e105f4ecef8ad9ca31a8372d0c353", bucket_name="example-bucket", ) print(custom.domain) ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ "string" ], "result": { "domain": "prefix.example-domain.one.com", "enabled": false, "status": { "ownership": "deactivated", "ssl": "pending" }, "ciphers": [ "string" ], "minTLS": "1.0", "zoneId": "36ca64a6d92827b8a6b90be344bb1bfd", "zoneName": "example-domain.one.com" }, "success": true } ``` ## Attach Custom Domain To Bucket `r2.buckets.domains.custom.create(strbucket_name, CustomCreateParams**kwargs) -> CustomCreateResponse` **post** `/accounts/{account_id}/r2/buckets/{bucket_name}/domains/custom` Register a new custom domain for an existing R2 bucket. ### Parameters - `account_id: str` Account ID. - `bucket_name: str` Name of the bucket. - `domain: str` Name of the custom domain to be added. - `enabled: bool` Whether to enable public bucket access at the custom domain. If undefined, the domain will be enabled. - `zone_id: str` Zone ID of the custom domain. - `ciphers: Optional[SequenceNotStr[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. - `"1.0"` - `"1.1"` - `"1.2"` - `"1.3"` - `jurisdiction: Optional[Literal["default", "eu", "fedramp"]]` Jurisdiction where objects in this bucket are guaranteed to be stored. - `"default"` - `"eu"` - `"fedramp"` ### Returns - `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. - `"1.0"` - `"1.1"` - `"1.2"` - `"1.3"` ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) custom = client.r2.buckets.domains.custom.create( bucket_name="example-bucket", account_id="023e105f4ecef8ad9ca31a8372d0c353", domain="prefix.example-domain.com", enabled=True, zone_id="36ca64a6d92827b8a6b90be344bb1bfd", ) print(custom.domain) ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ "string" ], "result": { "domain": "example-domain.com", "enabled": true, "ciphers": [ "string" ], "minTLS": "1.0" }, "success": true } ``` ## Configure Custom Domain Settings `r2.buckets.domains.custom.update(strdomain, CustomUpdateParams**kwargs) -> CustomUpdateResponse` **put** `/accounts/{account_id}/r2/buckets/{bucket_name}/domains/custom/{domain}` Edit the configuration for a custom domain on an existing R2 bucket. ### Parameters - `account_id: str` Account ID. - `bucket_name: str` Name of the bucket. - `domain: str` Name of the custom domain. - `ciphers: Optional[SequenceNotStr[str]]` An allowlist of ciphers for TLS termination. These ciphers must be in the BoringSSL format. - `enabled: Optional[bool]` Whether to enable public bucket access 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 previous value. - `"1.0"` - `"1.1"` - `"1.2"` - `"1.3"` - `jurisdiction: Optional[Literal["default", "eu", "fedramp"]]` Jurisdiction where objects in this bucket are guaranteed to be stored. - `"default"` - `"eu"` - `"fedramp"` ### Returns - `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. - `"1.0"` - `"1.1"` - `"1.2"` - `"1.3"` ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) custom = client.r2.buckets.domains.custom.update( domain="example-domain/custom-domain.com", account_id="023e105f4ecef8ad9ca31a8372d0c353", bucket_name="example-bucket", ) print(custom.domain) ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ "string" ], "result": { "domain": "example-domain.com", "ciphers": [ "string" ], "enabled": true, "minTLS": "1.0" }, "success": true } ``` ## Remove Custom Domain From Bucket `r2.buckets.domains.custom.delete(strdomain, CustomDeleteParams**kwargs) -> CustomDeleteResponse` **delete** `/accounts/{account_id}/r2/buckets/{bucket_name}/domains/custom/{domain}` Remove custom domain registration from an existing R2 bucket. ### Parameters - `account_id: str` Account ID. - `bucket_name: str` Name of the bucket. - `domain: str` Name of the custom domain. - `jurisdiction: Optional[Literal["default", "eu", "fedramp"]]` Jurisdiction where objects in this bucket are guaranteed to be stored. - `"default"` - `"eu"` - `"fedramp"` ### Returns - `class CustomDeleteResponse: …` - `domain: str` Name of the removed custom domain. ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) custom = client.r2.buckets.domains.custom.delete( domain="example-domain/custom-domain.com", account_id="023e105f4ecef8ad9ca31a8372d0c353", bucket_name="example-bucket", ) print(custom.domain) ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ "string" ], "result": { "domain": "example-domain/custom-domain.com" }, "success": true } ``` ## Domain Types ### Custom List Response - `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. - `"pending"` - `"active"` - `"deactivated"` - `"blocked"` - `"error"` - `"unknown"` - `ssl: Literal["initializing", "pending", "active", 3 more]` SSL certificate status. - `"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. - `"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. ### Custom Get Response - `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. - `"pending"` - `"active"` - `"deactivated"` - `"blocked"` - `"error"` - `"unknown"` - `ssl: Literal["initializing", "pending", "active", 3 more]` SSL certificate status. - `"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. - `"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. ### Custom Create Response - `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. - `"1.0"` - `"1.1"` - `"1.2"` - `"1.3"` ### Custom Update Response - `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. - `"1.0"` - `"1.1"` - `"1.2"` - `"1.3"` ### Custom Delete Response - `class CustomDeleteResponse: …` - `domain: str` Name of the removed custom domain. # Managed ## Get r2.dev Domain of Bucket `r2.buckets.domains.managed.list(strbucket_name, ManagedListParams**kwargs) -> ManagedListResponse` **get** `/accounts/{account_id}/r2/buckets/{bucket_name}/domains/managed` Gets state of public access over the bucket's R2-managed (r2.dev) domain. ### Parameters - `account_id: str` Account ID. - `bucket_name: str` Name of the bucket. - `jurisdiction: Optional[Literal["default", "eu", "fedramp"]]` Jurisdiction where objects in this bucket are guaranteed to be stored. - `"default"` - `"eu"` - `"fedramp"` ### Returns - `class ManagedListResponse: …` - `bucket_id: str` Bucket ID. - `domain: str` Domain name of the bucket's r2.dev domain. - `enabled: bool` Whether this bucket is publicly accessible at the r2.dev domain. ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) manageds = client.r2.buckets.domains.managed.list( bucket_name="example-bucket", account_id="023e105f4ecef8ad9ca31a8372d0c353", ) print(manageds.bucket_id) ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ "string" ], "result": { "bucketId": "0113a9e4549cf9b1ff1bf56e04da0cef", "domain": "pub-0113a9e4549cf9b1ff1bf56e04da0cef.r2.dev", "enabled": true }, "success": true } ``` ## Update r2.dev Domain of Bucket `r2.buckets.domains.managed.update(strbucket_name, ManagedUpdateParams**kwargs) -> ManagedUpdateResponse` **put** `/accounts/{account_id}/r2/buckets/{bucket_name}/domains/managed` Updates state of public access over the bucket's R2-managed (r2.dev) domain. ### Parameters - `account_id: str` Account ID. - `bucket_name: str` Name of the bucket. - `enabled: bool` Whether to enable public bucket access at the r2.dev domain. - `jurisdiction: Optional[Literal["default", "eu", "fedramp"]]` Jurisdiction where objects in this bucket are guaranteed to be stored. - `"default"` - `"eu"` - `"fedramp"` ### Returns - `class ManagedUpdateResponse: …` - `bucket_id: str` Bucket ID. - `domain: str` Domain name of the bucket's r2.dev domain. - `enabled: bool` Whether this bucket is publicly accessible at the r2.dev domain. ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) managed = client.r2.buckets.domains.managed.update( bucket_name="example-bucket", account_id="023e105f4ecef8ad9ca31a8372d0c353", enabled=True, ) print(managed.bucket_id) ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ "string" ], "result": { "bucketId": "0113a9e4549cf9b1ff1bf56e04da0cef", "domain": "pub-0113a9e4549cf9b1ff1bf56e04da0cef.r2.dev", "enabled": true }, "success": true } ``` ## Domain Types ### Managed List Response - `class ManagedListResponse: …` - `bucket_id: str` Bucket ID. - `domain: str` Domain name of the bucket's r2.dev domain. - `enabled: bool` Whether this bucket is publicly accessible at the r2.dev domain. ### Managed Update Response - `class ManagedUpdateResponse: …` - `bucket_id: str` Bucket ID. - `domain: str` Domain name of the bucket's r2.dev domain. - `enabled: bool` Whether this bucket is publicly accessible at the r2.dev domain. # Event Notifications ## List Event Notification Rules `r2.buckets.event_notifications.list(strbucket_name, EventNotificationListParams**kwargs) -> EventNotificationListResponse` **get** `/accounts/{account_id}/event_notifications/r2/{bucket_name}/configuration` List all event notification rules for a bucket. ### Parameters - `account_id: str` Account ID. - `bucket_name: str` Name of the bucket. - `jurisdiction: Optional[Literal["default", "eu", "fedramp"]]` Jurisdiction where objects in this bucket are guaranteed to be stored. - `"default"` - `"eu"` - `"fedramp"` ### Returns - `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. - `"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. ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) event_notifications = client.r2.buckets.event_notifications.list( bucket_name="example-bucket", account_id="023e105f4ecef8ad9ca31a8372d0c353", ) print(event_notifications.bucket_name) ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ "string" ], "result": { "bucketName": "bucketName", "queues": [ { "queueId": "11111aa1-11aa-111a-a1a1-a1a111a11a11", "queueName": "first-queue", "rules": [ { "actions": [ "PutObject", "CopyObject" ], "createdAt": "2024-09-19T21:54:48.405Z", "description": "Notifications from source bucket to queue", "prefix": "img/", "ruleId": "11111aa1-11aa-111a-a1a1-a1a111a11a11", "suffix": ".jpeg" } ] } ] }, "success": true } ``` ## Get Event Notification Rule `r2.buckets.event_notifications.get(strqueue_id, EventNotificationGetParams**kwargs) -> EventNotificationGetResponse` **get** `/accounts/{account_id}/event_notifications/r2/{bucket_name}/configuration/queues/{queue_id}` Get a single event notification rule. ### Parameters - `account_id: str` Account ID. - `bucket_name: str` Name of the bucket. - `queue_id: str` Queue ID. - `jurisdiction: Optional[Literal["default", "eu", "fedramp"]]` The bucket jurisdiction. - `"default"` - `"eu"` - `"fedramp"` ### Returns - `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. - `"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. ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) event_notification = client.r2.buckets.event_notifications.get( queue_id="queue_id", account_id="023e105f4ecef8ad9ca31a8372d0c353", bucket_name="example-bucket", ) print(event_notification.queue_id) ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ "string" ], "result": { "queueId": "11111aa1-11aa-111a-a1a1-a1a111a11a11", "queueName": "first-queue", "rules": [ { "actions": [ "PutObject", "CopyObject" ], "createdAt": "2024-09-19T21:54:48.405Z", "description": "Notifications from source bucket to queue", "prefix": "img/", "ruleId": "11111aa1-11aa-111a-a1a1-a1a111a11a11", "suffix": ".jpeg" } ] }, "success": true } ``` ## Create Event Notification Rule `r2.buckets.event_notifications.update(strqueue_id, EventNotificationUpdateParams**kwargs) -> object` **put** `/accounts/{account_id}/event_notifications/r2/{bucket_name}/configuration/queues/{queue_id}` Create event notification rule. ### Parameters - `account_id: str` Account ID. - `bucket_name: str` Name of the bucket. - `queue_id: str` Queue ID. - `rules: Iterable[Rule]` Array of rules to drive notifications. - `actions: List[Literal["PutObject", "CopyObject", "DeleteObject", 2 more]]` Array of R2 object actions that will trigger notifications. - `"PutObject"` - `"CopyObject"` - `"DeleteObject"` - `"CompleteMultipartUpload"` - `"LifecycleDeletion"` - `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. - `suffix: Optional[str]` Notifications will be sent only for objects with this suffix. - `jurisdiction: Optional[Literal["default", "eu", "fedramp"]]` Jurisdiction where objects in this bucket are guaranteed to be stored. - `"default"` - `"eu"` - `"fedramp"` ### Returns - `object` ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) event_notification = client.r2.buckets.event_notifications.update( queue_id="queue_id", account_id="023e105f4ecef8ad9ca31a8372d0c353", bucket_name="example-bucket", rules=[{ "actions": ["PutObject", "CopyObject"] }], ) print(event_notification) ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ "string" ], "result": {}, "success": true } ``` ## Delete Event Notification Rules `r2.buckets.event_notifications.delete(strqueue_id, EventNotificationDeleteParams**kwargs) -> object` **delete** `/accounts/{account_id}/event_notifications/r2/{bucket_name}/configuration/queues/{queue_id}` Delete an event notification rule. **If no body is provided, all rules for specified queue will be deleted**. ### Parameters - `account_id: str` Account ID. - `bucket_name: str` Name of the bucket. - `queue_id: str` Queue ID. - `jurisdiction: Optional[Literal["default", "eu", "fedramp"]]` Jurisdiction where objects in this bucket are guaranteed to be stored. - `"default"` - `"eu"` - `"fedramp"` ### Returns - `object` ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) event_notification = client.r2.buckets.event_notifications.delete( queue_id="queue_id", account_id="023e105f4ecef8ad9ca31a8372d0c353", bucket_name="example-bucket", ) print(event_notification) ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ "string" ], "result": {}, "success": true } ``` ## Domain Types ### Event Notification List Response - `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. - `"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. ### Event Notification Get Response - `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. - `"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. # Locks ## Get Bucket Lock Rules `r2.buckets.locks.get(strbucket_name, LockGetParams**kwargs) -> LockGetResponse` **get** `/accounts/{account_id}/r2/buckets/{bucket_name}/lock` Get lock rules for a bucket. ### Parameters - `account_id: str` Account ID. - `bucket_name: str` Name of the bucket. - `jurisdiction: Optional[Literal["default", "eu", "fedramp"]]` Jurisdiction where objects in this bucket are guaranteed to be stored. - `"default"` - `"eu"` - `"fedramp"` ### Returns - `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. - `class RuleConditionR2LockRuleAgeCondition: …` Condition to apply a lock rule to an object for how long in seconds. - `max_age_seconds: int` - `type: Literal["Age"]` - `"Age"` - `class RuleConditionR2LockRuleDateCondition: …` Condition to apply a lock rule to an object until a specific date. - `date: datetime` - `type: Literal["Date"]` - `"Date"` - `class RuleConditionR2LockRuleIndefiniteCondition: …` Condition to apply a lock rule indefinitely. - `type: Literal["Indefinite"]` - `"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. ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) lock = client.r2.buckets.locks.get( bucket_name="example-bucket", account_id="023e105f4ecef8ad9ca31a8372d0c353", ) print(lock.rules) ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ "string" ], "result": { "rules": [ { "id": "Lock all objects for 24 hours", "condition": { "maxAgeSeconds": 100, "type": "Age" }, "enabled": true, "prefix": "prefix" } ] }, "success": true } ``` ## Put Bucket Lock Rules `r2.buckets.locks.update(strbucket_name, LockUpdateParams**kwargs) -> object` **put** `/accounts/{account_id}/r2/buckets/{bucket_name}/lock` Set lock rules for a bucket. ### Parameters - `account_id: str` Account ID. - `bucket_name: str` Name of the bucket. - `rules: Optional[Iterable[Rule]]` - `id: str` Unique identifier for this rule. - `condition: RuleCondition` Condition to apply a lock rule to an object for how long in seconds. - `class RuleConditionR2LockRuleAgeCondition: …` Condition to apply a lock rule to an object for how long in seconds. - `max_age_seconds: int` - `type: Literal["Age"]` - `"Age"` - `class RuleConditionR2LockRuleDateCondition: …` Condition to apply a lock rule to an object until a specific date. - `date: Union[str, datetime]` - `type: Literal["Date"]` - `"Date"` - `class RuleConditionR2LockRuleIndefiniteCondition: …` Condition to apply a lock rule indefinitely. - `type: Literal["Indefinite"]` - `"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. - `jurisdiction: Optional[Literal["default", "eu", "fedramp"]]` Jurisdiction where objects in this bucket are guaranteed to be stored. - `"default"` - `"eu"` - `"fedramp"` ### Returns - `object` ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) lock = client.r2.buckets.locks.update( bucket_name="example-bucket", account_id="023e105f4ecef8ad9ca31a8372d0c353", ) print(lock) ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ "string" ], "result": {}, "success": true } ``` ## Domain Types ### Lock Get Response - `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. - `class RuleConditionR2LockRuleAgeCondition: …` Condition to apply a lock rule to an object for how long in seconds. - `max_age_seconds: int` - `type: Literal["Age"]` - `"Age"` - `class RuleConditionR2LockRuleDateCondition: …` Condition to apply a lock rule to an object until a specific date. - `date: datetime` - `type: Literal["Date"]` - `"Date"` - `class RuleConditionR2LockRuleIndefiniteCondition: …` Condition to apply a lock rule indefinitely. - `type: Literal["Indefinite"]` - `"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. # Metrics ## Get Account-Level Metrics `r2.buckets.metrics.list(MetricListParams**kwargs) -> MetricListResponse` **get** `/accounts/{account_id}/r2/metrics` Get Storage/Object Count Metrics across all buckets in your account. Note that Account-Level Metrics may not immediately reflect the latest data. ### Parameters - `account_id: str` Account ID. ### Returns - `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. ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) metrics = client.r2.buckets.metrics.list( account_id="023e105f4ecef8ad9ca31a8372d0c353", ) print(metrics.infrequent_access) ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ "string" ], "result": { "infrequentAccess": { "published": { "metadataSize": 0, "objects": 0, "payloadSize": 0 }, "uploaded": { "metadataSize": 0, "objects": 0, "payloadSize": 0 } }, "standard": { "published": { "metadataSize": 0, "objects": 0, "payloadSize": 0 }, "uploaded": { "metadataSize": 0, "objects": 0, "payloadSize": 0 } } }, "success": true } ``` ## Domain Types ### Metric List Response - `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. # Sippy ## Get Sippy Configuration `r2.buckets.sippy.get(strbucket_name, SippyGetParams**kwargs) -> Sippy` **get** `/accounts/{account_id}/r2/buckets/{bucket_name}/sippy` Gets configuration for Sippy for an existing R2 bucket. ### Parameters - `account_id: str` Account ID. - `bucket_name: str` Name of the bucket. - `jurisdiction: Optional[Literal["default", "eu", "fedramp"]]` Jurisdiction where objects in this bucket are guaranteed to be stored. - `"default"` - `"eu"` - `"fedramp"` ### Returns - `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]` - `"r2"` - `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"]]` - `"aws"` - `"gcs"` - `"s3"` - `region: Optional[str]` Region where the bucket resides (AWS only). ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) sippy = client.r2.buckets.sippy.get( bucket_name="example-bucket", account_id="023e105f4ecef8ad9ca31a8372d0c353", ) print(sippy.destination) ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ "string" ], "result": { "destination": { "accessKeyId": "accessKeyId", "account": "account", "bucket": "bucket", "provider": "r2" }, "enabled": true, "source": { "bucket": "bucket", "bucketUrl": "bucketUrl", "provider": "aws", "region": "region" } }, "success": true } ``` ## Enable Sippy `r2.buckets.sippy.update(strbucket_name, SippyUpdateParams**kwargs) -> Sippy` **put** `/accounts/{account_id}/r2/buckets/{bucket_name}/sippy` Sets configuration for Sippy for an existing R2 bucket. ### Parameters - `account_id: str` Account ID. - `bucket_name: str` Name of the bucket. - `destination: Optional[R2EnableSippyAwsDestination]` R2 bucket to copy objects to. - `access_key_id: Optional[str]` ID of a Cloudflare API token. This is the value labelled "Access Key ID" when creating an API. token from the [R2 dashboard](https://dash.cloudflare.com/?to=/:account/r2/api-tokens). Sippy will use this token when writing objects to R2, so it is best to scope this token to the bucket you're enabling Sippy for. - `provider: Optional[Provider]` - `"r2"` - `secret_access_key: Optional[str]` Value of a Cloudflare API token. This is the value labelled "Secret Access Key" when creating an API. token from the [R2 dashboard](https://dash.cloudflare.com/?to=/:account/r2/api-tokens). Sippy will use this token when writing objects to R2, so it is best to scope this token to the bucket you're enabling Sippy for. - `source: Optional[R2EnableSippyAwsSource]` AWS S3 bucket to copy objects from. - `access_key_id: Optional[str]` Access Key ID of an IAM credential (ideally scoped to a single S3 bucket). - `bucket: Optional[str]` Name of the AWS S3 bucket. - `provider: Optional[Literal["aws"]]` - `"aws"` - `region: Optional[str]` Name of the AWS availability zone. - `secret_access_key: Optional[str]` Secret Access Key of an IAM credential (ideally scoped to a single S3 bucket). - `jurisdiction: Optional[Literal["default", "eu", "fedramp"]]` Jurisdiction where objects in this bucket are guaranteed to be stored. - `"default"` - `"eu"` - `"fedramp"` ### Returns - `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]` - `"r2"` - `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"]]` - `"aws"` - `"gcs"` - `"s3"` - `region: Optional[str]` Region where the bucket resides (AWS only). ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) sippy = client.r2.buckets.sippy.update( bucket_name="example-bucket", account_id="023e105f4ecef8ad9ca31a8372d0c353", ) print(sippy.destination) ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ "string" ], "result": { "destination": { "accessKeyId": "accessKeyId", "account": "account", "bucket": "bucket", "provider": "r2" }, "enabled": true, "source": { "bucket": "bucket", "bucketUrl": "bucketUrl", "provider": "aws", "region": "region" } }, "success": true } ``` ## Disable Sippy `r2.buckets.sippy.delete(strbucket_name, SippyDeleteParams**kwargs) -> SippyDeleteResponse` **delete** `/accounts/{account_id}/r2/buckets/{bucket_name}/sippy` Disables Sippy on this bucket. ### Parameters - `account_id: str` Account ID. - `bucket_name: str` Name of the bucket. - `jurisdiction: Optional[Literal["default", "eu", "fedramp"]]` Jurisdiction where objects in this bucket are guaranteed to be stored. - `"default"` - `"eu"` - `"fedramp"` ### Returns - `class SippyDeleteResponse: …` - `enabled: Optional[Literal[false]]` - `false` ### Example ```python import os from cloudflare import Cloudflare client = Cloudflare( api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted ) sippy = client.r2.buckets.sippy.delete( bucket_name="example-bucket", account_id="023e105f4ecef8ad9ca31a8372d0c353", ) print(sippy.enabled) ``` #### Response ```json { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ "string" ], "result": { "enabled": false }, "success": true } ``` ## Domain Types ### Provider - `Literal["r2"]` - `"r2"` ### Sippy - `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]` - `"r2"` - `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"]]` - `"aws"` - `"gcs"` - `"s3"` - `region: Optional[str]` Region where the bucket resides (AWS only). ### Sippy Delete Response - `class SippyDeleteResponse: …` - `enabled: Optional[Literal[false]]` - `false`