1# API Reference
2 
3## Client Initialization
4 
5### TypeScript
6 
7```typescript
8import Cloudflare from 'cloudflare';
9 
10const client = new Cloudflare({
11  apiToken: process.env.CLOUDFLARE_API_TOKEN,
12});
13```
14 
15### Python
16 
17```python
18from cloudflare import Cloudflare
19 
20client = Cloudflare(api_token=os.environ.get("CLOUDFLARE_API_TOKEN"))
21 
22# For async:
23from cloudflare import AsyncCloudflare
24client = AsyncCloudflare(api_token=os.environ["CLOUDFLARE_API_TOKEN"])
25```
26 
27### Go
28 
29```go
30import (
31    "github.com/cloudflare/cloudflare-go/v4"
32    "github.com/cloudflare/cloudflare-go/v4/option"
33)
34 
35client := cloudflare.NewClient(
36    option.WithAPIToken(os.Getenv("CLOUDFLARE_API_TOKEN")),
37)
38```
39 
40## Authentication
41 
42### API Token (Recommended)
43 
44**Create token**: Dashboard → My Profile → API Tokens → Create Token
45 
46```bash
47export CLOUDFLARE_API_TOKEN='your-token-here'
48 
49curl "https://api.cloudflare.com/client/v4/zones" \
50  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
51```
52 
53**Token scopes**: Always use minimal permissions (zone-specific, time-limited).
54 
55### API Key (Legacy)
56 
57```bash
58curl "https://api.cloudflare.com/client/v4/zones" \
59  --header "X-Auth-Email: [email protected]" \
60  --header "X-Auth-Key: $CLOUDFLARE_API_KEY"
61```
62 
63**Not recommended:** Full account access, cannot scope permissions.
64 
65## Auto-Pagination
66 
67All SDKs support automatic pagination for list operations.
68 
69```typescript
70// TypeScript: for await...of
71for await (const zone of client.zones.list()) {
72  console.log(zone.id);
73}
74```
75 
76```python
77# Python: iterator protocol
78for zone in client.zones.list():
79    print(zone.id)
80```
81 
82```go
83// Go: ListAutoPaging
84iter := client.Zones.ListAutoPaging(ctx, cloudflare.ZoneListParams{})
85for iter.Next() {
86    zone := iter.Current()
87    fmt.Println(zone.ID)
88}
89```
90 
91## Error Handling
92 
93```typescript
94try {
95  const zone = await client.zones.get({ zone_id: 'xxx' });
96} catch (err) {
97  if (err instanceof Cloudflare.NotFoundError) {
98    // 404
99  } else if (err instanceof Cloudflare.RateLimitError) {
100    // 429 - SDK auto-retries with backoff
101  } else if (err instanceof Cloudflare.APIError) {
102    console.log(err.status, err.message);
103  }
104}
105```
106 
107**Common Error Types:**
108- `AuthenticationError` (401) - Invalid token
109- `PermissionDeniedError` (403) - Insufficient scope
110- `NotFoundError` (404) - Resource not found
111- `RateLimitError` (429) - Rate limit exceeded
112- `InternalServerError` (≥500) - Cloudflare error
113 
114## Zone Management
115 
116```typescript
117// List zones
118const zones = await client.zones.list({
119  account: { id: 'account-id' },
120  status: 'active',
121});
122 
123// Create zone
124const zone = await client.zones.create({
125  account: { id: 'account-id' },
126  name: 'example.com',
127  type: 'full', // or 'partial'
128});
129 
130// Update zone
131await client.zones.edit('zone-id', {
132  paused: false,
133});
134 
135// Delete zone
136await client.zones.delete('zone-id');
137```
138 
139```go
140// Go: requires cloudflare.F() wrapper
141zone, err := client.Zones.New(ctx, cloudflare.ZoneNewParams{
142    Account: cloudflare.F(cloudflare.ZoneNewParamsAccount{
143        ID: cloudflare.F("account-id"),
144    }),
145    Name: cloudflare.F("example.com"),
146    Type: cloudflare.F(cloudflare.ZoneNewParamsTypeFull),
147})
148```
149 
150## DNS Management
151 
152```typescript
153// Create DNS record
154await client.dns.records.create({
155  zone_id: 'zone-id',
156  type: 'A',
157  name: 'subdomain.example.com',
158  content: '192.0.2.1',
159  ttl: 1, // auto
160  proxied: true, // Orange cloud
161});
162 
163// List DNS records (with auto-pagination)
164for await (const record of client.dns.records.list({
165  zone_id: 'zone-id',
166  type: 'A',
167})) {
168  console.log(record.name, record.content);
169}
170 
171// Update DNS record
172await client.dns.records.update({
173  zone_id: 'zone-id',
174  dns_record_id: 'record-id',
175  type: 'A',
176  name: 'subdomain.example.com',
177  content: '203.0.113.1',
178  proxied: true,
179});
180 
181// Delete DNS record
182await client.dns.records.delete({
183  zone_id: 'zone-id',
184  dns_record_id: 'record-id',
185});
186```
187 
188```python
189# Python example
190client.dns.records.create(
191    zone_id="zone-id",
192    type="A",
193    name="subdomain.example.com",
194    content="192.0.2.1",
195    ttl=1,
196    proxied=True,
197)
198```
199 
200## See Also
201 
202- [configuration.md](./configuration.md) - SDK configuration, environment variables
203- [patterns.md](./patterns.md) - Real-world patterns and workflows
204- [gotchas.md](./gotchas.md) - Rate limits, troubleshooting
205