A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Cloudflare API is how an app or AI agent works with a Cloudflare account: editing DNS records, purging cached content, deploying Workers scripts, and tuning firewall and WAF rules. Access is granted through an API token that carries named permission groups, each set to read or edit and scoped to chosen accounts or zones, so a token reaches only what it was given. There is a single continuously updated API, and Cloudflare signals retired methods through a dated deprecations list rather than new version numbers.
How an app or AI agent connects to Cloudflare determines what it can reach. There is a route for making calls, a route for receiving notifications, and a hosted server that exposes Cloudflare to agents, and each is governed by the token behind it and the permissions that token carries.
The REST API answers at https://api.cloudflare.com/client/v4. Calls authenticate with an API token sent as a Bearer token, return a JSON envelope with a success boolean and errors and messages arrays, and the data in a result field. Account-scoped resources sit under /accounts/{account_id} and zone-scoped resources under /zones/{zone_id}.
Cloudflare runs a hosted Model Context Protocol server at https://mcp.cloudflare.com/mcp that exposes the whole API, over 2,500 endpoints, through a search and an execute tool. It authenticates with OAuth, with API tokens as a fallback for automation. Cloudflare also runs product-specific servers, like documentation at https://docs.mcp.cloudflare.com/mcp, Workers bindings at https://bindings.mcp.cloudflare.com/mcp, observability at https://observability.mcp.cloudflare.com/mcp, and analytics over GraphQL at https://graphql.mcp.cloudflare.com/mcp.
A separate GraphQL endpoint at https://api.cloudflare.com/client/v4/graphql serves analytics and metrics with a typed schema. It carries its own quota, capped at 320 queries per five minutes, with cost varying by query.
Cloudflare delivers alerts, like security events or certificate expiry, to configured destinations such as a webhook or email. The destination is set up per account, and Cloudflare sends the alert when the chosen condition fires.
An API token carries a chosen set of permission groups, each set to read or edit, scoped to specific accounts or zones. It is the recommended way to connect, because a token grants only what it was given and can be rolled or revoked on its own. The token is sent as a Bearer token in the Authorization header.
A Global API Key authenticates with the account email and a single key that carries the full access of the user, across every account and zone they can reach. Cloudflare recommends API tokens instead, because a key cannot be scoped down. It is sent through the X-Auth-Email and X-Auth-Key headers.
The Cloudflare API is split into areas an agent can act on, like zones, DNS records, firewall rules, Workers, and R2 storage. Each area has its own methods and its own permission group, and some reach far more than others.
List, read, create, and delete the zones (domains) on an account.
List, read, create, overwrite, patch, and delete the DNS records in a zone.
List and read the rulesets that hold WAF and custom firewall rules, and update a ruleset's rules.
List, read, create, and delete the URL-pattern Page Rules in a zone.
Purge cached content from Cloudflare's edge for a zone.
List Workers scripts, read a script, upload or update a script, and delete one.
List the R2 object-storage buckets on an account, read one, and create a bucket.
List custom SSL certificates in a zone and read or change Universal SSL settings.
List the load balancers in a zone and create a new one.
List the accounts a token can reach and read a single account's details.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
ZonesList, read, create, and delete the zones (domains) on an account.4 | ||||||
| GET | /zones | List, search, sort, and filter the zones on an account. | read | Zone Read | Current | |
Read-only. Zone scope. Results are filtered to the zones the token can reach. Acts onzone Permission (capability) Zone ReadVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /zones/{zone_id} | Get the details of a single zone. | read | Zone Read | Current | |
Read-only. Zone scope. Acts onzone Permission (capability) Zone ReadVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /zones | Create a zone by adding a domain to an account. | write | Zone Write | Current | |
Needs the account to be named in the request body. Zone scope. Acts onzone Permission (capability) Zone WriteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /zones/{zone_id} | Delete a zone, removing the domain from Cloudflare. | write | Zone Write | Current | |
Irreversible; the domain stops being proxied by Cloudflare. Zone scope. Acts onzone Permission (capability) Zone WriteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
DNS recordsList, read, create, overwrite, patch, and delete the DNS records in a zone.6 | ||||||
| GET | /zones/{zone_id}/dns_records | List, search, sort, and filter the DNS records in a zone. | read | DNS Read | Current | |
Read-only. Zone scope. Acts ondns_record Permission (capability) DNS ReadVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /zones/{zone_id}/dns_records/{dns_record_id} | Get the details of a single DNS record. | read | DNS Read | Current | |
Read-only. Zone scope. Acts ondns_record Permission (capability) DNS ReadVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /zones/{zone_id}/dns_records | Create a DNS record in a zone. | write | DNS Write | Current | |
Zone scope. Edits live DNS, which resolves publicly within seconds. Acts ondns_record Permission (capability) DNS WriteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /zones/{zone_id}/dns_records/{dns_record_id} | Overwrite an existing DNS record with a full new definition. | write | DNS Write | Current | |
Replaces the whole record. Changing the type of an existing record via the API is deprecated since 23 January 2026 and ends on 30 June 2026. Zone scope. Acts ondns_record Permission (capability) DNS WriteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /zones/{zone_id}/dns_records/{dns_record_id} | Update selected fields of an existing DNS record. | write | DNS Write | Current | |
Patches only the fields sent, leaving the rest intact. Zone scope. Acts ondns_record Permission (capability) DNS WriteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /zones/{zone_id}/dns_records/{dns_record_id} | Delete a DNS record from a zone. | write | DNS Write | Current | |
Removes the record from live DNS. Zone scope. Acts ondns_record Permission (capability) DNS WriteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Firewall & WAFList and read the rulesets that hold WAF and custom firewall rules, and update a ruleset's rules.3 | ||||||
| GET | /zones/{zone_id}/rulesets | List the rulesets in a zone, which hold WAF and custom firewall rules. | read | Zone WAF Read | Current | |
Read-only; the list omits each ruleset's rules. The standalone Firewall Rules and Filters APIs are deprecated since 15 June 2025 in favor of these rulesets. Zone scope. Acts onruleset Permission (capability) Zone WAF ReadVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /zones/{zone_id}/rulesets/{ruleset_id} | Get a ruleset, including the firewall and WAF rules it contains. | read | Zone WAF Read | Current | |
Read-only. Zone scope. Acts onruleset Permission (capability) Zone WAF ReadVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /zones/{zone_id}/rulesets/{ruleset_id} | Update a ruleset, replacing the firewall and WAF rules it contains. | write | Zone WAF Write | Current | |
Replaces the ruleset's full set of rules, changing what traffic is blocked or allowed. Zone scope. Acts onruleset Permission (capability) Zone WAF WriteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Page RulesList, read, create, and delete the URL-pattern Page Rules in a zone.3 | ||||||
| GET | /zones/{zone_id}/pagerules | List the Page Rules in a zone. | read | Page Rules Read | Current | |
Read-only. Zone scope. Acts onpagerule Permission (capability) Page Rules ReadVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /zones/{zone_id}/pagerules | Create a Page Rule that changes how requests matching a URL pattern are handled. | write | Page Rules Write | Current | |
Zone scope. A zone has a fixed quota of active Page Rules by plan. Acts onpagerule Permission (capability) Page Rules WriteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /zones/{zone_id}/pagerules/{pagerule_id} | Delete a Page Rule from a zone. | write | Page Rules Write | Current | |
Zone scope. Acts onpagerule Permission (capability) Page Rules WriteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
CachePurge cached content from Cloudflare's edge for a zone.1 | ||||||
| POST | /zones/{zone_id}/purge_cache | Purge cached content for a zone, by everything, URL, prefix, host, or cache tag. | write | Cache Purge | Current | |
Zone scope. A purge-everything is limited to roughly one request every few seconds per zone. Acts oncache Permission (capability) Cache PurgeVersionAvailable since the API’s base version Webhook eventNone Rate limit~5 purge-everything calls per second per zone SourceOfficial documentation ↗ | ||||||
WorkersList Workers scripts, read a script, upload or update a script, and delete one.4 | ||||||
| GET | /accounts/{account_id}/workers/scripts | List the Workers scripts uploaded to an account. | read | Workers Scripts Read | Current | |
Read-only. Account scope. Acts onworker_script Permission (capability) Workers Scripts ReadVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /accounts/{account_id}/workers/scripts/{script_name} | Download a Worker script's content. | read | Workers Scripts Read | Current | |
Read-only. Account scope. Acts onworker_script Permission (capability) Workers Scripts ReadVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /accounts/{account_id}/workers/scripts/{script_name}/content | Upload or replace a Worker script's content, deploying the code. | write | Workers Scripts Write | Current | |
Sends the script as multipart form data and puts the code live without touching its config or metadata. Account scope. Acts onworker_script Permission (capability) Workers Scripts WriteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /accounts/{account_id}/workers/scripts/{script_name} | Delete a Worker script from an account. | write | Workers Scripts Write | Current | |
Removes the deployed code. Account scope. Acts onworker_script Permission (capability) Workers Scripts WriteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
R2 storageList the R2 object-storage buckets on an account, read one, and create a bucket.3 | ||||||
| GET | /accounts/{account_id}/r2/buckets | List the R2 object-storage buckets on an account. | read | Workers R2 Storage Read | Current | |
Read-only. Account scope. Acts onr2_bucket Permission (capability) Workers R2 Storage ReadVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /accounts/{account_id}/r2/buckets/{bucket_name} | Get the details of a single R2 bucket. | read | Workers R2 Storage Read | Current | |
Read-only. Account scope. Acts onr2_bucket Permission (capability) Workers R2 Storage ReadVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /accounts/{account_id}/r2/buckets | Create an R2 object-storage bucket on an account. | write | Workers R2 Storage Write | Current | |
Account scope. Creates storage that can hold objects and incur cost. Acts onr2_bucket Permission (capability) Workers R2 Storage WriteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
SSL/TLSList custom SSL certificates in a zone and read or change Universal SSL settings.3 | ||||||
| GET | /zones/{zone_id}/custom_certificates | List, search, and filter the custom SSL certificates in a zone. | read | SSL and Certificates Read | Current | |
Read-only. Zone scope. Acts oncustom_certificate Permission (capability) SSL and Certificates ReadVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /zones/{zone_id}/ssl/universal/settings | Get the Universal SSL settings for a zone. | read | SSL and Certificates Read | Current | |
Read-only. Zone scope. Acts onuniversal_ssl_setting Permission (capability) SSL and Certificates ReadVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /zones/{zone_id}/ssl/universal/settings | Enable or disable Universal SSL for a zone. | write | SSL and Certificates Write | Current | |
Disabling removes active Universal SSL certificates, which can make the domain unreachable over HTTPS. Zone scope. Acts onuniversal_ssl_setting Permission (capability) SSL and Certificates WriteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Load BalancersList the load balancers in a zone and create a new one.2 | ||||||
| GET | /zones/{zone_id}/load_balancers | List the load balancers configured in a zone. | read | Load Balancers Read | Current | |
Read-only. Zone scope. Acts onload_balancer Permission (capability) Load Balancers ReadVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /zones/{zone_id}/load_balancers | Create a load balancer that steers traffic across pools in a zone. | write | Load Balancers Write | Current | |
Zone scope. Changes how requests are routed across origin pools. Acts onload_balancer Permission (capability) Load Balancers WriteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
AccountsList the accounts a token can reach and read a single account's details.2 | ||||||
| GET | /accounts | List the accounts a token can reach. | read | Account Settings Read | Current | |
Read-only. Account scope. Acts onaccount Permission (capability) Account Settings ReadVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /accounts/{account_id} | Get the details of a single account. | read | Account Settings Read | Current | |
Read-only. Account scope. Acts onaccount Permission (capability) Account Settings ReadVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Cloudflare can notify an app or AI agent when something happens in an account, like a security event firing or a certificate nearing expiry, by sending the alert to a configured destination instead of the app repeatedly asking.
| Event | What it signals | Triggered by |
|---|
Cloudflare limits how fast an app or AI agent can call, through a request quota counted per user over a rolling window, with stricter quotas on a few areas like the analytics query interface.
Cloudflare meters the API by a global limit of 1,200 requests every five minutes per user, counted cumulatively across the dashboard, an API key, and an API token. Going over blocks every call for the rest of the five-minute window and returns HTTP 429. A separate per-IP ceiling of 200 requests per second applies, and the GraphQL analytics interface has its own quota that varies by query cost and caps at 320 queries per five minutes. A few areas carry tighter limits, like purge-everything on the cache. Responses carry Ratelimit and Ratelimit-Policy headers reporting remaining quota and the window, and a retry-after header when the limit has been hit. Enterprise customers can ask support to raise these.
List endpoints page with the page and per_page query parameters, and the response carries a result_info object with the current page, per-page count, total count, and total pages. Some newer resources, like rulesets, page with a cursor and per_page instead. The data itself is returned in the result array of the JSON envelope.
Responses are JSON wrapped in a success, errors, messages, and result envelope. An account is allowed 50 API tokens per user and 500 per account. Worker script size and other per-product ceilings are set by each product rather than the API as a whole.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | Bad Request | The request was malformed or a parameter was invalid. The body's errors array names the problem with an integer code and a message, and success is false. | Read the errors array, correct the named parameter, and resend. |
| 401 | Unauthorized | Authentication failed, because the API token is missing, invalid, or expired, or the legacy email and key pair is wrong. | Send a valid token as a Bearer credential, and roll it if it may be compromised. |
| 403 | Forbidden | The token is valid but lacks the permission group needed for this call, or is not scoped to the target account or zone. | Grant the missing permission group on the token, or scope it to the right account or zone. |
| 404 | Not Found | The resource does not exist, or the token cannot see it. The path or an identifier may be wrong. | Confirm the path and the account, zone, or record identifier, and that the token can reach it. |
| 405 | Method Not Allowed | The HTTP method is not supported for this path, like sending POST where only GET is defined. | Use the method the endpoint documents for the operation. |
| 429 | Too Many Requests | The rate limit was exceeded. The global limit is 1,200 requests per five minutes per user, after which calls are blocked for the rest of the window. | Honor the retry-after header, slow the request rate, and wait for the window to reset. |
| 500 | Internal Server Error | An error on Cloudflare's side, which can also appear as 502, 503, or 504. | Retry with backoff, and contact Cloudflare support if it persists. |
Cloudflare keeps a single, continuously updated version of its API at the v4 path, and signals retired methods through a dated deprecations list rather than minting new version numbers.
Cloudflare serves a single, continuously updated API at https://api.cloudflare.com/client/v4. It is not versioned beyond the v4 path; new resources and fields are added in place, and retired methods are announced through a dated deprecations list with an end-of-life date rather than a new version number. An integration tracks the deprecations list and moves off a method before its end of life.
Changing the type of an existing DNS record through the API was deprecated on 23 January 2026, with an end-of-life date of 30 June 2026. After that date, an integration recreates the record at the new type rather than changing the type of the existing one.
The standalone Firewall Rules API and the Filters API were deprecated on 15 June 2025, replaced by WAF custom rules managed through the Rulesets API. The previous version of WAF Managed Rules, managed through packages, rule groups, and overrides, was deprecated on the same date in favor of the new WAF Managed Rules, also through the Rulesets API.
The Brotli setting and its API endpoints were deprecated on 15 August 2024, and the Auto Minify API endpoints were deprecated on 5 August 2024, after both features were retired. Earlier, on 14 June 2024, the Server-side Excludes feature and its API endpoints were deprecated.
An integration tracks the deprecations list and moves off a retired method before its end-of-life date.
Cloudflare API deprecations ↗Bollard AI sits between a team's AI agents and Cloudflare. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.