Cloudflare Docs
Ruleset Engine
Cloudflare Docs
Ruleset Engine
GitHub icon
Visit Ruleset Engine on GitHub
Set theme to dark (⇧+D)
  1. Products
  2. Ruleset Engine
  3. Rulesets API
  4. List and view rulesets

List and view rulesets

​​ 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.

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

​​ Example

Request 

curl https://api.cloudflare.com/client/v4/zones/{zone_id}/rulesets \

--header "Authorization: Bearer <API_TOKEN>"
Response 

{
  "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

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

Request 

curl https://api.cloudflare.com/client/v4/zones/{zone_id}/rulesets/{ruleset_id} \

--header "Authorization: Bearer <API_TOKEN>"
Response 

{
  "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. Check View a specific version of a ruleset to get this information.

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

​​ Example

Request 

curl https://api.cloudflare.com/client/v4/zones/{zone_id}/rulesets/{ruleset_id}/versions \

--header "Authorization: Bearer <API_TOKEN>"
Response 

{
  "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

Request 

curl https://api.cloudflare.com/client/v4/zones/{zone_id}/rulesets/{ruleset_id}/versions/{version_number} \

--header "Authorization: Bearer <API_TOKEN>"
Response 

{
  "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 rules in a managed ruleset with a specific tag

Returns a list of all the rules in a managed ruleset with a specific tag.

Operation Method + Endpoint
List rules in account ruleset version by tag GET /accounts/{account_id}/rulesets/{managed_ruleset_id}/versions/{version_number}/by_tag/{tag_name}

​​ Example

Request 

curl https://api.cloudflare.com/client/v4/accounts/{account_id}/rulesets/{ruleset_id}/versions/2/by_tag/wordpress \

--header "Authorization: Bearer <API_TOKEN>"
Response 

{
  "result": {
    "id": "<MANAGED_RULESET_ID>",
    "name": "Cloudflare Managed Ruleset",
    "description": "Managed ruleset created by Cloudflare",
    "kind": "managed",
    "version": "4",
    "rules": [
      {
        "id": "<RULE_ID_1>",
        "version": "3",
        "action": "log",
        "categories": [
          "cve-2014-5265",
          "cve-2014-5266",
          "cve-2014-5267",
          "dos",
          "drupal",
          "wordpress"
        ],
        "description": "Drupal, WordPress - DoS - XMLRPC - CVE:CVE-2014-5265, CVE:CVE-2014-5266, CVE:CVE-2014-5267",
        "last_updated": "2023-03-19T16:54:32.942986Z",
        "ref": "<RULE_REF_1>",
        "enabled": true
      },
      {
        "id": "<RULE_ID_2>",
        "version": "3",
        "action": "block",
        "categories": ["broken-access-control", "cve-2018-12895", "wordpress"],
        "description": "WordPress - Broken Access Control - CVE:CVE-2018-12895",
        "last_updated": "2023-03-19T16:54:32.942986Z",
        "ref": "<RULE_REF_2>",
        "enabled": true
      }
      // (...)
    ],
    "last_updated": "2023-03-19T16:54:32.942986Z",
    "phase": "http_request_firewall_managed"
  },
  "success": true,
  "errors": [],
  "messages": []

}