Cloudflare::API

Cloudflare::API is a pure Perl client for a focused subset of the
Cloudflare API. It covers mainstream compute and storage management,
including Workers, R2, KV, D1, Queues, Hyperdrive, and Secrets Store.
HTTP transport is provided by HTTP::API::Core.

The distribution requires Perl 5.10 or later, HTTP::API::Core 1.08 or
later, and HTTPS support through IO::Socket::SSL.

Example

    use Cloudflare::API;

    my $api=Cloudflare::API->new(
        token      => $ENV{'CLOUDFLARE_API_TOKEN'},
        account_id => $ENV{'CLOUDFLARE_ACCOUNT_ID'}
    );

    my $bucket=$api->r2()->create_bucket({ name => 'my-app-assets' });
    my $database=$api->d1()->create_database({ name => 'my-app-data' });
    my $namespaces=$api->kv()->list_namespaces();

List methods automatically follow Cloudflare pagination and return one
flat array reference containing every item. This is convenient but
retains the full result set in memory. For large collections, use the
corresponding _page() method and consume its HTTP::API::Core::Pagination
object incrementally:

    my $page_or=$api->kv()->list_keys_page($namespace_id, limit => 1_000);
    while (defined(my $key_hr=$page_or->next())) {
        process_key($key_hr);
    }

The corresponding _page_response() method makes one request and returns
the complete decoded Cloudflare response, including result_info when
supplied.

Authentication

Pass token and account_id to the constructor, or set
CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID. Account and zone lookups
do not require a default account ID. Other account-scoped methods do.

The cloudflare-api command can also use --auth=wrangler to obtain a
token from an existing Wrangler login. When Wrangler reports one
account, the command uses its account ID automatically. Use --account-id
or CLOUDFLARE_ACCOUNT_ID to select an account explicitly.

Non-list JSON methods return Cloudflare's decoded result by default.
Pass full_response => 1 to retain the complete decoded Cloudflare
response. request() provides access to JSON endpoints without a named
method, while response() returns the HTTP::API::Core::Response object
for non-JSON bodies or HTTP-level details.

Worker uploads

The Workers interface uploads prepared modules, versions, deployments,
secrets, routes, and static asset sets. upload_assets() can recursively
upload a directory and return the completion token needed for a Worker
version.

The module does not bundle JavaScript, resolve npm dependencies, or
build a Worker project. Continue to use Wrangler for uploads that
require bundling or a project build, and use Cloudflare::API when the
Worker modules and metadata are already prepared.

Current resource methods

  Resource        Methods
  --------------- ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
  Accounts        list, get
  Zones           list, get
  Workers         list_scripts, search_scripts, download_script, upload_script, upload_version, list_versions, get_version, upload_assets, delete_script, list_deployments, get_deployment, create_deployment, list_secrets, add_secret, delete_secret, get_subdomain, set_subdomain, list_routes, create_route, update_route, delete_route
  R2              list_buckets, get_bucket, create_bucket, update_bucket, delete_bucket
  KV              list_namespaces, get_namespace, create_namespace, rename_namespace, delete_namespace, list_keys, get_value, put_value, delete_value
  D1              list_databases, get_database, create_database, update_database, delete_database, query_database, query_sql
  Queues          list_queues, get_queue, create_queue, update_queue, delete_queue, list_consumers, create_consumer, delete_consumer
  Hyperdrive      list_configs, get_config, create_config, replace_config, update_config, delete_config
  Secrets Store   list_stores, get_store, create_store, delete_store, list_secrets, get_secret, create_secret, update_secret, delete_secret, get_quota

Every listed list... method also has ..._page and ..._page_response
variants; search_scripts has the same variants. Create and update
methods take a hash reference containing Cloudflare's request body. The
named methods intentionally cover a subset of the Cloudflare API; use
request() for other JSON endpoints.

Command-line client

The installed cloudflare-api command exposes the same resource methods
and also supports low-level requests:

    cloudflare-api --resource r2 --action list_buckets --paginate --max-pages 2
    cloudflare-api --resource kv --action create_namespace --arg-json '{"title":"my-app-cache"}'
    cloudflare-api --resource zones --action list --param status=active --output dumper
    cloudflare-api --method GET --path /accounts --full-response

Arguments and named parameters can be supplied as strings, booleans,
JSON, or JSON files. List actions support numbered and cursor-based
pagination. Output is pretty JSON by default, with Data::Dumper
available through --output dumper. Use cloudflare-api --man for the
complete option reference.

Documentation

Reference documentation is available in the doc/ directory and from the
GitHub Pages site linked from the repository. Module-specific Markdown
pages are stored alongside their modules under lib/Cloudflare.