1## API Reference
2 
3**Note on Smart Shield:** Argo Smart Routing is being integrated into Cloudflare's Smart Shield product. API endpoints remain stable; existing integrations continue to work without changes.
4 
5### Base Endpoint
6```
7https://api.cloudflare.com/client/v4
8```
9 
10### Authentication
11Use API tokens with Zone:Argo Smart Routing:Edit permissions:
12 
13```bash
14# Headers required
15X-Auth-Email: [email protected]
16Authorization: Bearer YOUR_API_TOKEN
17```
18 
19### Get Argo Smart Routing Status
20 
21**Endpoint:** `GET /zones/{zone_id}/argo/smart_routing`
22 
23**Description:** Retrieves current Argo Smart Routing enablement status.
24 
25**cURL Example:**
26```bash
27curl -X GET "https://api.cloudflare.com/client/v4/zones/{zone_id}/argo/smart_routing" \
28  -H "Authorization: Bearer YOUR_API_TOKEN" \
29  -H "Content-Type: application/json"
30```
31 
32**Response:**
33```json
34{
35  "result": {
36    "id": "smart_routing",
37    "value": "on",
38    "editable": true,
39    "modified_on": "2024-01-11T12:00:00Z"
40  },
41  "success": true,
42  "errors": [],
43  "messages": []
44}
45```
46 
47**TypeScript SDK Example:**
48```typescript
49import Cloudflare from 'cloudflare';
50 
51const client = new Cloudflare({
52  apiToken: process.env.CLOUDFLARE_API_TOKEN
53});
54 
55const status = await client.argo.smartRouting.get({ zone_id: 'your-zone-id' });
56console.log(`Argo status: ${status.value}, editable: ${status.editable}`);
57```
58 
59**Python SDK Example:**
60```python
61from cloudflare import Cloudflare
62 
63client = Cloudflare(api_token=os.environ.get('CLOUDFLARE_API_TOKEN'))
64 
65status = client.argo.smart_routing.get(zone_id='your-zone-id')
66print(f"Argo status: {status.value}, editable: {status.editable}")
67```
68 
69### Update Argo Smart Routing Status
70 
71**Endpoint:** `PATCH /zones/{zone_id}/argo/smart_routing`
72 
73**Description:** Enable or disable Argo Smart Routing for a zone.
74 
75**Request Body:**
76```json
77{
78  "value": "on"  // or "off"
79}
80```
81 
82**cURL Example:**
83```bash
84curl -X PATCH "https://api.cloudflare.com/client/v4/zones/{zone_id}/argo/smart_routing" \
85  -H "Authorization: Bearer YOUR_API_TOKEN" \
86  -H "Content-Type: application/json" \
87  -d '{"value": "on"}'
88```
89 
90**TypeScript SDK Example:**
91```typescript
92const result = await client.argo.smartRouting.edit({
93  zone_id: 'your-zone-id',
94  value: 'on',
95});
96console.log(`Updated: ${result.value} at ${result.modified_on}`);
97```
98 
99**Python SDK Example:**
100```python
101result = client.argo.smart_routing.edit(
102    zone_id='your-zone-id',
103    value='on'
104)
105print(f"Updated: {result.value} at {result.modified_on}")
106```
107 
108## Checking Editability Before Updates
109 
110**Critical:** Always check the `editable` field before attempting to enable/disable Argo. When `editable: false`, the zone has restrictions (billing not configured, insufficient permissions, or plan limitations).
111 
112**Pattern:**
113```typescript
114async function safelyEnableArgo(client: Cloudflare, zoneId: string): Promise<boolean> {
115  const status = await client.argo.smartRouting.get({ zone_id: zoneId });
116  
117  if (!status.editable) {
118    console.error('Cannot modify Argo: editable=false (check billing/permissions)');
119    return false;
120  }
121  
122  if (status.value === 'on') {
123    console.log('Argo already enabled');
124    return true;
125  }
126  
127  await client.argo.smartRouting.edit({ zone_id: zoneId, value: 'on' });
128  console.log('Argo enabled successfully');
129  return true;
130}
131```
132 
133**Python Pattern:**
134```python
135def safely_enable_argo(client: Cloudflare, zone_id: str) -> bool:
136    status = client.argo.smart_routing.get(zone_id=zone_id)
137    
138    if not status.editable:
139        print('Cannot modify Argo: editable=false (check billing/permissions)')
140        return False
141    
142    if status.value == 'on':
143        print('Argo already enabled')
144        return True
145    
146    client.argo.smart_routing.edit(zone_id=zone_id, value='on')
147    print('Argo enabled successfully')
148    return True
149```
150 
151## Error Handling
152 
153The TypeScript SDK provides typed error classes for robust error handling:
154 
155```typescript
156import Cloudflare from 'cloudflare';
157import { APIError, APIConnectionError, RateLimitError } from 'cloudflare';
158 
159async function enableArgoWithErrorHandling(client: Cloudflare, zoneId: string) {
160  try {
161    const result = await client.argo.smartRouting.edit({
162      zone_id: zoneId,
163      value: 'on',
164    });
165    return result;
166  } catch (error) {
167    if (error instanceof RateLimitError) {
168      console.error('Rate limited. Retry after:', error.response?.headers.get('retry-after'));
169      // Implement exponential backoff
170    } else if (error instanceof APIError) {
171      console.error('API error:', error.status, error.message);
172      if (error.status === 403) {
173        console.error('Permission denied - check API token scopes');
174      } else if (error.status === 400) {
175        console.error('Bad request - verify zone_id and payload');
176      }
177    } else if (error instanceof APIConnectionError) {
178      console.error('Connection failed:', error.message);
179      // Retry with exponential backoff
180    } else {
181      console.error('Unexpected error:', error);
182    }
183    throw error;
184  }
185}
186```
187 
188**Python Error Handling:**
189```python
190from cloudflare import Cloudflare, APIError, RateLimitError
191 
192def enable_argo_with_error_handling(client: Cloudflare, zone_id: str):
193    try:
194        result = client.argo.smart_routing.edit(zone_id=zone_id, value='on')
195        return result
196    except RateLimitError as e:
197        print(f"Rate limited. Retry after: {e.response.headers.get('retry-after')}")
198        raise
199    except APIError as e:
200        print(f"API error: {e.status} - {e.message}")
201        if e.status == 403:
202            print('Permission denied - check API token scopes')
203        elif e.status == 400:
204            print('Bad request - verify zone_id and payload')
205        raise
206    except Exception as e:
207        print(f"Unexpected error: {e}")
208        raise
209```
210 
211## Response Schema
212 
213All Argo Smart Routing API responses follow this structure:
214 
215```typescript
216interface ArgoSmartRoutingResponse {
217  result: {
218    id: 'smart_routing';
219    value: 'on' | 'off';
220    editable: boolean;
221    modified_on: string; // ISO 8601 timestamp
222  };
223  success: boolean;
224  errors: Array<{
225    code: number;
226    message: string;
227  }>;
228  messages: Array<string>;
229}
230```
231 
232## Key Response Fields
233 
234| Field | Type | Description |
235|-------|------|-------------|
236| `value` | `"on" \| "off"` | Current enablement status |
237| `editable` | `boolean` | Whether changes are allowed (check before PATCH) |
238| `modified_on` | `string` | ISO timestamp of last modification |
239| `success` | `boolean` | Whether request succeeded |
240| `errors` | `Array` | Error details if `success: false`