Create a custom rule via API

Use the Rulesets API to create a custom rule via API.

You must deploy custom rules to the http_request_firewall_custom phase entry point ruleset.

​​ Create a custom rule

To create a custom rule for a zone, add a rule to the http_request_firewall_custom phase entry point ruleset.

1. Invoke the List zone rulesets Open API docs link method to obtain the list of rulesets in your zone. You will need the zone ID for this operation.

2. Search for an entry point ruleset for the http_request_firewall_custom phase in the response. Such a ruleset would have the following properties: "kind": "zone" and "phase": "http_request_firewall_custom". If you find the ruleset, take note of its ID for the next step.

3. If the entry point ruleset already exists, invoke the Create a zone ruleset rule Open API docs link operation to add a custom rule to the existing ruleset. By default, the rule will be added at the end of the list of rules already in the ruleset. Refer to the examples below for details.

   If the entry point ruleset does not exist, invoke the Create a zone ruleset Open API docs link operation to create the entry point ruleset with the new custom rule. Refer to Create ruleset for an example.

​​ Example A

This example request, which covers step 3 in the rule creation procedure, adds a rule to the http_request_firewall_custom phase entry point ruleset for the zone with ID {zone_id}. The entry point ruleset already exists, with ID {ruleset_id}.

The new rule, which will be the last rule in the ruleset, will challenge requests from the United Kingdom or France with a threat score greater than 10:

curl https://api.cloudflare.com/client/v4/zones/{zone_id}/rulesets/{ruleset_id}/rules \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Content-Type: application/json" \
--data '{
  "description": "My custom rule",
  "expression": "(ip.geoip.country eq \"GB\" or ip.geoip.country eq \"FR\") and cf.threat_score > 10",
  "action": "challenge"
}'

To define a specific position for the new rule, include a position object in the request body according to the guidelines in Change the order of a rule in a ruleset.

For instructions on creating an entry point ruleset and defining its rules using a single API call, refer to Add rules to phase entry point rulesets.

​​ Example B

This example request, which covers step 3 in the rule creation procedure, adds a rule to the http_request_firewall_custom phase entry point ruleset for the zone with ID {zone_id}. The entry point ruleset already exists, with ID {ruleset_id}.

The new rule, which will be the last rule in the ruleset, includes the definition of a custom response for blocked requests:

curl https://api.cloudflare.com/client/v4/zones/{zone_id}/rulesets/{ruleset_id}/rules \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Content-Type: application/json" \
--data '{
  "description": "My custom rule with plain text response",
  "expression": "(ip.geoip.country eq \"GB\" or ip.geoip.country eq \"FR\") and cf.threat_score > 50",
  "action": "block",
  "action_parameters": {
    "response": {
      "status_code": 403,
      "content": "Your request was blocked.",
      "content_type": "text/plain"
    }
  }
}'

To define a specific position for the new rule, include a position object in the request body according to the guidelines in Change the order of a rule in a ruleset.

For instructions on creating an entry point ruleset and defining its rules using a single API call, refer to Add rules to phase entry point rulesets.

​​ Next steps

Use the different operations in the Rulesets API to work with the rule you just created. The following table has a list of common tasks:

These operations are covered in the Ruleset Engine documentation. The Ruleset Engine powers different Cloudflare products, including custom rules.