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 Get a zone entry point ruleset operation to obtain the definition of the entry point ruleset for the http_request_firewall_custom phase. You will need the zone ID for this task.

2. If the entry point ruleset already exists (that is, if you received a 200 OK status code and the ruleset definition), take note of the ruleset ID in the response. Then, invoke the Create a zone ruleset rule operation to add a custom rule to the existing ruleset. Refer to the examples below for details.

3. If the entry point ruleset does not exist (that is, if you received a 404 Not Found status code in step 1), create it using the Create a zone ruleset operation. Include your custom rule in the rules array. Refer to Create ruleset for an example.

Example A

This example request 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 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:

Task	Procedure
List all rules in ruleset	Use the Get a zone entry point ruleset operation with the http_request_firewall_custom phase name to obtain the list of configured custom rules and their IDs. For more information, refer to View a specific ruleset.
Update a rule	Use the Update a zone ruleset rule operation. You will need to provide the ruleset ID and the rule ID. To obtain these IDs, you can use the Get a zone entry point ruleset operation with the http_request_firewall_custom phase name. For more information, refer to Update a rule in a ruleset.
Delete a rule	Use the Delete a zone ruleset rule operation. You will need to provide the ruleset ID and the rule ID. To obtain these IDs, you can use the Get a zone entry point ruleset operation with the http_request_firewall_custom phase name. For more information, refer to Delete a rule in a ruleset.

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