references/ddos/api.md

# DDoS API

## Endpoints

### HTTP DDoS (L7)

```typescript
// Zone-level
PUT /zones/{zoneId}/rulesets/phases/ddos_l7/entrypoint
GET /zones/{zoneId}/rulesets/phases/ddos_l7/entrypoint

// Account-level (Enterprise Advanced)
PUT /accounts/{accountId}/rulesets/phases/ddos_l7/entrypoint
GET /accounts/{accountId}/rulesets/phases/ddos_l7/entrypoint
```

### Network DDoS (L3/4)

```typescript
// Account-level only
PUT /accounts/{accountId}/rulesets/phases/ddos_l4/entrypoint
GET /accounts/{accountId}/rulesets/phases/ddos_l4/entrypoint
```

## TypeScript SDK

**SDK Version**: Requires `cloudflare` >= 3.0.0 for ruleset phase methods.

```typescript
import Cloudflare from "cloudflare";

const client = new Cloudflare({ apiToken: process.env.CLOUDFLARE_API_TOKEN });

// STEP 1: Discover managed ruleset ID (required for overrides)
const allRulesets = await client.rulesets.list({ zone_id: zoneId });
const ddosRuleset = allRulesets.result.find(
  (r) => r.kind === "managed" && r.phase === "ddos_l7"
);
if (!ddosRuleset) throw new Error("DDoS managed ruleset not found");
const managedRulesetId = ddosRuleset.id;

// STEP 2: Get current HTTP DDoS configuration
const entrypointRuleset = await client.zones.rulesets.phases.entrypoint.get("ddos_l7", {
  zone_id: zoneId,
});

// STEP 3: Update HTTP DDoS ruleset with overrides
await client.zones.rulesets.phases.entrypoint.update("ddos_l7", {
  zone_id: zoneId,
  rules: [
    {
      action: "execute",
      expression: "true",
      action_parameters: {
        id: managedRulesetId, // From discovery step
        overrides: {
          sensitivity_level: "medium",
          action: "managed_challenge",
        },
      },
    },
  ],
});

// Network DDoS (account level, L3/4)
const l4Rulesets = await client.rulesets.list({ account_id: accountId });
const l4DdosRuleset = l4Rulesets.result.find(
  (r) => r.kind === "managed" && r.phase === "ddos_l4"
);
const l4Ruleset = await client.accounts.rulesets.phases.entrypoint.get("ddos_l4", {
  account_id: accountId,
});
```

## Alert Configuration

```typescript
interface DDoSAlertConfig {
  name: string;
  enabled: boolean;
  alert_type: "http_ddos_attack_alert" | "layer_3_4_ddos_attack_alert" 
    | "advanced_http_ddos_attack_alert" | "advanced_layer_3_4_ddos_attack_alert";
  filters?: {
    zones?: string[];
    hostnames?: string[];
    requests_per_second?: number;
    packets_per_second?: number;
    megabits_per_second?: number;
    ip_prefixes?: string[]; // CIDR
    ip_addresses?: string[];
    protocols?: string[];
  };
  mechanisms: {
    email?: Array<{ id: string }>;
    webhooks?: Array<{ id: string }>;
    pagerduty?: Array<{ id: string }>;
  };
}

// Create alert
await fetch(
  `https://api.cloudflare.com/client/v4/accounts/${accountId}/alerting/v3/policies`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(alertConfig),
  }
);
```

## Typed Override Examples

```typescript
// Override by category
interface CategoryOverride {
  action: "execute";
  expression: string;
  action_parameters: {
    id: string;
    overrides: {
      categories?: Array<{
        category: "http-flood" | "http-anomaly" | "udp-flood" | "syn-flood";
        sensitivity_level?: "default" | "medium" | "low" | "eoff";
        action?: "block" | "managed_challenge" | "challenge" | "log";
      }>;
    };
  };
}

// Override by rule ID
interface RuleOverride {
  action: "execute";
  expression: string;
  action_parameters: {
    id: string;
    overrides: {
      rules?: Array<{
        id: string;
        action?: "block" | "managed_challenge" | "challenge" | "log";
        sensitivity_level?: "default" | "medium" | "low" | "eoff";
      }>;
    };
  };
}

// Example: Override specific adaptive rule
const adaptiveOverride: RuleOverride = {
  action: "execute",
  expression: "true",
  action_parameters: {
    id: managedRulesetId,
    overrides: {
      rules: [
        { id: "...adaptive-origins-rule-id...", sensitivity_level: "low" },
      ],
    },
  },
};
```

See [patterns.md](./patterns.md) for complete implementation patterns.