Cloudflare/r2
Cloudflare R2 object storage — buckets, objects, multipart uploads, notifications
2026.11.05.1
Fixed: disable_catalog is a write whose success response carries no
body (HTTP 204). Earlier versions declared a disable_catalog resource with an
empty schema and wrote an empty {} to it under a constant instance name on
every call. The method now issues the API call for its side effect and returns
no data handles — it stores nothing. The empty disable_catalog resource spec
is gone.
Upgrade note: The disable_catalog resource is no longer declared. Any data
earlier versions wrote under it is stale; delete it with swamp data delete.
2026.11.03.1
Changed: Bump zod 4.6.5 → 4.6.7
2026.10.21.1
Changed: The README and the apiToken description now lead with a vault.
Store the token with swamp vault put cloudflare API_TOKEN and set apiToken
to ${{ vault.get("cloudflare", "API_TOKEN") }}. The CLOUDFLARE_API_TOKEN
environment variable still works as a fallback, but swamp does not redact it, so
it is no longer recommended. The missing-token error now says the same.
Changed: Method arguments that carry a secret are now marked sensitive, so
swamp redacts them from logs and run records. Pass them as vault.get
expressions. Affected: create_store_credentials and put_bucket_sippy_config.
The README's new "Secrets" section lists them per method.
Changed: Secrets returned by create_temp_access_credentials are now stored
in a vault, and the stored resource holds a vault.get reference instead of the
value. Because the model now declares secret output, swamp refuses to run any of
the model's methods, reads included, until a vault exists
(swamp vault create local_encryption cloudflare). The README's "Secrets"
section lists what each method stores.
Fixed: update_maintenance_config and update_table_maintenance_config
wrote to a resource the model does not declare, so they always failed. They now
write the resource the model declares.
Fixed: Create methods whose response carries no id wrote every result to
one instance named created, so each call overwrote the previous one. They now
name the instance by the response's id when present, else by the path
parameter that scopes the call, else by a hash of the request arguments (secret
arguments left out). Affected: create_store_credentials, create_bucket,
create_r2_add_custom_domain and create_temp_access_credentials.
Upgrade note: Resources stored by earlier versions of the methods in the
README's "Secrets" section may hold plaintext secrets; delete them with
swamp data delete and rotate the affected credentials. Results earlier
versions wrote to the created instance stay there; new runs write under the
new names.
Global Arguments
| Argument | Type | Description |
|---|---|---|
| apiToken? | string | Cloudflare API token. Wire it with ${{ vault.get("cloudflare", "API_TOKEN") }}; never pass the literal token. The CLOUDFLARE_API_TOKEN environment variable is read as a fallback, but it is not redacted and is not recommended. |
| accountId | string | Cloudflare account ID |
| Argument | Type | Description |
|---|---|---|
| bucket_name | string | Specifies the R2 bucket name. |
| Argument | Type | Description |
|---|---|---|
| bucket_name | string | Specifies the R2 bucket name. |
| token | string | Provides the Cloudflare API token for accessing R2. Secret: pass a vault.get expression, never a literal value. |
| Argument | Type | Description |
|---|---|---|
| bucket_name | string | Specifies the R2 bucket name to disable as catalog. |
| Argument | Type | Description |
|---|---|---|
| bucket_name | string | Specifies the R2 bucket name to enable as catalog. |
| Argument | Type | Description |
|---|---|---|
| bucket_name | string | Specifies the R2 bucket name. |
| Argument | Type | Description |
|---|---|---|
| bucket_name | string | Specifies the R2 bucket name. |
| compaction? | unknown | |
| snapshot_expiration? | unknown |
| Argument | Type | Description |
|---|---|---|
| bucket_name | string | Specifies the R2 bucket name. |
| page_token? | string | Opaque pagination token from a previous response. Use this to fetch the next page of results. |
| page_size? | number | Maximum number of namespaces to return per page. Defaults to 100, maximum 1000. |
| parent? | string | 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 | Whether to include namespace UUIDs in the response. Set to true to receive the namespace_uuids array. |
| return_details? | boolean | Whether to include additional metadata (timestamps). When true, response includes created_at and updated_at arrays. |
| Argument | Type | Description |
|---|---|---|
| bucket_name | string | Specifies the R2 bucket name. |
| namespace | string | The namespace identifier. For nested namespaces, use %1F as separator (e.g., "bronze%1Fanalytics"). |
| page_token? | string | Opaque pagination token from a previous response. Use this to fetch the next page of results. |
| page_size? | number | Maximum number of tables to return per page. Defaults to 100, maximum 1000. |
| return_uuids? | boolean | Whether to include table UUIDs in the response. Set to true to receive the table_uuids array. |
| return_details? | boolean | Whether to include additional metadata (timestamps, locations). When true, response includes created_at, updated_at, metadata_locations, and locations arrays. |
| Argument | Type | Description |
|---|---|---|
| bucket_name | string | Specifies the R2 bucket name. |
| namespace | string | The namespace identifier. For nested namespaces, use %1F as separator (e.g., "bronze%1Fanalytics"). |
| table_name | string | The table name within the given namespace. |
| Argument | Type | Description |
|---|---|---|
| bucket_name | string | Specifies the R2 bucket name. |
| namespace | string | The namespace identifier (use %1F as separator for nested namespaces). |
| table_name | string | The table name. |
| Argument | Type | Description |
|---|---|---|
| bucket_name | string | Specifies the R2 bucket name. |
| namespace | string | The namespace identifier (use %1F as separator for nested namespaces). |
| table_name | string | The table name. |
| compaction? | unknown | |
| snapshot_expiration? | unknown |
| Argument | Type | Description |
|---|---|---|
| name_contains? | string | |
| start_after? | string | |
| per_page? | number | |
| order? | enum | |
| direction? | enum | |
| cursor? | string |
| Argument | Type | Description |
|---|---|---|
| locationHint? | unknown | |
| name | unknown | |
| storageClass? | unknown |
| Argument | Type | Description |
|---|---|---|
| bucket_name | string |
| Argument | Type | Description |
|---|---|---|
| bucket_name | string |
| Argument | Type | Description |
|---|---|---|
| bucket_name | string |
| Argument | Type | Description |
|---|---|---|
| bucket_name | string |
| Argument | Type | Description |
|---|---|---|
| bucket_name | string | |
| rules? | array |
| Argument | Type | Description |
|---|---|---|
| bucket_name | string |
| Argument | Type | Description |
|---|---|---|
| bucket_name | string |
| Argument | Type | Description |
|---|---|---|
| bucket_name | string | |
| ciphers? | array | An allowlist of ciphers for TLS termination. These ciphers must be in the Bor... |
| domain | string | Name of the custom domain to be added. |
| enabled | boolean | Whether to enable public bucket access at the custom domain. If undefined, th... |
| minTLS? | enum | Minimum TLS Version the custom domain will accept for incoming connections. I... |
| zoneId | string | Zone ID of the custom domain. |
| Argument | Type | Description |
|---|---|---|
| bucket_name | string | |
| domain | string |
| Argument | Type | Description |
|---|---|---|
| bucket_name | string | |
| domain | string | |
| ciphers? | array | An allowlist of ciphers for TLS termination. These ciphers must be in the Bor... |
| enabled? | boolean | Whether to enable public bucket access at the specified custom domain. |
| minTLS? | enum | Minimum TLS Version the custom domain will accept for incoming connections. I... |
| Argument | Type | Description |
|---|---|---|
| bucket_name | string | |
| domain | string |
| Argument | Type | Description |
|---|---|---|
| bucket_name | string |
| Argument | Type | Description |
|---|---|---|
| bucket_name | string | |
| enabled | boolean | Whether to enable public bucket access at the r2.dev domain. |
| Argument | Type | Description |
|---|---|---|
| bucket_name | string |
| Argument | Type | Description |
|---|---|---|
| bucket_name | string | |
| rules? | array |
| Argument | Type | Description |
|---|---|---|
| bucket_name | string |
| Argument | Type | Description |
|---|---|---|
| bucket_name | string | |
| enabled | boolean | Whether to enable local uploads for this bucket. |
| Argument | Type | Description |
|---|---|---|
| bucket_name | string |
| Argument | Type | Description |
|---|---|---|
| bucket_name | string | |
| rules? | array |
| Argument | Type | Description |
|---|---|---|
| bucket_name | string | |
| per_page? | number | |
| prefix? | string | |
| delimiter? | string | |
| cursor? | string | |
| start_after? | string |
| Argument | Type | Description |
|---|---|---|
| bucket_name | string | |
| prefix? | string | |
| items | array |
| Argument | Type | Description |
|---|---|---|
| bucket_name | string | |
| object_key | string |
| Argument | Type | Description |
|---|---|---|
| bucket_name | string |
| Argument | Type | Description |
|---|---|---|
| bucket_name | string | |
| body | union |
| Argument | Type | Description |
|---|---|---|
| bucket_name | string |
| Argument | Type | Description |
|---|---|---|
| bucket | string | Name of the R2 bucket. |
| objects? | array | Optional object paths to scope the credentials to. |
| parentAccessKeyId | string | The parent access key id to use for signing. |
| permission | enum | Permissions allowed on the credentials. |
| prefixes? | array | Optional prefix paths to scope the credentials to. |
| ttlSeconds | number | How long the credentials will live for in seconds. |
Resources
2026.11.03.1
Changed: Bump zod 4.6.5 → 4.6.7
2026.10.21.1
Changed: The README and the apiToken description now lead with a vault.
Store the token with swamp vault put cloudflare API_TOKEN and set apiToken
to ${{ vault.get("cloudflare", "API_TOKEN") }}. The CLOUDFLARE_API_TOKEN
environment variable still works as a fallback, but swamp does not redact it, so
it is no longer recommended. The missing-token error now says the same.
Changed: Method arguments that carry a secret are now marked sensitive, so
swamp redacts them from logs and run records. Pass them as vault.get
expressions. Affected: create_store_credentials and put_bucket_sippy_config.
The README's new "Secrets" section lists them per method.
Changed: Secrets returned by create_temp_access_credentials are now stored
in a vault, and the stored resource holds a vault.get reference instead of the
value. Because the model now declares secret output, swamp refuses to run any of
the model's methods, reads included, until a vault exists
(swamp vault create local_encryption cloudflare). The README's "Secrets"
section lists what each method stores.
Fixed: update_maintenance_config and update_table_maintenance_config
wrote to a resource the model does not declare, so they always failed. They now
write the resource the model declares.
Fixed: Create methods whose response carries no id wrote every result to
one instance named created, so each call overwrote the previous one. They now
name the instance by the response's id when present, else by the path
parameter that scopes the call, else by a hash of the request arguments (secret
arguments left out). Affected: create_store_credentials, create_bucket,
create_r2_add_custom_domain and create_temp_access_credentials.
Upgrade note: Resources stored by earlier versions of the methods in the
README's "Secrets" section may hold plaintext secrets; delete them with
swamp data delete and rotate the affected credentials. Results earlier
versions wrote to the created instance stay there; new runs write under the
new names.
2026.10.21.1
Changed: The README and the apiToken description now lead with a vault.
Store the token with swamp vault put cloudflare API_TOKEN and set apiToken
to ${{ vault.get("cloudflare", "API_TOKEN") }}. The CLOUDFLARE_API_TOKEN
environment variable still works as a fallback, but swamp does not redact it, so
it is no longer recommended. The missing-token error now says the same.
Changed: Method arguments that carry a secret are now marked sensitive, so
swamp redacts them from logs and run records. Pass them as vault.get
expressions. Affected: create_store_credentials and put_bucket_sippy_config.
The README's new "Secrets" section lists them per method.
Changed: Secrets returned by create_temp_access_credentials are now stored
in a vault, and the stored resource holds a vault.get reference instead of the
value. Because the model now declares secret output, swamp refuses to run any of
the model's methods, reads included, until a vault exists
(swamp vault create local_encryption cloudflare). The README's "Secrets"
section lists what each method stores.
Fixed: update_maintenance_config and update_table_maintenance_config
wrote to a resource the model does not declare, so they always failed. They now
write the resource the model declares.
Fixed: Create methods whose response carries no id wrote every result to
one instance named created, so each call overwrote the previous one. They now
name the instance by the response's id when present, else by the path
parameter that scopes the call, else by a hash of the request arguments (secret
arguments left out). Affected: create_store_credentials, create_bucket,
create_r2_add_custom_domain and create_temp_access_credentials.
Upgrade note: Resources stored by earlier versions of the methods in the
README's "Secrets" section may hold plaintext secrets; delete them with
swamp data delete and rotate the affected credentials. Results earlier
versions wrote to the created instance stay there; new runs write under the
new names.
2026.10.14.1
Fixed: Methods that write a singleton resource failed on current swamp with
Data name 'latest' is reserved for internal use.
Changed: Singleton get and action methods now write their data under
account_level_metrics-current, disable_catalog-current,
enable_catalog-current, list_buckets-current, list_catalogs-current
instead of latest. Anything that read data.latest("<model>", "latest") or
queried name == "latest" must use the new name.
Upgrade note: Data previously stored under latest is not migrated; re-run
the method to populate the new name. No attribute schemas changed.
Added: The manifest now declares license: Apache-2.0 (SPDX). The registry quality rubric scores a declared license separately from the bundled LICENSE.md.
2026.09.18.1
Upgrade note: Normalized npm:zod dependency version to 4.6.5 across the
repo. No behavioral changes in this extension.
2026.09.17.2
Adversarial review on PR #427 found: (1) a user-supplied cursor argument was silently discarded (excluded from the params passed to cfApiPaginatedCursor, so resuming from a prior truncated result always re-fetched from page one instead); (2) cfApiPaginatedCursor claimed truncated: false when a response had no result_info at all, which could silently under-report results on endpoints that omit that field. Both are fixed: a caller-supplied cursor now flows through as the starting point, and a missing result_info now marks truncated: true instead of claiming completeness. Also fixed a trailing '?' on URLs with no query params.
2026.09.15.1
Changed: Bump zod 4.4.3 → 4.6.5
2026.08.28.2
Hardened codegen: instance names sanitized against path traversal; 429 rate-limit retry with Retry-After; string schema patterns emit regex validation; output schemas passthrough unknown fields; apiToken now optional and vault-wireable with CLOUDFLARE_API_TOKEN env fallback.
Added 1, removed 1 behaviors
2026.08.28.2
Hardened codegen: instance names sanitized against path traversal; 429 rate-limit retry with Retry-After; string schema patterns emit regex validation; output schemas passthrough unknown fields; apiToken now optional and vault-wireable with CLOUDFLARE_API_TOKEN env fallback.
2026.08.28.1
Changed: Normalized the extension license to Apache-2.0 and corrected the copyright holder to "Sean Escriva". Extensions that previously shipped an MIT LICENSE.md are now Apache-2.0, consistent with the repository root and every other extension. No code or behavioral changes.
Upgrade note: License text only. No API, schema, or runtime behavior changed.
2026.08.26.2
Fixed: Restored inline npm:zod@4.4.3 import specifiers so the registry
quality scorer can resolve dependencies and score the extension. An earlier
release used a bare "zod" import-map specifier, which published but scored as
unscored.
Changed: Retained explicit compilerOptions.strict in deno.json. No
behavioral or schema changes.
2026.08.26.2
Fixed: Restored inline npm:zod@4.4.3 import specifiers so the registry
quality scorer can resolve dependencies and score the extension. An earlier
release used a bare "zod" import-map specifier, which published but scored as
unscored.
Changed: Retained explicit compilerOptions.strict in deno.json. No
behavioral or schema changes.
2026.08.24.1
Added: Output metadata attributes for observability.
durationMs: Method execution duration in milliseconds.collectedBy: Extension name that produced the data.fetchedAt: ISO 8601 timestamp when data was fetched (added to resources that previously lacked it).
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 bareCloudflare API error: .... Network-level failures (DNS, connection reset, timeout) are now also caught and wrapped with the same operation context instead of surfacing a rawfetcherror. disable_catalog,enable_catalog,list_tables,get_table,get_table_maintenance_config, andupdate_table_maintenance_confignow reject an emptybucket_name,namespace, ortable_namebefore 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_namespacesandlist_tablesnow enforce the documentedpage_sizebounds (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.
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.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.
Modified 1 behaviors
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
parameterslist, 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 witharguments: z.object({})and an unused_argsparameter whose body still interpolatedargs.<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 withCloudflare 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.1
Added: Initial code-generated release of @webframp/cloudflare/r2 with 42 methods covering the Cloudflare r2 API surface.
- Has README or module doc2/2earned
- README has a code example1/1earned
- README is substantive1/1earned
- Most symbols documented1/1earned
- No slow types (deprecated)1/1earned
- Dependencies pass trust audit2/2earned
- Docs keep secrets in a vault1/1earned
- Has description1/1earned
- Platform support declared (or universal)2/2earned
- License2/2earned
- Verified public repository2/2earned