导航|地址|刷新
Create a custom rule via API

Skip to contentDocumentation Index
Fetch the complete documentation index at: https://developers.cloudflare.com/waf/llms.txt
Use this file to discover all available pages before exploring further.

Docs Directory API SDKs Changelog

Search

Log in

WAF

/

Overview

Get started

Concepts

Traffic detections

Overview

Attack score

Leaked credentials

Overview

Get started

Common API calls

Terraform examples

Example mitigation rules

Malicious uploads

Overview

Get started

Example rules

Common API calls

Terraform examples

AI Security for Apps

Overview

Get started

PII detection

Unsafe and custom topic detection

Prompt injection detection

Token counting

Example mitigation rules

Log mode vs production mode

Available fields

Bot score ↗

Threat intelligence

Overview

Get started

Example rules

Available fields

Custom rules

Overview

Create in the dashboard

Create via API

Create using Terraform ↗

Configure a rule with the Skip action

Overview

API examples

Skip options

Common use cases

Allow traffic from IP addresses in allowlist only

Allow traffic from search engine bots

Allow traffic from specific countries only

Block Microsoft Exchange Autodiscover requests

Block requests by attack score

Block traffic by geographical location

Block traffic from specific countries

Build a sequence rule within custom rules

Challenge bad bots

Configure token authentication

Exempt partners from Hotlink Protection

Issue challenge for admin user in JWT claim based on attack score

Require a specific cookie

Require known IP addresses in site admin area

Require specific HTTP headers

Require specific HTTP ports

Stop R-U-Dead-Yet? (R.U.D.Y.) attacks

Update custom rules for customers or partners

Custom rulesets

Rate limiting rules

Overview

Request rate calculation

Create in the dashboard

Create via API

Create using Terraform ↗

Find appropriate rate limit

Rate limiting parameters

Rule examples

Best practices

Troubleshooting

Managed rules

Overview

Deploy in the dashboard

Deploy via API

Deploy using Terraform ↗

Troubleshooting

Create exceptions

Overview

Add an exception in the dashboard

Add an exception via API

Log the payload of matched rules

Overview

Configure in the dashboard

View the payload content in the dashboard

Configure via API

Store decrypted matched payloads in logs

Command-line operations

Overview

Generate a key pair

Decrypt the payload content

Check for exposed credentialsDeprecated

Overview

How it works

Configure via API

Configure using Terraform

Test your configuration

Monitor exposed credentials events

Upgrade to leaked credentials detection

Rulesets reference

Cloudflare Managed Ruleset

Cloudflare OWASP Core Ruleset

Overview

Concepts

Evaluation example

Configure in the dashboard

Configure via API

Configure in Terraform ↗

Cloudflare Exposed Credentials Check Managed RulesetDeprecated

Cloudflare Sensitive Data Detection

Additional tools

Lists

Overview

Custom lists

Bulk Redirect Lists ↗

Managed Lists

Create in the dashboard

Use lists in expressions

Lists API

Overview

JSON object

Endpoints

IP Access rules

Overview

Create a rule

Parameters

Actions

Scrape Shield

Overview

Email Address Obfuscation

Hotlink Protection

User Agent Blocking

Zone Lockdown

Browser Integrity Check

Enable security.txt ↗

Privacy Pass

Replace insecure JS libraries

Security Level

Validation checks

Account-level configuration

Overview

Custom rulesets

Overview

Use the dashboard

Use the API

Use Terraform ↗

Rate limiting rulesets

Overview

Create in the dashboard

Create via API

Create using Terraform ↗

Managed rulesets

Overview

Deploy in the dashboard

Deploy via API

Deploy using Terraform ↗

Create exceptions ↗

Analytics

Security Analytics

Security Events

Security features interoperability

Reference

Alerts

Phases

Legacy features

WAF managed rules (previous version)

Overview

Troubleshooting

WAF managed rules upgrade

Rate Limiting (previous version)

Overview

Troubleshooting

Rate limiting upgrade

Firewall rules ↗

Firewall rules upgrade

Troubleshooting

Bing's Site Scan blocked by a managed rule

Fake bot detection blocking legitimate requests

Issues sharing to Facebook

SameSite cookie interaction with Cloudflare

Rule phase interactions

FAQ

Glossary

Changelog

Overview

Changelog

Scheduled changes

Historical (2024)

Historical (2023)

Historical (2022)

Agent resources

Agent setup ↗

Cloudflare Skills ↗

Code Mode MCP Server ↗

Domain-specific MCP Servers ↗MCP

WAF llms.txt ↗

WAF llms-full.txt ↗

Cloudflare Docs llms.txt ↗

Cloudflare Docs llms-full.txt ↗

Home

/WAF

/Custom rules

/Create via API

Create a custom rule via API

Last updated Apr 16, 2026|Copy as Markdown|View as Markdown|Agent setup

OverviewCreate a custom rule Example A Example BNext stepsMore resources

Use the Rulesets API to create a custom rule via API at the zone level.

You must deploy custom rules to the http_request_firewall_customphase entry point ruleset.

If you are using Terraform, refer to WAF custom rules configuration using Terraform.

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.

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.

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.

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 an A number from 1 (likely malicious) to 99 (likely clean) classifying how likely an incoming request is malicious or not. Allows you to detect new attack techniques before they are publicly known.
" class="glossary-tooltip" tabindex="0" data-astro-cid-hklyqugd>attack score lower than 20.
Create a zone ruleset rulebashcurl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/rulesets/$RULESET_ID/rules" \ --request POST \ --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \ --json '{ "description": "My custom rule", "expression": "(ip.src.country eq \"GB\" or ip.src.country eq \"FR\") and cf.waf.score lt 20", "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.
Create a zone ruleset rulebashcurl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/rulesets/$RULESET_ID/rules" \ --request POST \ --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \ --json '{ "description": "My custom rule with plain text response", "expression": "(ip.src.country eq \"GB\" or ip.src.country eq \"FR\") and cf.waf.score lt 20", "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.

More resources

For instructions on deploying custom rules at the account level via API, refer to Create a custom ruleset using the API.

PreviousCreate in the dashboardNextCreate using Terraform ↗

Was this helpful?

YesNo

Edit pageReport issue

On this page

Overview

Create a custom rule

Example A

Example B

Next steps

More resources

Edit pageReport issue

Getting started
PlansContact salesPartnersFind a partnerStartupsUnder attack?Domain name search

Company
AboutCareersInvestorsPressPress kitGlobal network

Public interest
Project GalileoAthenian ProjectCloudflare for CampaignsProject FairshotImpact/ESG

Compliance
Compliance resourcesTrust HubData ProtectionResponsible AITransparency reportReport abuse

Resources
App innovation reportCloudflare RadarCase studiesStatusSupportEventsBlog

Developers
DocumentationLearning centerCommunity

Solutions
SSE and SASE platformCloudflare AI CloudAI SecurityFrontend Development PlatformMulti-Tenant Platform DevelopmentWeb Security Platform

Start BuildingLog In

© 2026 Cloudflare, Inc.

Privacy policy|Report security issues|Terms of use|Trademark
|
Your privacy choices

Docs

------
导航页打开网址

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.