Update Zone Precursor Config

PUT/zones/{zone_id}/precursor

Updates the Precursor configuration for a zone.

default_mode sets the zone-level enforcement mode. enforcement_rules is the ordered list of rules that override enforcement for matching requests.

This is a partial update: only the fields present in the request body are changed.

Sending an empty array ([]) clears all enforcement rules.
At least one of default_mode or enforcement_rules must be present; an empty body ({}) is rejected with 400.
Rule id is read-only (assigned by Cloudflare) and ignored on input.
Rule mode must be min-friction or max-security (off is not a valid rule mode; use default_mode to disable enforcement).
Rule expression is limited to 4000 characters. The limit applies to each rule individually, not to the combined size of all 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

Path ParametersExpand Collapse

zone_id: string

Identifier.

maxLength32

Body ParametersJSONExpand Collapse

default_mode: optional "off" or "min-friction" or "max-security"

The zone-level Precursor enforcement mode applied to requests that do not match a more specific enforcement rule.

One of the following:

"off"

"min-friction"

"max-security"

enforcement_rules: optional array of EnforcementRule { expression, mode, id, 2 more }

The ordered list of enforcement rules for the zone.

expression: string

The filter expression that determines which requests the rule matches.

maxLength4000

mode: "min-friction" or "max-security"

The override mode Precursor applies to requests matching an enforcement rule. Unlike default_mode, this cannot be off.

One of the following:

"min-friction"

"max-security"

id: optional string

The read-only identifier that Cloudflare assigns to the rule.

description: optional string

An informative description of the rule.

enabled: optional boolean

Whether the rule is active.

ReturnsExpand Collapse

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

code: number

minimum1000

message: string

documentation_url: optional string

source: optional object { pointer }

pointer: optional string

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

code: number

minimum1000

message: string

documentation_url: optional string

source: optional object { pointer }

pointer: optional string

success: true

Whether the API call was successful.

result: optional PrecursorConfig { default_mode, enforcement_rules }

default_mode: optional "off" or "min-friction" or "max-security"

The zone-level Precursor enforcement mode applied to requests that do not match a more specific enforcement rule.

One of the following:

"off"

"min-friction"

"max-security"

enforcement_rules: optional array of EnforcementRule { expression, mode, id, 2 more }

The ordered list of enforcement rules for the zone.

expression: string

The filter expression that determines which requests the rule matches.

maxLength4000

mode: "min-friction" or "max-security"

The override mode Precursor applies to requests matching an enforcement rule. Unlike default_mode, this cannot be off.

One of the following:

"min-friction"

"max-security"

id: optional string

The read-only identifier that Cloudflare assigns to the rule.

description: optional string

An informative description of the rule.

enabled: optional boolean

Whether the rule is active.

Update Zone Precursor Config

curl https://api.cloudflare.com/client/v4/zones/$ZONE_ID/precursor \
    -X PUT \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
    -d '{
          "default_mode": "min-friction"
        }'

{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "success": true,
  "result": {
    "default_mode": "min-friction",
    "enforcement_rules": [
      {
        "expression": "http.request.uri.path eq \"/shop\"",
        "mode": "max-security",
        "id": "3a03d665bac043e3a684e0d385a4b1e2",
        "description": "Enforce max-security on the shop page",
        "enabled": true
      }
    ]
  }
}

Returns Examples

{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "success": true,
  "result": {
    "default_mode": "min-friction",
    "enforcement_rules": [
      {
        "expression": "http.request.uri.path eq \"/shop\"",
        "mode": "max-security",
        "id": "3a03d665bac043e3a684e0d385a4b1e2",
        "description": "Enforce max-security on the shop page",
        "enabled": true
      }
    ]
  }
}