Update Zone Precursor Config

precursor.update() -> PrecursorConfig

PUT/zones/{zone_id}/precursor

Updates the Precursor configuration for a zone.

mode controls whether Precursor detection is off, monitoring, or armed. show_interstitial controls the zone-level response when armed. rules is the ordered list of overrides for matching requests.

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

Sending an empty array ([]) clears all rules.
At least one of mode, show_interstitial, or rules must be present; an empty body ({}) is rejected with 400.
Rule id is read-only (assigned by Cloudflare) and ignored on input.
Rule show_interstitial is required and controls the response for requests that match that rule.
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

ParametersExpand Collapse

zone_id: str

Identifier.

maxLength32

cloudflare_version: Literal["1.0"]

mode: Optional[Literal["off", "monitor", "arm"]]

Controls Precursor detection for the zone. off disables detection, monitor records detections without affecting bot scores, and arm allows detections to affect bot scores.

One of the following:

"off"

"monitor"

"arm"

rules: Optional[Iterable[Rule]]

The ordered list of Precursor rules for the zone.

expression: str

The filter expression that determines which requests the rule matches.

maxLength4000

show_interstitial: bool

Whether Precursor shows an interstitial when it takes action on a request.

id: Optional[str]

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

description: Optional[str]

An informative description of the rule.

enabled: Optional[bool]

Whether the rule is active.

show_interstitial: Optional[bool]

Whether Precursor shows an interstitial when it takes action on a request.

ReturnsExpand Collapse

class PrecursorConfig: …

mode: Optional[Literal["off", "monitor", "arm"]]

Controls Precursor detection for the zone. off disables detection, monitor records detections without affecting bot scores, and arm allows detections to affect bot scores.

One of the following:

"off"

"monitor"

"arm"

rules: Optional[List[Rule]]

The ordered list of Precursor rules for the zone.

expression: str

The filter expression that determines which requests the rule matches.

maxLength4000

show_interstitial: bool

Whether Precursor shows an interstitial when it takes action on a request.

id: Optional[str]

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

description: Optional[str]

An informative description of the rule.

enabled: Optional[bool]

Whether the rule is active.

show_interstitial: Optional[bool]

Whether Precursor shows an interstitial when it takes action on a request.

Update Zone Precursor Config

import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
precursor_config = client.precursor.update(
    zone_id="023e105f4ecef8ad9ca31a8372d0c353",
    mode="monitor",
)
print(precursor_config.mode)

{
  "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": {
    "mode": "arm",
    "rules": [
      {
        "expression": "http.request.uri.path eq \"/shop\"",
        "show_interstitial": true,
        "id": "3a03d665bac043e3a684e0d385a4b1e2",
        "description": "Show an interstitial on the shop page",
        "enabled": true
      }
    ],
    "show_interstitial": false
  }
}

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": {
    "mode": "arm",
    "rules": [
      {
        "expression": "http.request.uri.path eq \"/shop\"",
        "show_interstitial": true,
        "id": "3a03d665bac043e3a684e0d385a4b1e2",
        "description": "Show an interstitial on the shop page",
        "enabled": true
      }
    ],
    "show_interstitial": false
  }
}