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.
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" \
-H "Authorization: Bearer <API_TOKEN>"
Response
{
"result": [
{
"id": "<PHASE_RULESET_ID>",
"name": "Zone-level phase entry point",
"description": "",
"kind": "zone",
"version": "5",
"last_updated": "2021-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 account entry point ruleset | GET /accounts/<ACCOUNT_ID>/rulesets/phases/<PHASE_NAME>/entrypoint |
| Get 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>" \
-H "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": "2021-03-17T15:42:37.917815Z"
}
],
"last_updated": "2021-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 versions of an account ruleset | GET /accounts/<ACCOUNT_ID>/rulesets/<RULESET_ID>/versions |
| List versions of a zone ruleset | GET /zones/<ZONE_ID>/rulesets/<RULESET_ID>/versions |
| List versions of an account entry point ruleset | GET /accounts/<ACCOUNT_ID>/rulesets/phases/<PHASE_NAME>/entrypoint/versions |
| List versions of a zone entry point ruleset | 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.
For Managed Rulesets, this method returns a list with one item with the information about the most recent version of the ruleset.
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" \
-H "Authorization: Bearer <API_TOKEN>"
Response
{
"result": [
{
"id": "<RULESET_ID>",
"name": "Zone Ruleset 1",
"description": "",
"kind": "zone",
"version": "1",
"last_updated": "2021-02-17T11:15:13.128705Z",
"phase": "http_request_firewall_managed"
},
{
"id": "<RULESET_ID>",
"name": "Zone Ruleset 1",
"description": "",
"kind": "zone",
"version": "2",
"last_updated": "2021-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 account entry point ruleset version | GET /accounts/<ACCOUNT_ID>/rulesets/phases/<PHASE_NAME>/entrypoint/versions/<VERSION_NUMBER> |
| Get zone entry point ruleset version | GET /zones/<ZONE_ID>/rulesets/phases/<PHASE_NAME>/entrypoint/versions/<VERSION_NUMBER> |
You can view the rules in all the versions of a custom ruleset. However, you can only view the rules of the latest version of a Managed Ruleset.
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>" \
-H "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": "2021-03-17T15:42:37.917815Z"
}
],
"last_updated": "2021-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 ruleset 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" \
-H "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": "2021-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": "2021-03-19T16:54:32.942986Z",
"ref": "<RULE_REF_2>",
"enabled": true
}
// (...)
],
"last_updated": "2021-03-19T16:54:32.942986Z",
"phase": "http_request_firewall_managed"
},
"success": true,
"errors": [],
"messages": []
}