1# API Reference
2 
3## SDK Setup
4 
5```typescript
6import Cloudflare from 'cloudflare';
7 
8const client = new Cloudflare({
9  apiToken: process.env.CF_API_TOKEN,
10});
11```
12 
13## Core Methods
14 
15```typescript
16// List rulesets
17await client.rulesets.list({ zone_id: 'zone_id', phase: 'http_request_firewall_managed' });
18 
19// Get ruleset
20await client.rulesets.get({ zone_id: 'zone_id', ruleset_id: 'ruleset_id' });
21 
22// Create ruleset
23await client.rulesets.create({
24  zone_id: 'zone_id',
25  kind: 'zone',
26  phase: 'http_request_firewall_custom',
27  name: 'Custom WAF Rules',
28  rules: [{ action: 'block', expression: 'cf.waf.score gt 40', enabled: true }],
29});
30 
31// Update ruleset (include rule id to keep existing, omit id for new rules)
32await client.rulesets.update({
33  zone_id: 'zone_id',
34  ruleset_id: 'ruleset_id',
35  rules: [
36    { id: 'rule_id', action: 'block', expression: 'cf.waf.score gt 40', enabled: true },
37    { action: 'challenge', expression: 'http.request.uri.path contains "/admin"', enabled: true },
38  ],
39});
40 
41// Delete ruleset
42await client.rulesets.delete({ zone_id: 'zone_id', ruleset_id: 'ruleset_id' });
43```
44 
45## Actions & Phases
46 
47### Actions by Phase
48 
49| Action | Custom | Managed | Rate Limit | Description |
50|--------|--------|---------|------------|-------------|
51| `block` | ✅ | ❌ | ✅ | Block request with 403 |
52| `challenge` | ✅ | ❌ | ✅ | Show CAPTCHA challenge |
53| `js_challenge` | ✅ | ❌ | ✅ | JS-based challenge |
54| `managed_challenge` | ✅ | ❌ | ✅ | Smart challenge (recommended) |
55| `log` | ✅ | ❌ | ✅ | Log only, don't block |
56| `skip` | ✅ | ❌ | ❌ | Skip rule evaluation |
57| `execute` | ❌ | ✅ | ❌ | Deploy managed ruleset |
58 
59### Phases (Execution Order)
60 
611. `http_request_firewall_custom` - Custom rules (first line of defense)
622. `http_request_firewall_managed` - Managed rulesets (pre-configured protection)
633. `http_ratelimit` - Rate limiting (request throttling)
644. `http_request_sbfm` - Super Bot Fight Mode (Pro+ only)
65 
66## Expression Syntax
67 
68### Fields
69 
70```typescript
71// Request properties
72http.request.method          // GET, POST, etc.
73http.request.uri.path        // /api/users
74http.host                    // example.com
75 
76// IP and Geolocation
77ip.src                       // 192.0.2.1
78ip.geoip.country            // US, GB, etc.
79ip.geoip.continent          // NA, EU, etc.
80 
81// Attack detection
82cf.waf.score                 // 0-100 attack score
83cf.waf.score.sqli           // SQL injection score
84cf.waf.score.xss            // XSS score
85 
86// Headers & Cookies
87http.request.headers["authorization"][0]
88http.request.cookies["session"][0]
89lower(http.user_agent)      // Lowercase user agent
90```
91 
92### Operators
93 
94```typescript
95// Comparison
96eq      // Equal
97ne      // Not equal
98lt      // Less than
99le      // Less than or equal
100gt      // Greater than
101ge      // Greater than or equal
102 
103// String matching
104contains        // Substring match
105matches         // Regex match (use carefully)
106starts_with     // Prefix match
107ends_with       // Suffix match
108 
109// List operations
110in              // Value in list
111not             // Logical NOT
112and             // Logical AND
113or              // Logical OR
114```
115 
116### Expression Examples
117 
118```typescript
119'cf.waf.score gt 40' // Attack score
120'http.request.uri.path eq "/api/login" and http.request.method eq "POST"' // Path + method
121'ip.src in {192.0.2.0/24 203.0.113.0/24}' // IP blocking
122'ip.geoip.country in {"CN" "RU" "KP"}' // Country blocking
123'http.user_agent contains "bot"' // User agent
124'not http.request.headers["authorization"][0]' // Header check
125'(cf.waf.score.sqli gt 20 or cf.waf.score.xss gt 20) and http.request.uri.path starts_with "/api"' // Complex
126```
127 
128## Rate Limiting Configuration
129 
130```typescript
131{
132  action: 'block',
133  expression: 'http.request.uri.path starts_with "/api"',
134  action_parameters: {
135    ratelimit: {
136      // Characteristics define uniqueness: 'ip.src', 'cf.colo.id', 
137      // 'http.request.headers["key"][0]', 'http.request.cookies["session"][0]'
138      characteristics: ['cf.colo.id', 'ip.src'], // Recommended: per-IP per-datacenter
139      period: 60,                      // Time window in seconds
140      requests_per_period: 100,        // Max requests in period
141      mitigation_timeout: 600,         // Block duration in seconds
142      counting_expression: 'http.request.method ne "GET"', // Optional: filter counted requests
143      requests_to_origin: false,       // Count all requests (not just origin hits)
144    },
145  },
146  enabled: true,
147}
148```
149 
150## Managed Ruleset Deployment
151 
152```typescript
153{
154  action: 'execute',
155  action_parameters: {
156    id: 'efb7b8c949ac4650a09736fc376e9aee', // Cloudflare Managed
157    overrides: {
158      // Override specific rules
159      rules: [
160        { id: '5de7edfa648c4d6891dc3e7f84534ffa', action: 'log', enabled: true },
161      ],
162      // Override categories: 'wordpress', 'sqli', 'xss', 'rce', etc.
163      categories: [
164        { category: 'wordpress', enabled: false },
165        { category: 'sqli', action: 'log' },
166      ],
167    },
168  },
169  expression: 'true',
170  enabled: true,
171}
172```
173 
174## Skip Rules
175 
176Skip rules bypass subsequent rule evaluation. Two skip types:
177 
178**Skip current ruleset**: Skip remaining rules in current phase only
179```typescript
180{
181  action: 'skip',
182  action_parameters: {
183    ruleset: 'current', // Skip rest of current ruleset
184  },
185  expression: 'http.request.uri.path ends_with ".jpg" or http.request.uri.path ends_with ".css"',
186  enabled: true,
187}
188```
189 
190**Skip entire phases**: Skip one or more phases completely
191```typescript
192{
193  action: 'skip',
194  action_parameters: {
195    phases: ['http_request_firewall_managed', 'http_ratelimit'], // Skip multiple phases
196  },
197  expression: 'ip.src in {192.0.2.0/24 203.0.113.0/24}',
198  enabled: true,
199}
200```
201 
202**Note**: Skip rules in custom phase can skip managed/ratelimit phases, but not vice versa (execution order).