cloudflare

---
name: cloudflare
description: Cloudflare API for DNS and zone management. Use when user mentions "Cloudflare",
  "DNS record", "zone", or "CDN settings".
---

## Troubleshooting

If requests fail, run `zero doctor check-connector --env-name CLOUDFLARE_TOKEN` or `zero doctor check-connector --url https://api.cloudflare.com/client/v4/user/tokens/verify --method GET`

## How to Use

### Base URL

All API requests use: `https://api.cloudflare.com/client/v4`

### 1. Verify Token

```bash
curl -s "https://api.cloudflare.com/client/v4/user/tokens/verify" --header "Authorization: Bearer $CLOUDFLARE_TOKEN" | jq .
```

### 2. List Zones

```bash
curl -s "https://api.cloudflare.com/client/v4/zones" --header "Authorization: Bearer $CLOUDFLARE_TOKEN" | jq .
```

### 3. Get Zone Details

```bash
curl -s "https://api.cloudflare.com/client/v4/zones/$CLOUDFLARE_ZONE_ID" --header "Authorization: Bearer $CLOUDFLARE_TOKEN" | jq .
```

### 4. List DNS Records

```bash
curl -s "https://api.cloudflare.com/client/v4/zones/$CLOUDFLARE_ZONE_ID/dns_records" --header "Authorization: Bearer $CLOUDFLARE_TOKEN" | jq .
```

### 5. Create DNS Record

Write to `/tmp/cloudflare_request.json`:

```json
{
  "type": "A",
  "name": "sub.example.com",
  "content": "1.2.3.4",
  "ttl": 3600,
  "proxied": false
}
```

Then run:

```bash
curl -s -X POST "https://api.cloudflare.com/client/v4/zones/$CLOUDFLARE_ZONE_ID/dns_records" --header "Authorization: Bearer $CLOUDFLARE_TOKEN" --header "Content-Type: application/json" -d @/tmp/cloudflare_request.json | jq .
```

### 6. Update DNS Record

Write to `/tmp/cloudflare_request.json`:

```json
{
  "type": "A",
  "name": "sub.example.com",
  "content": "5.6.7.8",
  "ttl": 3600,
  "proxied": true
}
```

Then run:

```bash
curl -s -X PUT "https://api.cloudflare.com/client/v4/zones/$CLOUDFLARE_ZONE_ID/dns_records/RECORD_ID" --header "Authorization: Bearer $CLOUDFLARE_TOKEN" --header "Content-Type: application/json" -d @/tmp/cloudflare_request.json | jq .
```

### 7. Delete DNS Record

```bash
curl -s -X DELETE "https://api.cloudflare.com/client/v4/zones/$CLOUDFLARE_ZONE_ID/dns_records/RECORD_ID" --header "Authorization: Bearer $CLOUDFLARE_TOKEN" | jq .
```

### 8. List Workers Scripts

```bash
curl -s "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/workers/scripts" --header "Authorization: Bearer $CLOUDFLARE_TOKEN" | jq .
```

### 9. List KV Namespaces

```bash
curl -s "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/storage/kv/namespaces" --header "Authorization: Bearer $CLOUDFLARE_TOKEN" | jq .
```

### 10. List R2 Buckets

```bash
curl -s "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/r2/buckets" --header "Authorization: Bearer $CLOUDFLARE_TOKEN" | jq .
```

### 11. Purge Zone Cache

Write to `/tmp/cloudflare_request.json`:

```json
{
  "purge_everything": true
}
```

Then run:

```bash
curl -s -X POST "https://api.cloudflare.com/client/v4/zones/$CLOUDFLARE_ZONE_ID/purge_cache" --header "Authorization: Bearer $CLOUDFLARE_TOKEN" --header "Content-Type: application/json" -d @/tmp/cloudflare_request.json | jq .
```

### 12. List Firewall Rules

```bash
curl -s "https://api.cloudflare.com/client/v4/zones/$CLOUDFLARE_ZONE_ID/firewall/rules" --header "Authorization: Bearer $CLOUDFLARE_TOKEN" | jq .
```

### 13. Get Zone Analytics

```bash
curl -s "https://api.cloudflare.com/client/v4/zones/$CLOUDFLARE_ZONE_ID/analytics/dashboard?since=-1440&continuous=true" --header "Authorization: Bearer $CLOUDFLARE_TOKEN" | jq .
```

## Common DNS Record Types

| Type | Purpose | Example Content |
|------|---------|-----------------|
| **A** | IPv4 address | `1.2.3.4` |
| **AAAA** | IPv6 address | `2001:db8::1` |
| **CNAME** | Alias to another domain | `example.com` |
| **MX** | Mail server | `mail.example.com` (with priority) |
| **TXT** | Text record (SPF, DKIM, etc.) | `v=spf1 include:_spf.google.com ~all` |
| **NS** | Name server | `ns1.example.com` |
| **SRV** | Service locator | Service-specific format |

## Guidelines

1. **Use API Tokens over Global API Key**: API tokens provide scoped, least-privilege access and are the recommended authentication method
2. **Pagination**: List endpoints return paginated results (default 20-100 per page). Use `page` and `per_page` query parameters to iterate
3. **Response Structure**: All responses include `success`, `errors`, `messages`, and `result` fields. Always check `success` before using `result`
4. **Proxied Records**: Setting `proxied: true` routes traffic through Cloudflare CDN and enables security features. Not all record types support proxying
5. **Zone ID vs Domain Name**: Most API endpoints require the Zone ID (a 32-character hex string), not the domain name
6. **Account ID**: Workers, R2, KV, and other account-level resources require the Account ID instead of Zone ID
7. **Rate Limits**: Cloudflare API has rate limits per token. Monitor response headers and implement backoff if you receive 429 responses