1# DDoS API
2 
3## Endpoints
4 
5### HTTP DDoS (L7)
6 
7```typescript
8// Zone-level
9PUT /zones/{zoneId}/rulesets/phases/ddos_l7/entrypoint
10GET /zones/{zoneId}/rulesets/phases/ddos_l7/entrypoint
11 
12// Account-level (Enterprise Advanced)
13PUT /accounts/{accountId}/rulesets/phases/ddos_l7/entrypoint
14GET /accounts/{accountId}/rulesets/phases/ddos_l7/entrypoint
15```
16 
17### Network DDoS (L3/4)
18 
19```typescript
20// Account-level only
21PUT /accounts/{accountId}/rulesets/phases/ddos_l4/entrypoint
22GET /accounts/{accountId}/rulesets/phases/ddos_l4/entrypoint
23```
24 
25## TypeScript SDK
26 
27**SDK Version**: Requires `cloudflare` >= 3.0.0 for ruleset phase methods.
28 
29```typescript
30import Cloudflare from "cloudflare";
31 
32const client = new Cloudflare({ apiToken: process.env.CLOUDFLARE_API_TOKEN });
33 
34// STEP 1: Discover managed ruleset ID (required for overrides)
35const allRulesets = await client.rulesets.list({ zone_id: zoneId });
36const ddosRuleset = allRulesets.result.find(
37  (r) => r.kind === "managed" && r.phase === "ddos_l7"
38);
39if (!ddosRuleset) throw new Error("DDoS managed ruleset not found");
40const managedRulesetId = ddosRuleset.id;
41 
42// STEP 2: Get current HTTP DDoS configuration
43const entrypointRuleset = await client.zones.rulesets.phases.entrypoint.get("ddos_l7", {
44  zone_id: zoneId,
45});
46 
47// STEP 3: Update HTTP DDoS ruleset with overrides
48await client.zones.rulesets.phases.entrypoint.update("ddos_l7", {
49  zone_id: zoneId,
50  rules: [
51    {
52      action: "execute",
53      expression: "true",
54      action_parameters: {
55        id: managedRulesetId, // From discovery step
56        overrides: {
57          sensitivity_level: "medium",
58          action: "managed_challenge",
59        },
60      },
61    },
62  ],
63});
64 
65// Network DDoS (account level, L3/4)
66const l4Rulesets = await client.rulesets.list({ account_id: accountId });
67const l4DdosRuleset = l4Rulesets.result.find(
68  (r) => r.kind === "managed" && r.phase === "ddos_l4"
69);
70const l4Ruleset = await client.accounts.rulesets.phases.entrypoint.get("ddos_l4", {
71  account_id: accountId,
72});
73```
74 
75## Alert Configuration
76 
77```typescript
78interface DDoSAlertConfig {
79  name: string;
80  enabled: boolean;
81  alert_type: "http_ddos_attack_alert" | "layer_3_4_ddos_attack_alert" 
82    | "advanced_http_ddos_attack_alert" | "advanced_layer_3_4_ddos_attack_alert";
83  filters?: {
84    zones?: string[];
85    hostnames?: string[];
86    requests_per_second?: number;
87    packets_per_second?: number;
88    megabits_per_second?: number;
89    ip_prefixes?: string[]; // CIDR
90    ip_addresses?: string[];
91    protocols?: string[];
92  };
93  mechanisms: {
94    email?: Array<{ id: string }>;
95    webhooks?: Array<{ id: string }>;
96    pagerduty?: Array<{ id: string }>;
97  };
98}
99 
100// Create alert
101await fetch(
102  `https://api.cloudflare.com/client/v4/accounts/${accountId}/alerting/v3/policies`,
103  {
104    method: "POST",
105    headers: {
106      Authorization: `Bearer ${apiToken}`,
107      "Content-Type": "application/json",
108    },
109    body: JSON.stringify(alertConfig),
110  }
111);
112```
113 
114## Typed Override Examples
115 
116```typescript
117// Override by category
118interface CategoryOverride {
119  action: "execute";
120  expression: string;
121  action_parameters: {
122    id: string;
123    overrides: {
124      categories?: Array<{
125        category: "http-flood" | "http-anomaly" | "udp-flood" | "syn-flood";
126        sensitivity_level?: "default" | "medium" | "low" | "eoff";
127        action?: "block" | "managed_challenge" | "challenge" | "log";
128      }>;
129    };
130  };
131}
132 
133// Override by rule ID
134interface RuleOverride {
135  action: "execute";
136  expression: string;
137  action_parameters: {
138    id: string;
139    overrides: {
140      rules?: Array<{
141        id: string;
142        action?: "block" | "managed_challenge" | "challenge" | "log";
143        sensitivity_level?: "default" | "medium" | "low" | "eoff";
144      }>;
145    };
146  };
147}
148 
149// Example: Override specific adaptive rule
150const adaptiveOverride: RuleOverride = {
151  action: "execute",
152  expression: "true",
153  action_parameters: {
154    id: managedRulesetId,
155    overrides: {
156      rules: [
157        { id: "...adaptive-origins-rule-id...", sensitivity_level: "low" },
158      ],
159    },
160  },
161};
162```
163 
164See [patterns.md](./patterns.md) for complete implementation patterns.
165