Skip to content

Commit 3f78abf

Browse files
pedrosousapedrosousa
committed
Update Rulesets API examples
1 parent a79fdde commit 3f78abf

File tree

7 files changed

+250
-264
lines changed

7 files changed

+250
-264
lines changed

‎src/content/docs/ruleset-engine/rulesets-api/add-rule.mdx‎

Lines changed: 15 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ sidebar:
66
order: 7
77
---
88

9-
import { Render } from "~/components";
9+
import { Render, APIRequest } from "~/components";
1010

1111
Adds a single rule to an existing ruleset. Use this endpoint to add a rule without having to include all the existing ruleset rules in the request.
1212

@@ -28,20 +28,20 @@ Invoking this method creates a new version of the ruleset.
2828

2929
## Example
3030

31-
The following example adds a rule to ruleset `{ruleset_id}` of zone `{zone_id}`. The ruleset ID was previously obtained using the [List zone rulesets](/api/resources/rulesets/methods/list/) operation, and corresponds to the entry point ruleset for the `http_request_firewall_custom` phase.
31+
The following `POST` request adds a rule to ruleset `$RULESET_ID` of zone `$ZONE_ID`. The ruleset ID was previously obtained using the [List zone rulesets](/api/resources/rulesets/methods/list/) operation, and corresponds to the entry point ruleset for the `http_request_firewall_custom` phase.
3232

3333
The response will include the complete ruleset after adding the rule.
3434

35-
```bash
36-
curl https://api.cloudflare.com/client/v4/zones/{zone_id}/rulesets/{ruleset_id}/rules \
37-
--header "Authorization: Bearer <API_TOKEN>" \
38-
--header "Content-Type: application/json" \
39-
--data '{
40-
"action": "js_challenge",
41-
"expression": "(ip.src.country eq \"GB\" or ip.src.country eq \"FR\") or cf.threat_score > 0",
42-
"description": "challenge GB and FR or based on IP Reputation"
43-
}'
44-
```
35+
<APIRequest
36+
path="/zones/{zone_id}/rulesets/{ruleset_id}/rules"
37+
method="POST"
38+
json={{
39+
action: "js_challenge",
40+
expression:
41+
'(ip.src.country eq "GB" or ip.src.country eq "FR") or cf.threat_score > 0',
42+
description: "challenge GB and FR or based on IP Reputation",
43+
}}
44+
/>
4545

4646
```json output
4747
{
@@ -57,7 +57,7 @@ curl https://api.cloudflare.com/client/v4/zones/{zone_id}/rulesets/{ruleset_id}/
5757
"version": "1",
5858
"action": "challenge",
5959
"expression": "not http.request.uri.path matches \"^/api/.*$\"",
60-
"last_updated": "2020-11-23T11:36:24.192361Z",
60+
"last_updated": "2023-11-23T11:36:24.192361Z",
6161
"ref": "<RULE_REF_1>",
6262
"enabled": true
6363
},
@@ -67,12 +67,12 @@ curl https://api.cloudflare.com/client/v4/zones/{zone_id}/rulesets/{ruleset_id}/
6767
"action": "js_challenge",
6868
"expression": "(ip.src.country eq \"GB\" or ip.src.country eq \"FR\") or cf.threat_score > 0",
6969
"description": "challenge GB and FR or based on IP Reputation",
70-
"last_updated": "2021-06-22T12:35:58.144683Z",
70+
"last_updated": "2024-06-22T12:35:58.144683Z",
7171
"ref": "<NEW_RULE_REF>",
7272
"enabled": true
7373
}
7474
],
75-
"last_updated": "2021-06-22T12:35:58.144683Z",
75+
"last_updated": "2024-06-22T12:35:58.144683Z",
7676
"phase": "http_request_firewall_custom"
7777
},
7878
"success": true,

‎src/content/docs/ruleset-engine/rulesets-api/create.mdx‎

Lines changed: 63 additions & 89 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ sidebar:
66
order: 5
77
---
88

9-
import { Description, Type, Render } from "~/components";
9+
import { Description, Type, Render, APIRequest } from "~/components";
1010

1111
Creates a ruleset of a given kind in the specified phase. Allows you to create phase entry point rulesets.
1212

@@ -32,35 +32,34 @@ The following parameters are required:
3232
- The kind of ruleset the JSON object represents.
3333
- Allowed values:
3434
- `custom`: Creates a custom ruleset
35-
- `root`: Creates a phase entry point ruleset at the account level
35+
- `root`: Creates a phase [entry point ruleset](/ruleset-engine/about/rulesets/#entry-point-ruleset) at the account level
3636
- `zone`: Creates a phase entry point ruleset at the zone level
3737
- `phase` <Type text="String" />
3838
- The name of the [phase](/ruleset-engine/about/phases/) where the ruleset will be created.
39-
- Check the specific Cloudflare product documentation for more information on the phases where you can create rulesets for that product.
39+
- Check the [phases list](/ruleset-engine/reference/phases-list/) or the the specific Cloudflare product documentation for more information on the phases where you can create rulesets for that product.
4040

4141
Use the `rules` parameter to supply a list of rules for the ruleset. For an object definition, refer to [Rulesets API: JSON Object](/ruleset-engine/rulesets-api/json-object/).
4242

4343
## Example - Create a custom ruleset
4444

4545
The following `POST` request creates a custom ruleset in the `http_request_firewall_custom` phase containing a single rule.
4646

47-
```bash
48-
curl https://api.cloudflare.com/client/v4/accounts/{account_id}/rulesets \
49-
--header "Authorization: Bearer <API_TOKEN>" \
50-
--header "Content-Type: application/json" \
51-
--data '{
52-
"name": "Example custom ruleset",
53-
"kind": "custom",
54-
"description": "Example ruleset description",
55-
"rules": [
56-
{
57-
"action": "log",
58-
"expression": "cf.zone.name eq \"example.com\""
59-
}
60-
],
61-
"phase": "http_request_firewall_custom"
62-
}'
63-
```
47+
<APIRequest
48+
path="/accounts/{account_id}/rulesets"
49+
method="POST"
50+
json={{
51+
name: "Example custom ruleset",
52+
kind: "custom",
53+
description: "Example ruleset description",
54+
rules: [
55+
{
56+
action: "log",
57+
expression: 'cf.zone.name eq "example.com"',
58+
},
59+
],
60+
phase: "http_request_firewall_custom",
61+
}}
62+
/>
6463

6564
```json output
6665
{
@@ -76,31 +75,10 @@ curl https://api.cloudflare.com/client/v4/accounts/{account_id}/rulesets \
7675
"version": "1",
7776
"action": "log",
7877
"expression": "cf.zone.name eq \"example.com\"",
79-
"last_updated": "2021-03-17T15:42:37.917815Z"
80-
}
81-
],
82-
"last_updated": "2021-03-17T15:42:37.917815Z",
83-
"phase": "http_request_firewall_custom"
84-
},
85-
"success": true,
86-
"errors": [],
87-
"messages": []
88-
"result": {
89-
"id": "<RULESET_ID>",
90-
"name": "Example custom ruleset",
91-
"description": "Example ruleset description",
92-
"kind": "custom",
93-
"version": "1",
94-
"rules": [
95-
{
96-
"id": "<RULE_ID>",
97-
"version": "1",
98-
"action": "log",
99-
"expression": "cf.zone.name eq \"example.com\"",
100-
"last_updated": "2021-03-17T15:42:37.917815Z"
78+
"last_updated": "2025-03-17T15:42:37.917815Z"
10179
}
10280
],
103-
"last_updated": "2021-03-17T15:42:37.917815Z",
81+
"last_updated": "2025-03-17T15:42:37.917815Z",
10482
"phase": "http_request_firewall_custom"
10583
},
10684
"success": true,
@@ -114,31 +92,28 @@ curl https://api.cloudflare.com/client/v4/accounts/{account_id}/rulesets \
11492
The following `POST` request creates a zone-level phase entry point ruleset at the `http_request_firewall_managed` phase with a single rule that executes a managed ruleset.
11593

11694
:::note
117-
118-
You do not have to use this method to create a phase entry point ruleset — Cloudflare automatically creates the entry point ruleset when you add a rule to it, if it does not exist. Refer to [Add rules to phase entry point rulesets](/ruleset-engine/basic-operations/add-rule-phase-rulesets/) for more information.
119-
95+
You do not have to use this method to create a phase entry point ruleset. Cloudflare automatically creates the entry point ruleset when you add a rule to it, if it does not exist. Refer to [Add rules to phase entry point rulesets](/ruleset-engine/basic-operations/add-rule-phase-rulesets/) for more information.
12096
:::
12197

122-
```bash
123-
curl https://api.cloudflare.com/client/v4/zones/{zone_id}/rulesets \
124-
--header "Authorization: Bearer <API_TOKEN>" \
125-
--header "Content-Type: application/json" \
126-
--data '{
127-
"name": "Zone-level phase entry point",
128-
"kind": "zone",
129-
"description": "This ruleset executes a managed ruleset.",
130-
"rules": [
131-
{
132-
"action": "execute",
133-
"expression": "true",
134-
"action_parameters": {
135-
"id": "<MANAGED_RULESET_ID>"
136-
}
137-
}
138-
],
139-
"phase": "http_request_firewall_managed"
140-
}'
141-
```
98+
<APIRequest
99+
path="/zones/{zone_id}/rulesets"
100+
method="POST"
101+
json={{
102+
name: "Zone-level phase entry point",
103+
kind: "zone",
104+
description: "This ruleset executes a managed ruleset.",
105+
rules: [
106+
{
107+
action: "execute",
108+
expression: "true",
109+
action_parameters: {
110+
id: "<MANAGED_RULESET_ID>",
111+
},
112+
},
113+
],
114+
phase: "http_request_firewall_managed",
115+
}}
116+
/>
142117

143118
```json output
144119
{
@@ -157,10 +132,10 @@ curl https://api.cloudflare.com/client/v4/zones/{zone_id}/rulesets \
157132
"action_parameters": {
158133
"id": "<MANAGED_RULESET_ID>"
159134
},
160-
"last_updated": "2021-03-17T15:42:37.917815Z"
135+
"last_updated": "2025-03-17T15:42:37.917815Z"
161136
}
162137
],
163-
"last_updated": "2021-03-17T15:42:37.917815Z",
138+
"last_updated": "2025-03-17T15:42:37.917815Z",
164139
"phase": "http_request_firewall_managed"
165140
},
166141
"success": true,
@@ -174,29 +149,28 @@ curl https://api.cloudflare.com/client/v4/zones/{zone_id}/rulesets \
174149
The following `POST` request creates an account-level phase entry point ruleset for the `http_ratelimit` phase with a single rule that executes a rate limiting ruleset for all Enterprise zones in the account.
175150

176151
:::note
177-
You do not have to use this method to create a phase entry point ruleset — Cloudflare automatically creates the entry point ruleset when you add a rule to it, if it does not exist. Refer to [Add rules to phase entry point rulesets](/ruleset-engine/basic-operations/add-rule-phase-rulesets/) for more information.
152+
You do not have to use this method to create a phase entry point ruleset. Cloudflare automatically creates the entry point ruleset when you add a rule to it, if it does not exist. Refer to [Add rules to phase entry point rulesets](/ruleset-engine/basic-operations/add-rule-phase-rulesets/) for more information.
178153
:::
179154

180-
```bash
181-
curl https://api.cloudflare.com/client/v4/accounts/{account_id}/rulesets \
182-
--header "Authorization: Bearer <API_TOKEN>" \
183-
--header "Content-Type: application/json" \
184-
--data '{
185-
"name": "Account-level phase entry point",
186-
"kind": "root",
187-
"description": "This ruleset executes a rate limiting ruleset.",
188-
"rules": [
189-
{
190-
"action": "execute",
191-
"expression": "(cf.zone.plan eq \"ENT\")",
192-
"action_parameters": {
193-
"id": "<RATE_LIMITING_RULESET_ID>"
194-
}
195-
}
196-
],
197-
"phase": "http_ratelimit"
198-
}'
199-
```
155+
<APIRequest
156+
path="/accounts/{account_id}/rulesets"
157+
method="POST"
158+
json={{
159+
name: "Account-level phase entry point",
160+
kind: "root",
161+
description: "This ruleset executes a rate limiting ruleset.",
162+
rules: [
163+
{
164+
action: "execute",
165+
expression: '(cf.zone.plan eq "ENT")',
166+
action_parameters: {
167+
id: "<RATE_LIMITING_RULESET_ID>",
168+
},
169+
},
170+
],
171+
phase: "http_ratelimit",
172+
}}
173+
/>
200174

201175
```json output
202176
{

‎src/content/docs/ruleset-engine/rulesets-api/delete-rule.mdx‎

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@ sidebar:
66
order: 9
77
---
88

9+
import { APIRequest } from "~/components";
10+
911
Deletes a single rule in a ruleset at the account or zone level.
1012

1113
Use one of the following API endpoints:
@@ -22,15 +24,17 @@ If the delete operation succeeds, the API method call returns a `200 OK` HTTP st
2224

2325
## Example
2426

25-
The following example deletes rule `{rule_id_1}` belonging to ruleset `{ruleset_id}`.
27+
The following example deletes rule `$RULE_ID_1` belonging to ruleset `$RULESET_ID`.
2628

2729
The response will include the complete ruleset after deleting the rule.
2830

29-
```bash
30-
curl --request DELETE \
31-
https://api.cloudflare.com/client/v4/accounts/{account_id}/rulesets/{ruleset_id}/rules/{rule_id_1} \
32-
--header "Authorization: Bearer <API_TOKEN>"
33-
```
31+
<APIRequest
32+
path="/accounts/{account_id}/rulesets/{ruleset_id}/rules/{rule_id}"
33+
method="DELETE"
34+
parameters={{
35+
rule_id: "$RULE_ID_1",
36+
}}
37+
/>
3438

3539
```json output
3640
{

‎src/content/docs/ruleset-engine/rulesets-api/delete.mdx‎

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@ sidebar:
66
order: 10
77
---
88

9+
import { APIRequest } from "~/components";
10+
911
You can use the API to delete all the versions of a ruleset or delete a specific version of a ruleset.
1012

1113
- [Delete ruleset (all versions)](#delete-ruleset)
@@ -37,13 +39,12 @@ To delete the ruleset, update or delete any rules that reference the ruleset and
3739

3840
### Example
3941

40-
The following example request deletes an existing ruleset.
42+
The following example request deletes an existing ruleset with ID `$RULESET_ID`.
4143

42-
```bash
43-
curl --request DELETE \
44-
https://api.cloudflare.com/client/v4/accounts/{account_id}/rulesets/{ruleset_id} \
45-
--header "Authorization: Bearer <API_TOKEN>"
46-
```
44+
<APIRequest
45+
path="/accounts/{account_id}/rulesets/{ruleset_id}"
46+
method="DELETE"
47+
/>
4748

4849
## Delete ruleset version
4950

@@ -75,8 +76,7 @@ To delete the ruleset version, update or delete any rules that reference the rul
7576

7677
The following example request deletes a version of an existing ruleset.
7778

78-
```bash
79-
curl --request DELETE \
80-
https://api.cloudflare.com/client/v4/accounts/{account_id}/rulesets/{ruleset_id}/versions/{version_number} \
81-
--header "Authorization: Bearer <API_TOKEN>"
82-
```
79+
<APIRequest
80+
path="/accounts/{account_id}/rulesets/{ruleset_id}/versions/{ruleset_version}"
81+
method="DELETE"
82+
/>

0 commit comments

Comments
 (0)