# Cloudflare::API::R2 #

# NAME #

Cloudflare::API::R2 - manage R2 buckets through Cloudflare's REST API

# SYNOPSIS #

```perl
my $r2=$api->r2();
my $bucket=$r2->create_bucket({ name => 'my-app-assets' });
my $buckets=$r2->list_buckets();
my $page_or=$r2->list_buckets_page(per_page => 100);
```

# DESCRIPTION #

Bucket management uses the account ID on `Cloudflare::API`. This module does not transfer bucket objects; use R2's S3-compatible API for object operations.

# METHODS #

* **list_buckets(%query)** — List every bucket. Named arguments become Cloudflare query parameters. The method follows cursor pages and returns one flat array reference; a large bucket set can require many requests and substantial memory.
* **list_buckets_page(%query)** — Return a lazy `HTTP::API::Core::Pagination` object. Use `next()` to consume one bucket at a time. A supplied `cursor` selects the starting page.
* **list_buckets_page_response(%query)** — Make one list request and return the complete decoded Cloudflare response hash, including the bucket array and any cursor in `result_info`.
* **get_bucket($name, %options)** — Retrieve a bucket by name and return its `result`.
* **create_bucket(\%body, %options)** — POST a bucket definition, normally including `name`, and return its `result`. Other fields pass through to Cloudflare.
* **update_bucket($name, \%body, %options)** — PATCH a bucket and return its `result`.
* **delete_bucket($name, %options)** — DELETE a bucket and return the endpoint's `result`, possibly `undef` for an empty body.

Non-list JSON methods accept `full_response => 1`. Bucket names are percent-encoded as path components. Create and update bodies must be hash references.

# ERRORS #

Missing account context, invalid names or bodies, HTTP and transport failures, and Cloudflare response failures cause exceptions as described in `Cloudflare::API`.

# SEE ALSO #

[Cloudflare::API](../API.pm.md)

# AUTHOR #

Andrew Speer <andrew.speer@isolutions.com.au>

# LICENSE and COPYRIGHT #

Copyright (c) 2026 Andrew Speer. This software is free software under the same terms as Perl 5.