Create firewall rules

Deprecated: The Firewall Rules API is deprecated in favour of using the Ruleset Engine. See https://developers.cloudflare.com/fundamentals/api/reference/deprecations/#firewall-rules-api-and-filters-api for full details.

POST/zones/{zone_id}/firewall/rules

Create one or more firewall rules.

Security

API Token

The preferred authorization scheme for interacting with the Cloudflare API. Create a token.

Example:Authorization: Bearer Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY

API Email + API Key

The previous authorization scheme for interacting with the Cloudflare API, used in conjunction with a Global API key.

Example:X-Auth-Email: user@example.com

The previous authorization scheme for interacting with the Cloudflare API. When possible, use API tokens instead of Global API keys.

Example:X-Auth-Key: 144c9defac04969c7bfad8efaa8ea194

Accepted Permissions (at least one required)

Firewall Services Write

Path ParametersExpand Collapse

zone_id: string

Defines an identifier.

maxLength32

Body ParametersJSONExpand Collapse

action: object { mode, response, timeout }

The action to perform when the threshold of matched traffic within the configured period is exceeded.

mode: optional "simulate" or "ban" or "challenge" or 2 more

The action to perform.

One of the following:

"simulate"

"ban"

"challenge"

"js_challenge"

"managed_challenge"

response: optional object { body, content_type }

A custom content type and reponse to return when the threshold is exceeded. The custom response configured in this object will override the custom error for the zone. This object is optional. Notes: If you omit this object, Cloudflare will use the default HTML error page. If mode is challenge, managed_challenge, or js_challenge, Cloudflare will use the zone challenge pages and you should not provide the response object.

body: optional string

The response body to return. The value must conform to the configured content type.

maxLength10240

content_type: optional string

The content type of the body. Must be one of the following: text/plain, text/xml, or application/json.

maxLength50

timeout: optional number

The time in seconds during which Cloudflare will perform the mitigation action. Must be an integer value greater than or equal to the period. Notes: If mode is challenge, managed_challenge, or js_challenge, Cloudflare will use the zones Challenge Passage time and you should not provide this value.

maximum86400

minimum1

filter: FirewallFilter { id, description, expression, 2 more }

id: optional string

The unique identifier of the filter.

maxLength32

minLength32

description: optional string

An informative summary of the filter.

maxLength500

expression: optional string

The filter expression. For more information, refer to Expressions.

paused: optional boolean

When true, indicates that the filter is currently paused.

ref: optional string

A short reference tag. Allows you to select related filters.

maxLength50

ReturnsExpand Collapse

errors: array of ResponseInfo { code, message, documentation_url, source }

code: number

minimum1000

message: string

documentation_url: optional string

source: optional object { pointer }

pointer: optional string

messages: array of ResponseInfo { code, message, documentation_url, source }

code: number

minimum1000

message: string

documentation_url: optional string

source: optional object { pointer }

pointer: optional string

result: array of FirewallRule { id, action, description, 5 more }

id: optional string

The unique identifier of the firewall rule.

maxLength32

action: optional Action

The action to apply to a matched request. The log action is only available on an Enterprise plan.

One of the following:

"block"

"challenge"

"js_challenge"

"managed_challenge"

"allow"

"log"

"bypass"

description: optional string

An informative summary of the firewall rule.

maxLength500

filter: optional FirewallFilter { id, description, expression, 2 more } or DeletedFilter { id, deleted }

One of the following:

FirewallFilter object { id, description, expression, 2 more }

id: optional string

The unique identifier of the filter.

maxLength32

minLength32

description: optional string

An informative summary of the filter.

maxLength500

expression: optional string

The filter expression. For more information, refer to Expressions.

paused: optional boolean

When true, indicates that the filter is currently paused.

ref: optional string

A short reference tag. Allows you to select related filters.

maxLength50

DeletedFilter object { id, deleted }

id: string

The unique identifier of the filter.

maxLength32

minLength32

deleted: boolean

When true, indicates that the firewall rule was deleted.

paused: optional boolean

When true, indicates that the firewall rule is currently paused.

priority: optional number

The priority of the rule. Optional value used to define the processing order. A lower number indicates a higher priority. If not provided, rules with a defined priority will be processed before rules without a priority.

maximum2147483647

minimum0

products: optional array of Product

One of the following:

"zoneLockdown"

"uaBlock"

"bic"

"hot"

"securityLevel"

"rateLimit"

"waf"

ref: optional string

A short reference tag. Allows you to select related firewall rules.

maxLength50

success: true

Defines whether the API call was successful.

result_info: optional object { count, page, per_page, total_count }

count: optional number

Defines the total number of results for the requested service.

page: optional number

Defines the current page within paginated list of results.

per_page: optional number

Defines the number of results per page of results.

total_count: optional number

Defines the total results available without any search parameters.

Create firewall rules

curl https://api.cloudflare.com/client/v4/zones/$ZONE_ID/firewall/rules \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
    -d '{
          "action": {},
          "filter": {}
        }'

200 example

{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "result": [
    {
      "id": "372e67954025e0ba6aaa6d586b9e0b60",
      "action": "block",
      "description": "Blocks traffic identified during investigation for MIR-31",
      "filter": {
        "id": "372e67954025e0ba6aaa6d586b9e0b61",
        "description": "Restrict access from these browsers on this address range.",
        "expression": "(http.request.uri.path ~ \".*wp-login.php\" or http.request.uri.path ~ \".*xmlrpc.php\") and ip.addr ne 172.16.22.155",
        "paused": false,
        "ref": "FIL-100"
      },
      "paused": false,
      "priority": 50,
      "products": [
        "waf"
      ],
      "ref": "MIR-31"
    }
  ],
  "success": true,
  "result_info": {
    "count": 1,
    "page": 1,
    "per_page": 20,
    "total_count": 2000
  }
}

Returns Examples

200 example

{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "result": [
    {
      "id": "372e67954025e0ba6aaa6d586b9e0b60",
      "action": "block",
      "description": "Blocks traffic identified during investigation for MIR-31",
      "filter": {
        "id": "372e67954025e0ba6aaa6d586b9e0b61",
        "description": "Restrict access from these browsers on this address range.",
        "expression": "(http.request.uri.path ~ \".*wp-login.php\" or http.request.uri.path ~ \".*xmlrpc.php\") and ip.addr ne 172.16.22.155",
        "paused": false,
        "ref": "FIL-100"
      },
      "paused": false,
      "priority": 50,
      "products": [
        "waf"
      ],
      "ref": "MIR-31"
    }
  ],
  "success": true,
  "result_info": {
    "count": 1,
    "page": 1,
    "per_page": 20,
    "total_count": 2000
  }
}