Table of Contents

Class R2BucketsApi

Namespace
Cloudflare.NET.Accounts.Buckets
Assembly
Cloudflare.NET.dll

Implements the API for managing Cloudflare R2 bucket resources.

public class R2BucketsApi : ApiResource, IR2BucketsApi
Inheritance
R2BucketsApi
Implements
Inherited Members

Constructors

R2BucketsApi(HttpClient, IOptions<CloudflareApiOptions>, ILoggerFactory)

Initializes a new instance of the R2BucketsApi class.

public R2BucketsApi(HttpClient httpClient, IOptions<CloudflareApiOptions> options, ILoggerFactory loggerFactory)

Parameters

httpClient HttpClient

The HttpClient for making requests.

options IOptions<CloudflareApiOptions>

The Cloudflare API options containing the account ID.

loggerFactory ILoggerFactory

The factory to create loggers.

Methods

AttachCustomDomainAsync(string, string, string, R2Jurisdiction?, string?, CancellationToken)

Attaches a custom domain to an R2 bucket, allowing it to be served from a custom hostname.

public Task<CustomDomainResponse> AttachCustomDomainAsync(string bucketName, string hostname, string zoneId, R2Jurisdiction? jurisdiction = null, string? minTls = null, CancellationToken cancellationToken = default)

Parameters

bucketName string

The name of the R2 bucket.

hostname string

The custom hostname to attach (e.g., "files.example.com").

zoneId string

The ID of the zone the hostname belongs to.

jurisdiction R2Jurisdiction?

Required for jurisdictional buckets created with a jurisdiction (e.g., EuropeanUnion).

minTls string

Optional minimum TLS version for the attached domain (e.g., "1.2", "1.3"). When omitted, the Cloudflare API defaults the domain to TLS 1.0.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<CustomDomainResponse>

A task that represents the asynchronous operation. The task result contains the CustomDomainResponse from the API.

See Also

CreateAsync(string, R2LocationHint?, R2Jurisdiction?, R2StorageClass?, CancellationToken)

Creates a new R2 bucket within the configured account with optional location and storage settings.

public Task<R2Bucket> CreateAsync(string bucketName, R2LocationHint? locationHint = null, R2Jurisdiction? jurisdiction = null, R2StorageClass? storageClass = null, CancellationToken cancellationToken = default)

Parameters

bucketName string

The desired name for the new bucket. Must be 3-64 characters and unique.

locationHint R2LocationHint?

Optional location hint suggesting where the bucket's data should be stored. Use R2LocationHint constants (e.g., EastNorthAmerica).

jurisdiction R2Jurisdiction?

Optional jurisdictional restriction guaranteeing data residency. Use R2Jurisdiction constants (e.g., EuropeanUnion).

storageClass R2StorageClass?

Optional default storage class for new objects. Use R2StorageClass constants (e.g., InfrequentAccess).

cancellationToken CancellationToken

A cancellation token.

Returns

Task<R2Bucket>

A task that represents the asynchronous operation. The task result contains the R2Bucket from the Cloudflare API, detailing the created bucket.

Remarks

Important: If you create a bucket with a jurisdiction (e.g., EuropeanUnion), you must pass the same jurisdiction value to all subsequent API operations on this bucket. Store the jurisdiction value and reuse it.

Once created, a bucket's jurisdiction cannot be changed.

See Also

CreateTempCredentialsAsync(CreateTempCredentialsRequest, CancellationToken)

Creates temporary access credentials for R2 that can be optionally scoped to specific buckets or prefixes.

public Task<TempCredentials> CreateTempCredentialsAsync(CreateTempCredentialsRequest request, CancellationToken cancellationToken = default)

Parameters

request CreateTempCredentialsRequest

The request specifying the credentials to create.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<TempCredentials>

A task that represents the asynchronous operation. The task result contains the TempCredentials with the temporary access credentials.

Remarks

Temporary credentials are useful for granting limited, time-bound access to R2 resources without exposing your main API credentials. The credentials include an access key ID, secret access key, and session token.

See Also

DeleteAsync(string, R2Jurisdiction?, CancellationToken)

Deletes an R2 bucket. The bucket must be empty before it can be deleted.

public Task DeleteAsync(string bucketName, R2Jurisdiction? jurisdiction = null, CancellationToken cancellationToken = default)

Parameters

bucketName string

The name of the bucket to delete.

jurisdiction R2Jurisdiction?

Required for jurisdictional buckets created with a jurisdiction (e.g., EuropeanUnion).

cancellationToken CancellationToken

A cancellation token.

Returns

Task

A task that represents the asynchronous operation.

See Also

DeleteCorsAsync(string, R2Jurisdiction?, CancellationToken)

Deletes the CORS policy for an R2 bucket, removing all CORS rules.

public Task DeleteCorsAsync(string bucketName, R2Jurisdiction? jurisdiction = null, CancellationToken cancellationToken = default)

Parameters

bucketName string

The name of the bucket.

jurisdiction R2Jurisdiction?

Required for jurisdictional buckets created with a jurisdiction (e.g., EuropeanUnion).

cancellationToken CancellationToken

A cancellation token.

Returns

Task

A task that represents the asynchronous operation.

See Also

DeleteLifecycleAsync(string, R2Jurisdiction?, CancellationToken)

Deletes the lifecycle policy for an R2 bucket, removing all lifecycle rules.

public Task DeleteLifecycleAsync(string bucketName, R2Jurisdiction? jurisdiction = null, CancellationToken cancellationToken = default)

Parameters

bucketName string

The name of the bucket.

jurisdiction R2Jurisdiction?

Required for jurisdictional buckets created with a jurisdiction (e.g., EuropeanUnion).

cancellationToken CancellationToken

A cancellation token.

Returns

Task

A task that represents the asynchronous operation.

Remarks

Cloudflare R2 does not have a dedicated DELETE endpoint for lifecycle policies. This method removes the policy by setting an empty rules array.

See Also

DeleteLockAsync(string, R2Jurisdiction?, CancellationToken)

Deletes all lock rules for an R2 bucket.

public Task DeleteLockAsync(string bucketName, R2Jurisdiction? jurisdiction = null, CancellationToken cancellationToken = default)

Parameters

bucketName string

The name of the bucket.

jurisdiction R2Jurisdiction?

Required for jurisdictional buckets created with a jurisdiction (e.g., EuropeanUnion).

cancellationToken CancellationToken

A cancellation token.

Returns

Task

A task that represents the asynchronous operation.

Remarks

This method removes the lock policy by setting an empty rules array, similar to lifecycle policy deletion.

DetachCustomDomainAsync(string, string, R2Jurisdiction?, CancellationToken)

Detaches a custom domain from an R2 bucket.

public Task DetachCustomDomainAsync(string bucketName, string hostname, R2Jurisdiction? jurisdiction = null, CancellationToken cancellationToken = default)

Parameters

bucketName string

The name of the bucket.

hostname string

The custom hostname to detach.

jurisdiction R2Jurisdiction?

Required for jurisdictional buckets created with a jurisdiction (e.g., EuropeanUnion).

cancellationToken CancellationToken

A cancellation token.

Returns

Task

A task that represents the asynchronous operation.

DisableManagedDomainAsync(string, R2Jurisdiction?, CancellationToken)

Disables the public r2.dev URL for a given bucket.

public Task DisableManagedDomainAsync(string bucketName, R2Jurisdiction? jurisdiction = null, CancellationToken cancellationToken = default)

Parameters

bucketName string

The name of the bucket to modify.

jurisdiction R2Jurisdiction?

Required for jurisdictional buckets created with a jurisdiction (e.g., EuropeanUnion).

cancellationToken CancellationToken

A cancellation token.

Returns

Task

A task that represents the asynchronous operation.

DisableSippyAsync(string, R2Jurisdiction?, CancellationToken)

Disables Sippy (incremental migration) for an R2 bucket.

public Task DisableSippyAsync(string bucketName, R2Jurisdiction? jurisdiction = null, CancellationToken cancellationToken = default)

Parameters

bucketName string

The name of the bucket.

jurisdiction R2Jurisdiction?

Required for jurisdictional buckets created with a jurisdiction (e.g., EuropeanUnion).

cancellationToken CancellationToken

A cancellation token.

Returns

Task

A task that represents the asynchronous operation.

See Also

EnableManagedDomainAsync(string, R2Jurisdiction?, CancellationToken)

Enables the public r2.dev URL for a given bucket.

public Task<ManagedDomainResponse> EnableManagedDomainAsync(string bucketName, R2Jurisdiction? jurisdiction = null, CancellationToken cancellationToken = default)

Parameters

bucketName string

The name of the bucket to modify.

jurisdiction R2Jurisdiction?

Required for jurisdictional buckets created with a jurisdiction (e.g., EuropeanUnion).

cancellationToken CancellationToken

A cancellation token.

Returns

Task<ManagedDomainResponse>

A task that represents the asynchronous operation. The task result contains the ManagedDomainResponse with the updated status.

EnableSippyAsync(string, EnableSippyRequest, R2Jurisdiction?, CancellationToken)

Enables or updates Sippy (incremental migration) for an R2 bucket.

public Task<SippyConfig> EnableSippyAsync(string bucketName, EnableSippyRequest request, R2Jurisdiction? jurisdiction = null, CancellationToken cancellationToken = default)

Parameters

bucketName string

The name of the bucket.

request EnableSippyRequest

The Sippy configuration to apply.

jurisdiction R2Jurisdiction?

Required for jurisdictional buckets created with a jurisdiction (e.g., EuropeanUnion).

cancellationToken CancellationToken

A cancellation token.

Returns

Task<SippyConfig>

A task that represents the asynchronous operation. The task result contains the SippyConfig with the applied configuration.

Remarks

Sippy supports migration from:

  • Amazon S3
  • Google Cloud Storage (GCS)

When enabled, objects not found in R2 are simultaneously returned from the source bucket and copied to R2 for future requests.

See Also

GetAsync(string, R2Jurisdiction?, CancellationToken)

Gets the properties of an existing R2 bucket.

public Task<R2Bucket> GetAsync(string bucketName, R2Jurisdiction? jurisdiction = null, CancellationToken cancellationToken = default)

Parameters

bucketName string

The name of the bucket to retrieve (3-64 characters).

jurisdiction R2Jurisdiction?

Required for jurisdictional buckets created with a jurisdiction (e.g., EuropeanUnion).

cancellationToken CancellationToken

A cancellation token.

Returns

Task<R2Bucket>

A task that represents the asynchronous operation. The task result contains the R2Bucket with the bucket's properties, including its Jurisdiction.

See Also

GetCorsAsync(string, R2Jurisdiction?, CancellationToken)

Gets the CORS policy for an R2 bucket.

public Task<BucketCorsPolicy> GetCorsAsync(string bucketName, R2Jurisdiction? jurisdiction = null, CancellationToken cancellationToken = default)

Parameters

bucketName string

The name of the bucket.

jurisdiction R2Jurisdiction?

Required for jurisdictional buckets created with a jurisdiction (e.g., EuropeanUnion).

cancellationToken CancellationToken

A cancellation token.

Returns

Task<BucketCorsPolicy>

A task that represents the asynchronous operation. The task result contains the BucketCorsPolicy with the current CORS rules.

See Also

GetCustomDomainStatusAsync(string, string, R2Jurisdiction?, CancellationToken)

Gets the current status of a custom domain attached to a bucket, including ownership and SSL status.

public Task<CustomDomainResponse> GetCustomDomainStatusAsync(string bucketName, string hostname, R2Jurisdiction? jurisdiction = null, CancellationToken cancellationToken = default)

Parameters

bucketName string

The name of the R2 bucket.

hostname string

The custom hostname to check.

jurisdiction R2Jurisdiction?

Required for jurisdictional buckets created with a jurisdiction (e.g., EuropeanUnion).

cancellationToken CancellationToken

A cancellation token.

Returns

Task<CustomDomainResponse>

A task that represents the asynchronous operation. The task result contains the CustomDomainResponse with the latest status.

GetLifecycleAsync(string, R2Jurisdiction?, CancellationToken)

Gets the lifecycle policy for an R2 bucket.

public Task<BucketLifecyclePolicy> GetLifecycleAsync(string bucketName, R2Jurisdiction? jurisdiction = null, CancellationToken cancellationToken = default)

Parameters

bucketName string

The name of the bucket.

jurisdiction R2Jurisdiction?

Required for jurisdictional buckets created with a jurisdiction (e.g., EuropeanUnion).

cancellationToken CancellationToken

A cancellation token.

Returns

Task<BucketLifecyclePolicy>

A task that represents the asynchronous operation. The task result contains the BucketLifecyclePolicy with the current lifecycle rules.

Remarks

Lifecycle rules determine object retention, automatic deletion, storage class transitions, and cleanup of incomplete multipart uploads. A bucket can have up to 1000 lifecycle rules.

See Also

GetLockAsync(string, R2Jurisdiction?, CancellationToken)

Gets the lock rules for an R2 bucket.

public Task<BucketLockPolicy> GetLockAsync(string bucketName, R2Jurisdiction? jurisdiction = null, CancellationToken cancellationToken = default)

Parameters

bucketName string

The name of the bucket.

jurisdiction R2Jurisdiction?

Required for jurisdictional buckets created with a jurisdiction (e.g., EuropeanUnion).

cancellationToken CancellationToken

A cancellation token.

Returns

Task<BucketLockPolicy>

A task that represents the asynchronous operation. The task result contains the BucketLockPolicy with the current lock rules.

Remarks

Bucket locks prevent the deletion and overwriting of objects for a specified period or indefinitely. If multiple rules apply to the same prefix or object key, the strictest retention requirement takes precedence.

See Also

GetManagedDomainAsync(string, R2Jurisdiction?, CancellationToken)

Gets the current state of public access over the bucket's R2-managed (r2.dev) domain.

public Task<ManagedDomainResponse> GetManagedDomainAsync(string bucketName, R2Jurisdiction? jurisdiction = null, CancellationToken cancellationToken = default)

Parameters

bucketName string

The name of the R2 bucket.

jurisdiction R2Jurisdiction?

Required for jurisdictional buckets created with a jurisdiction (e.g., EuropeanUnion).

cancellationToken CancellationToken

A cancellation token.

Returns

Task<ManagedDomainResponse>

A task that represents the asynchronous operation. The task result contains the ManagedDomainResponse with the r2.dev domain status.

See Also

GetSippyAsync(string, R2Jurisdiction?, CancellationToken)

Gets the Sippy (incremental migration) configuration for an R2 bucket.

public Task<SippyConfig> GetSippyAsync(string bucketName, R2Jurisdiction? jurisdiction = null, CancellationToken cancellationToken = default)

Parameters

bucketName string

The name of the bucket.

jurisdiction R2Jurisdiction?

Required for jurisdictional buckets created with a jurisdiction (e.g., EuropeanUnion).

cancellationToken CancellationToken

A cancellation token.

Returns

Task<SippyConfig>

A task that represents the asynchronous operation. The task result contains the SippyConfig with the current Sippy configuration.

Remarks

Sippy is an incremental migration service that copies data from cloud storage providers (AWS S3, GCS) to R2 as it's requested, helping avoid upfront egress fees during migration.

See Also

ListAllAsync(ListR2BucketsFilters?, R2Jurisdiction?, CancellationToken)

Lists all R2 buckets in the account, automatically handling cursor-based pagination.

public IAsyncEnumerable<R2Bucket> ListAllAsync(ListR2BucketsFilters? filters = null, R2Jurisdiction? jurisdiction = null, CancellationToken cancellationToken = default)

Parameters

filters ListR2BucketsFilters

Optional filters for pagination. The cursor will be ignored.

jurisdiction R2Jurisdiction?

Optional filter to return only buckets in this jurisdiction. When null, returns all buckets regardless of jurisdiction.

cancellationToken CancellationToken

A cancellation token.

Returns

IAsyncEnumerable<R2Bucket>

An asynchronous stream of all R2 buckets in the account.

ListAsync(ListR2BucketsFilters?, R2Jurisdiction?, CancellationToken)

Lists R2 buckets in the account, allowing for manual pagination control.

public Task<CursorPaginatedResult<R2Bucket>> ListAsync(ListR2BucketsFilters? filters = null, R2Jurisdiction? jurisdiction = null, CancellationToken cancellationToken = default)

Parameters

filters ListR2BucketsFilters

Optional filters for pagination.

jurisdiction R2Jurisdiction?

Optional filter to return only buckets in this jurisdiction. When null, returns all buckets regardless of jurisdiction.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<CursorPaginatedResult<R2Bucket>>

A single page of R2 buckets along with pagination information.

See Also

ListCustomDomainsAsync(string, R2Jurisdiction?, CancellationToken)

Lists all custom domains attached to an R2 bucket.

public Task<IReadOnlyList<CustomDomain>> ListCustomDomainsAsync(string bucketName, R2Jurisdiction? jurisdiction = null, CancellationToken cancellationToken = default)

Parameters

bucketName string

The name of the R2 bucket.

jurisdiction R2Jurisdiction?

Required for jurisdictional buckets created with a jurisdiction (e.g., EuropeanUnion).

cancellationToken CancellationToken

A cancellation token.

Returns

Task<IReadOnlyList<CustomDomain>>

A task that represents the asynchronous operation. The task result contains a list of CustomDomain objects representing all custom domains for the bucket.

See Also

SetCorsAsync(string, BucketCorsPolicy, R2Jurisdiction?, CancellationToken)

Sets or updates the CORS policy for an R2 bucket.

public Task SetCorsAsync(string bucketName, BucketCorsPolicy corsPolicy, R2Jurisdiction? jurisdiction = null, CancellationToken cancellationToken = default)

Parameters

bucketName string

The name of the bucket.

corsPolicy BucketCorsPolicy

The CORS policy to apply to the bucket.

jurisdiction R2Jurisdiction?

Required for jurisdictional buckets created with a jurisdiction (e.g., EuropeanUnion).

cancellationToken CancellationToken

A cancellation token.

Returns

Task

A task that represents the asynchronous operation.

See Also

SetLifecycleAsync(string, BucketLifecyclePolicy, R2Jurisdiction?, CancellationToken)

Sets or updates the lifecycle policy for an R2 bucket.

public Task SetLifecycleAsync(string bucketName, BucketLifecyclePolicy lifecyclePolicy, R2Jurisdiction? jurisdiction = null, CancellationToken cancellationToken = default)

Parameters

bucketName string

The name of the bucket.

lifecyclePolicy BucketLifecyclePolicy

The lifecycle policy to apply to the bucket.

jurisdiction R2Jurisdiction?

Required for jurisdictional buckets created with a jurisdiction (e.g., EuropeanUnion).

cancellationToken CancellationToken

A cancellation token.

Returns

Task

A task that represents the asynchronous operation.

Remarks

Lifecycle rules can perform the following actions:

  • Delete objects after a specified age or on a specific date
  • Abort incomplete multipart uploads after a specified age
  • Transition objects to Infrequent Access storage class

Rules are processed within 24 hours of being set. Maximum of 1000 rules per bucket.

See Also

SetLockAsync(string, BucketLockPolicy, R2Jurisdiction?, CancellationToken)

Sets or updates the lock rules for an R2 bucket.

public Task<BucketLockPolicy> SetLockAsync(string bucketName, BucketLockPolicy lockPolicy, R2Jurisdiction? jurisdiction = null, CancellationToken cancellationToken = default)

Parameters

bucketName string

The name of the bucket.

lockPolicy BucketLockPolicy

The lock policy to apply to the bucket.

jurisdiction R2Jurisdiction?

Required for jurisdictional buckets created with a jurisdiction (e.g., EuropeanUnion).

cancellationToken CancellationToken

A cancellation token.

Returns

Task<BucketLockPolicy>

A task that represents the asynchronous operation. The task result contains the BucketLockPolicy with the applied lock rules.

Remarks

Lock rules can have the following condition types:

  • Age-based: Retention for a specific duration in seconds
  • Date-based: Retention until a specific date
  • Indefinite: Permanent locking without expiration

Maximum of 1000 lock rules per bucket configuration.

See Also

UpdateAsync(string, R2StorageClass, R2Jurisdiction?, CancellationToken)

Updates properties of an existing R2 bucket.

public Task<R2Bucket> UpdateAsync(string bucketName, R2StorageClass storageClass, R2Jurisdiction? jurisdiction = null, CancellationToken cancellationToken = default)

Parameters

bucketName string

The name of the bucket to update (3-64 characters).

storageClass R2StorageClass

The new default storage class for newly uploaded objects. This does not change the storage class of existing objects. Use R2StorageClass constants (e.g., InfrequentAccess).

jurisdiction R2Jurisdiction?

Required for jurisdictional buckets created with a jurisdiction (e.g., EuropeanUnion).

cancellationToken CancellationToken

A cancellation token.

Returns

Task<R2Bucket>

A task that represents the asynchronous operation. The task result contains the updated R2Bucket with the bucket's properties, including the new StorageClass.

Remarks

Currently, the only property that can be updated is the default storage class for new objects. Existing objects in the bucket retain their original storage class; use lifecycle rules to transition them if needed.

The bucket's location hint and jurisdiction cannot be changed after creation.

See Also

UpdateCustomDomainAsync(string, string, UpdateCustomDomainRequest, R2Jurisdiction?, CancellationToken)

Updates the configuration of a custom domain attached to a bucket.

public Task<CustomDomainResponse> UpdateCustomDomainAsync(string bucketName, string hostname, UpdateCustomDomainRequest request, R2Jurisdiction? jurisdiction = null, CancellationToken cancellationToken = default)

Parameters

bucketName string

The name of the R2 bucket.

hostname string

The custom hostname to update.

request UpdateCustomDomainRequest

The update request with new domain settings.

jurisdiction R2Jurisdiction?

Required for jurisdictional buckets created with a jurisdiction (e.g., EuropeanUnion).

cancellationToken CancellationToken

A cancellation token.

Returns

Task<CustomDomainResponse>

A task that represents the asynchronous operation. The task result contains the CustomDomainResponse with the updated configuration.

Edit this page