List and view rulesets

• List existing rulesets
• View a specific ruleset
• List all versions of a ruleset
• View a specific version of a ruleset
• List rules in a managed ruleset with a specific tag

List existing rulesets

Returns the list of existing rulesets at the account level or at the zone level.

Use one of the following API endpoints:

Operation	Method + Endpoint
List account rulesets	GET /accounts/{account_id}/rulesets
List zone rulesets	GET /zones/{zone_id}/rulesets

The result includes rulesets across all phases at a given level (account or zone). The phase field in each result element indicates the phase where that ruleset is defined.

Also, the list of rulesets at the zone level includes the account-level rulesets you may want to deploy to the specified zone.

Note

Not all zone-level phases support all types of rulesets, even if they are presented in the list returned by this API method. Check the documentation for each Cloudflare product for more information on which ruleset types are allowed in that product's supported phases.

The result does not include the list of rules in the ruleset. Refer to View a specific version of a ruleset to learn how to obtain the list of rules.

Example

curl https://api.cloudflare.com/client/v4/zones/{zone_id}/rulesets \
--header "Authorization: Bearer <API_TOKEN>"

{
  "result": [
    {
      "id": "<PHASE_RULESET_ID>",
      "name": "Zone-level phase entry point",
      "description": "",
      "kind": "zone",
      "version": "5",
      "last_updated": "2023-03-18T18:30:08.122758Z",
      "phase": "http_request_firewall_managed"
    }
  ],
  "success": true,
  "errors": [],
  "messages": []
}

View a specific ruleset

Returns the properties of the most recent version of the ruleset with the specified ruleset ID.

Use one of the following API endpoints:

Operation	Method + Endpoint
Get an account ruleset	GET /accounts/{account_id}/rulesets/{ruleset_id}
Get a zone ruleset	GET /zones/{zone_id}/rulesets/{ruleset_id}
Get an account entry point ruleset	GET /accounts/{account_id}/rulesets/phases/{phase_name}/entrypoint
Get a zone entry point ruleset	GET /zones/{zone_id}/rulesets/phases/{phase_name}/entrypoint

Note

You can only use the Get a zone ruleset operation for zone-level phase entry points (entry points where kind is set to zone).

The API returns a 404 Not Found HTTP status code under these conditions:

• When a ruleset cannot be found.
• When the specified ruleset is not a managed ruleset the calling account is entitled to execute.

Example

curl https://api.cloudflare.com/client/v4/zones/{zone_id}/rulesets/{ruleset_id} \
--header "Authorization: Bearer <API_TOKEN>"

{
  "result": {
    "id": "<RULESET_ID>",
    "name": "Zone-level phase entry point",
    "description": "Executes a managed ruleset.",
    "kind": "zone",
    "version": "3",
    "rules": [
      {
        "id": "<RULE_ID>",
        "version": "1",
        "action": "execute",
        "expression": "true",
        "action_parameters": {
          "id": "<MANAGED_RULESET_ID>"
        },
        "last_updated": "2023-03-17T15:42:37.917815Z"
      }
    ],
    "last_updated": "2023-03-17T15:42:37.917815Z",
    "phase": "http_request_firewall_managed"
  },
  "success": true,
  "errors": [],
  "messages": []
}

List all versions of a ruleset

Returns a list of all the versions of a ruleset.

Use one of the following API endpoints:

Operation	Method + Endpoint
List account ruleset versions	GET /accounts/{account_id}/rulesets/{ruleset_id}/versions
List zone ruleset versions	GET /zones/{zone_id}/rulesets/{ruleset_id}/versions
List account entry point ruleset versions	GET /accounts/{account_id}/rulesets/phases/{phase_name}/entrypoint/versions
List zone entry point ruleset versions	GET /zones/{zone_id}/rulesets/phases/{phase_name}/entrypoint/versions

The result contains the ruleset properties of each version, but it does not include the list of rules. Refer to View a specific version of a ruleset for instructions on obtaining this information.

When the specified phase entry point ruleset does not exist, this API method returns an empty array in the result field.

Example

curl https://api.cloudflare.com/client/v4/zones/{zone_id}/rulesets/{ruleset_id}/versions \
--header "Authorization: Bearer <API_TOKEN>"

{
  "result": [
    {
      "id": "<RULESET_ID>",
      "name": "Zone Ruleset 1",
      "description": "",
      "kind": "zone",
      "version": "1",
      "last_updated": "2023-02-17T11:15:13.128705Z",
      "phase": "http_request_firewall_managed"
    },
    {
      "id": "<RULESET_ID>",
      "name": "Zone Ruleset 1",
      "description": "",
      "kind": "zone",
      "version": "2",
      "last_updated": "2023-02-17T11:24:06.869326Z",
      "phase": "http_request_firewall_managed"
    }
  ],
  "success": true,
  "errors": [],
  "messages": []
}

View a specific version of a ruleset

Returns the configuration of a specific version of a ruleset, including its rules.

Use one of the following API endpoints:

Operation	Method + Endpoint
Get an account ruleset version	GET /account/{account_id}/rulesets/{ruleset_id}/versions/{version_number}
Get a zone ruleset version	GET /zones/{zone_id}/rulesets/{ruleset_id}/versions/{version_number}
Get an account entry point ruleset version	GET /accounts/{account_id}/rulesets/phases/{phase_name}/entrypoint/versions/{version_number}
Get a zone entry point ruleset version	GET /zones/{zone_id}/rulesets/phases/{phase_name}/entrypoint/versions/{version_number}

When the specified phase entry point ruleset does not exist, this API method returns a 404 Not Found HTTP status code.

Example

curl https://api.cloudflare.com/client/v4/zones/{zone_id}/rulesets/{ruleset_id}/versions/{version_number} \
--header "Authorization: Bearer <API_TOKEN>"

{
  "result": {
    "id": "<RULESET_ID>",
    "name": "Zone-level phase entry point",
    "description": "Executes a managed ruleset.",
    "kind": "zone",
    "version": "3",
    "rules": [
      {
        "id": "<RULE_ID>",
        "version": "1",
        "action": "execute",
        "expression": "true",
        "action_parameters": {
          "id": "<MANAGED_RULESET_ID>"
        },
        "last_updated": "2023-03-17T15:42:37.917815Z"
      }
    ],
    "last_updated": "2023-03-17T15:42:37.917815Z",
    "phase": "http_request_firewall_managed"
  },
  "success": true,
  "errors": [],
  "messages": []
}

Note

When you view a specific version of a managed ruleset, each rule listed in the result can have one or more associated categories/tags, and it will not contain an expression.

Was this helpful?

What did you like?

Accurate

Easy to understand

Solved my problem

Helped me decide to use the product

Other

What went wrong?

Hard to understand

Incorrect information

Missing the information

Other

Thank you for helping improve Cloudflare's documentation!