Cloudflare/r2

@webframp/cloudflare/r2v2026.08.21.3· 1d agoMODELS

01README

Cloudflare R2 object storage — buckets, objects, multipart uploads, notifications

02Release Notes

2026.08.21.3

Changed:

Errors raised when a Cloudflare API call fails now name the HTTP method and path that was attempted (e.g. Cloudflare API GET /accounts/.../r2-catalog/xxx/namespaces/yyy/tables failed with HTTP 400 ...) instead of a bare Cloudflare API error: .... Network-level failures (DNS, connection reset, timeout) are now also caught and wrapped with the same operation context instead of surfacing a raw fetch error.
disable_catalog, enable_catalog, list_tables, get_table, get_table_maintenance_config, and update_table_maintenance_config now reject an empty bucket_name, namespace, or table_name before making a request. Previously these identifiers were validated on some R2 catalog methods but not others, so an empty value on the unvalidated ones would fail deep inside the Cloudflare API call with a less specific error.
list_namespaces and list_tables now enforce the documented page_size bounds (1 to 1000) at the schema level, instead of letting an out-of-range value fail inside the Cloudflare API call.

No breaking changes. Existing calls that already supplied non-empty identifiers and in-range page sizes are unaffected.

03Models1

cloudflare/r2.tsv2026.08.21.1

Global Arguments

Argument	Type	Required	Description
apiToken	string	yes	Cloudflare API token
accountId	string	yes	Cloudflare account ID

fn list_catalogs()

List R2 catalogs

fn get_catalog_details(bucket_name: string)

Get R2 catalog details

Argument	Type	Required	Description
bucket_name	string	yes	Specifies the R2 bucket name.

fn create_store_credentials(bucket_name: string, token: string)

Store catalog credentials

Argument	Type	Required	Description
bucket_name	string	yes	Specifies the R2 bucket name.
token	string	yes	Provides the Cloudflare API token for accessing R2.

fn disable_catalog(bucket_name: string)

Disable R2 catalog

Argument	Type	Required	Description
bucket_name	string	yes	Specifies the R2 bucket name to disable as catalog.

fn enable_catalog(bucket_name: string)

Enable R2 bucket as a catalog

Argument	Type	Required	Description
bucket_name	string	yes	Specifies the R2 bucket name to enable as catalog.

fn get_maintenance_config(bucket_name: string)

Get catalog maintenance configuration

Argument	Type	Required	Description
bucket_name	string	yes	Specifies the R2 bucket name.

fn update_maintenance_config(bucket_name: string, compaction?: unknown, snapshot_expiration?: unknown)

Update catalog maintenance configuration

Argument	Type	Required	Description
bucket_name	string	yes	Specifies the R2 bucket name.
compaction?	unknown	no
snapshot_expiration?	unknown	no

fn list_namespaces(bucket_name: string, page_token?: string, page_size?: number, parent?: string, return_uuids?: boolean, return_details?: boolean)

List namespaces in catalog

Argument	Type	Required	Description
bucket_name	string	yes	Specifies the R2 bucket name.
page_token?	string	no	Opaque pagination token from a previous response. Use this to fetch the next page of results.
page_size?	number	no	Maximum number of namespaces to return per page. Defaults to 100, maximum 1000.
parent?	string	no	Parent namespace to filter by. Only returns direct children of this namespace. For nested namespaces, use %1F as separator (e.g., "bronze%1Fanalytics"). Omit this parameter to list top-level namespaces.
return_uuids?	boolean	no	Whether to include namespace UUIDs in the response. Set to true to receive the namespace_uuids array.
return_details?	boolean	no	Whether to include additional metadata (timestamps). When true, response includes created_at and updated_at arrays.

fn list_tables(bucket_name: string, namespace: string, page_token?: string, page_size?: number, return_uuids?: boolean, return_details?: boolean)

List tables in namespace

Argument	Type	Required	Description
bucket_name	string	yes	Specifies the R2 bucket name.
namespace	string	yes	The namespace identifier. For nested namespaces, use %1F as separator (e.g., "bronze%1Fanalytics").
page_token?	string	no	Opaque pagination token from a previous response. Use this to fetch the next page of results.
page_size?	number	no	Maximum number of tables to return per page. Defaults to 100, maximum 1000.
return_uuids?	boolean	no	Whether to include table UUIDs in the response. Set to true to receive the table_uuids array.
return_details?	boolean	no	Whether to include additional metadata (timestamps, locations). When true, response includes created_at, updated_at, metadata_locations, and locations arrays.

fn get_table(bucket_name: string, namespace: string, table_name: string)

Get table details

Argument	Type	Required	Description
bucket_name	string	yes	Specifies the R2 bucket name.
namespace	string	yes	The namespace identifier. For nested namespaces, use %1F as separator (e.g., "bronze%1Fanalytics").
table_name	string	yes	The table name within the given namespace.

fn get_table_maintenance_config(bucket_name: string, namespace: string, table_name: string)

Get table maintenance configuration

Argument	Type	Required	Description
bucket_name	string	yes	Specifies the R2 bucket name.
namespace	string	yes	The namespace identifier (use %1F as separator for nested namespaces).
table_name	string	yes	The table name.

fn update_table_maintenance_config(bucket_name: string, namespace: string, table_name: string, compaction?: unknown, snapshot_expiration?: unknown)

Update table maintenance configuration

Argument	Type	Required	Description
bucket_name	string	yes	Specifies the R2 bucket name.
namespace	string	yes	The namespace identifier (use %1F as separator for nested namespaces).
table_name	string	yes	The table name.
compaction?	unknown	no
snapshot_expiration?	unknown	no

fn list_buckets(name_contains?: string, start_after?: string, per_page?: number, order?: enum, direction?: enum, cursor?: string)

List Buckets

Argument	Type	Required
name_contains?	string	no
start_after?	string	no
per_page?	number	no
order?	enum	no
direction?	enum	no
cursor?	string	no

fn create_bucket(locationHint?: unknown, name: unknown, storageClass?: unknown)

Create Bucket

Argument	Type	Required
locationHint?	unknown	no
name	unknown	yes
storageClass?	unknown	no

fn get_bucket(bucket_name: string)

Get Bucket

Argument	Type	Required	Description
bucket_name	string	yes	Specifies the R2 bucket name.

fn patch_bucket(bucket_name: string)

Patch Bucket

Argument	Type	Required	Description
bucket_name	string	yes	Specifies the R2 bucket name.

fn delete_bucket(bucket_name: string)

Delete Bucket

Argument	Type	Required	Description
bucket_name	string	yes	Specifies the R2 bucket name.

fn get_bucket_cors_policy(bucket_name: string)

Get Bucket CORS Policy

Argument	Type	Required	Description
bucket_name	string	yes	Specifies the R2 bucket name.

fn put_bucket_cors_policy(bucket_name: string, rules?: array)

Put Bucket CORS Policy

Argument	Type	Required	Description
bucket_name	string	yes	Specifies the R2 bucket name.
rules?	array	no

fn delete_bucket_cors_policy(bucket_name: string)

Delete Bucket CORS Policy

Argument	Type	Required	Description
bucket_name	string	yes	Specifies the R2 bucket name.

fn list_custom_domains(bucket_name: string)

List Custom Domains of Bucket

Argument	Type	Required	Description
bucket_name	string	yes	Specifies the R2 bucket name.

fn create_r2_add_custom_domain(bucket_name: string, ciphers?: array, domain: string, enabled: boolean, minTLS?: enum, zoneId: string)

Attach Custom Domain To Bucket

Argument	Type	Required	Description
bucket_name	string	yes	Specifies the R2 bucket name.
ciphers?	array	no	An allowlist of ciphers for TLS termination. These ciphers must be in the Bor...
domain	string	yes	Name of the custom domain to be added.
enabled	boolean	yes	Whether to enable public bucket access at the custom domain. If undefined, th...
minTLS?	enum	no	Minimum TLS Version the custom domain will accept for incoming connections. I...
zoneId	string	yes	Zone ID of the custom domain.

fn get_custom_domain_settings(bucket_name: string, domain: string)

Get Custom Domain Settings

Argument	Type	Required	Description
bucket_name	string	yes	Specifies the R2 bucket name.
domain	string	yes	Name of the custom domain.

fn update_r2_edit_custom_domain_settings(bucket_name: string, domain: string, ciphers?: array, enabled?: boolean, minTLS?: enum)

Configure Custom Domain Settings

Argument	Type	Required	Description
bucket_name	string	yes	Specifies the R2 bucket name.
domain	string	yes	Name of the custom domain.
ciphers?	array	no	An allowlist of ciphers for TLS termination. These ciphers must be in the Bor...
enabled?	boolean	no	Whether to enable public bucket access at the specified custom domain.
minTLS?	enum	no	Minimum TLS Version the custom domain will accept for incoming connections. I...

fn delete_custom_domain(bucket_name: string, domain: string)

Remove Custom Domain From Bucket

Argument	Type	Required	Description
bucket_name	string	yes	Specifies the R2 bucket name.
domain	string	yes	Name of the custom domain.

fn get_bucket_public_policy(bucket_name: string)

Get r2.dev Domain of Bucket

Argument	Type	Required	Description
bucket_name	string	yes	Specifies the R2 bucket name.

fn put_bucket_public_policy(bucket_name: string, enabled: boolean)

Update r2.dev Domain of Bucket

Argument	Type	Required	Description
bucket_name	string	yes	Specifies the R2 bucket name.
enabled	boolean	yes	Whether to enable public bucket access at the r2.dev domain.

fn get_bucket_lifecycle_configuration(bucket_name: string)

Get Object Lifecycle Rules

Argument	Type	Required	Description
bucket_name	string	yes	Specifies the R2 bucket name.

fn put_bucket_lifecycle_configuration(bucket_name: string, rules?: array)

Put Object Lifecycle Rules

Argument	Type	Required	Description
bucket_name	string	yes	Specifies the R2 bucket name.
rules?	array	no

fn get_bucket_local_uploads_configuration(bucket_name: string)

Get Local Uploads Configuration

Argument	Type	Required	Description
bucket_name	string	yes	Specifies the R2 bucket name.

fn put_bucket_local_uploads_configuration(bucket_name: string, enabled: boolean)

Put Local Uploads Configuration

Argument	Type	Required	Description
bucket_name	string	yes	Specifies the R2 bucket name.
enabled	boolean	yes	Whether to enable local uploads for this bucket.

fn get_bucket_lock_configuration(bucket_name: string)

Get Bucket Lock Rules

Argument	Type	Required	Description
bucket_name	string	yes	Specifies the R2 bucket name.

fn put_bucket_lock_configuration(bucket_name: string, rules?: array)

Put Bucket Lock Rules

Argument	Type	Required	Description
bucket_name	string	yes	Specifies the R2 bucket name.
rules?	array	no

fn list_objects(bucket_name: string, per_page?: number, prefix?: string, delimiter?: string, cursor?: string, start_after?: string)

List Objects

Argument	Type	Required	Description
bucket_name	string	yes	Specifies the R2 bucket name.
per_page?	number	no
prefix?	string	no
delimiter?	string	no
cursor?	string	no
start_after?	string	no

fn delete_objects(bucket_name: string, prefix?: string, items: array)

Delete Objects

Argument	Type	Required	Description
bucket_name	string	yes	Specifies the R2 bucket name.
prefix?	string	no
items	array	yes

fn delete_object(bucket_name: string, object_key: string)

Delete Object

Argument	Type	Required	Description
bucket_name	string	yes	Specifies the R2 bucket name.
object_key	string	yes	Key of the object in the bucket.

fn get_bucket_sippy_config(bucket_name: string)

Get Sippy Configuration

Argument	Type	Required	Description
bucket_name	string	yes	Specifies the R2 bucket name.

fn put_bucket_sippy_config(bucket_name: string, body?: union)

Enable Sippy

Argument	Type	Required	Description
bucket_name	string	yes	Specifies the R2 bucket name.
body?	union	no

fn delete_bucket_sippy_config(bucket_name: string)

Disable Sippy

Argument	Type	Required	Description
bucket_name	string	yes	Specifies the R2 bucket name.

fn get_account_level_metrics()

Get Account-Level Metrics

fn create_temp_access_credentials(bucket: string, objects?: array, parentAccessKeyId: string, permission: enum, prefixes?: array, ttlSeconds: number)

Create Temporary Access Credentials

Argument	Type	Required	Description
bucket	string	yes	Name of the R2 bucket.
objects?	array	no	Optional object paths to scope the credentials to.
parentAccessKeyId	string	yes	The parent access key id to use for signing.
permission	enum	yes	Permissions allowed on the credentials.
prefixes?	array	no	Optional prefix paths to scope the credentials to.
ttlSeconds	number	yes	How long the credentials will live for in seconds.

04Previous Versions4

2026.08.21.2Aug 21, 2026

2026.08.21.2

Changed: Added .describe() and .min(1) to previously undocumented bucket_name, domain, and object_key method arguments. No behavioral changes.

2026.08.21.1

Fixed: Regenerated with three cloudflare-codegen fixes: (1) discriminated-union request bodies with a sibling top-level discriminator property (e.g. gateway proxy_endpoints kind) now correctly build the body from the full oneOf variant instead of silently dropping it to undefined; (2) DELETE methods with a request body (e.g. r2 delete_objects bulk-delete-by-list) now send that body instead of ignoring it; (3) oneOf/anyOf request body variants that are $ref (e.g. r2 sippy config) are now resolved to their real schema instead of collapsing to z.unknown(). Same generator fix as workers-scripts in #352, now caught up for these 7 services.

Changed: put_object was removed — it is no longer present in the upstream Cloudflare API spec this extension is generated from.

2026.08.21.1Aug 21, 2026

2026.08.21.1

Changed: put_object was removed — it is no longer present in the upstream Cloudflare API spec this extension is generated from.

Modified 1 models

2026.07.27.1Jul 27, 2026

2026.07.27.1

Fixed: Regenerated from scripts/cloudflare-codegen after two generator bugs were repaired (webframp/swamp-extensions#284).

Methods referencing an undeclared path parameter did not compile. The generator derived a method's arguments schema and execute signature from the OpenAPI parameters list, but built the request URL from the path template. Where the Cloudflare spec omits a declaration for a {placeholder} — which it does in several places — the result was a method with arguments: z.object({}) and an unused _args parameter whose body still interpolated args.<name>. Those methods failed type checking and were uncallable even if they had compiled, because the argument was never declared. Path-template placeholders are now unioned into the declared parameters, so the schema, the signature, and the body agree.
Generated tests could request a URL the mock server did not serve. Test arguments merged the request-body fixture over the path-parameter values, so a body property sharing a name with a path parameter (commonly id) substituted its own example value into the URL. The request then missed the mock and failed with Cloudflare API error: Not found. Path parameters now take precedence, matching what the generated model already does by excluding path-parameter names from the request body.

Upgrade note: No API surface change and no method was added or removed. If this extension type-checked and tested cleanly before, its behavior is unchanged and only the version moved. Extensions that previously failed deno check or deno task test now pass.

2026.07.19.1Jul 19, 2026