Migrate to the Rulesets API
The Firewall Rules API and Filters API were deprecated by Cloudflare on 2025-06-15 and replaced by the Rulesets API. This repository has been fully migrated to the new API.
What changed
| Aspect | Old (Firewall Rules API) | New (Rulesets API) |
|---|---|---|
| Rule creation | 2 API calls per rule (filter + rule) | 1 API call (expression inline) |
| Profile schema | v2 with priority field | v3 with enabled/logging/action_parameters |
| Skip action | allow + bypass (two actions) | skip (one action with config) |
| Custom responses | Not supported | Supported for the block action |
| Logging control | Not supported | Per-rule logging.enabled |
| Rate limiting | Separate product | Configurable within custom rules |
Action migration
| Old action | New action | Notes |
|---|---|---|
allow | skip with "ruleset": "current" | Stops evaluating remaining custom rules |
bypass | skip with "phases": [...] | Skips specific security products |
block | block | Same, with an optional custom response |
challenge / js_challenge / managed_challenge | Same | No changes needed |
log | log | Same |
One-time migration
If you have existing Firewall Rules on your zones, use the migration tool to convert them:
# Preview the migration (rules are applied, old ones preserved)
./cfwr.sh -v1 -d domain.com -c migrate-to-rulesets
# Full migration with cleanup of old rules and filters
./cfwr.sh -v1 -d domain.com -c migrate-to-rulesets --delete-old
# Multi-zone migration
./cfwr.sh -v1 -zf zones.txt -c migrate-to-rulesets
The migration tool:
- Fetches all existing Firewall Rules through the old API.
- Converts them to Rulesets API format (
allow→skip, priority removed, and so on). - Applies them to the phase entry point.
- Optionally deletes the old rules and filters after verification.
Profile conversion
A v2 profile needs three mechanical changes before it can be applied — priority
removed, allow/bypass replaced by skip, and enabled/logging added to
each rule. The profile format reference
lists the mapping line by line.
The profiles in profiles/ are already v3, so there is usually nothing to
convert: start from profiles/mwp-rules-beta.json and edit it.
Required API token permissions
For the Rulesets API, make sure your API token includes at least one of:
Zone WAF Write— for zone-level custom rulesZone Rulesets Write— for zone-level ruleset managementAccount WAF Write— for account-level custom rulesetsAccount Rulesets Write— for account-level ruleset management
The old Zone.Firewall Services:Edit permission may still work for backward
compatibility, but the new permissions are recommended.