1# API Operations
2 
3## Deploy User Worker
4 
5```bash
6curl -X PUT \
7  "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/workers/dispatch/namespaces/$NAMESPACE/scripts/$SCRIPT_NAME" \
8  -H "Authorization: Bearer $API_TOKEN" \
9  -F 'metadata={"main_module": "worker.mjs"};type=application/json' \
10  -F '[email protected];type=application/javascript+module'
11```
12 
13### TypeScript SDK
14```typescript
15import Cloudflare from "cloudflare";
16 
17const client = new Cloudflare({ apiToken: process.env.API_TOKEN });
18 
19const scriptFile = new File([scriptContent], `${scriptName}.mjs`, {
20  type: "application/javascript+module",
21});
22 
23await client.workersForPlatforms.dispatch.namespaces.scripts.update(
24  namespace, scriptName,
25  {
26    account_id: accountId,
27    metadata: { main_module: `${scriptName}.mjs` },
28    files: [scriptFile],
29  }
30);
31```
32 
33## TypeScript Types
34 
35```typescript
36import type { DispatchNamespace } from '@cloudflare/workers-types';
37 
38interface DispatchNamespace {
39  get(name: string, options?: Record<string, unknown>, dispatchOptions?: DynamicDispatchOptions): Fetcher;
40}
41 
42interface DynamicDispatchOptions {
43  limits?: DynamicDispatchLimits;
44  outbound?: Record<string, unknown>;
45}
46 
47interface DynamicDispatchLimits {
48  cpuMs?: number;        // Max CPU milliseconds
49  subRequests?: number;  // Max fetch() calls
50}
51 
52// Usage
53const userWorker = env.DISPATCHER.get('customer-123', {}, {
54  limits: { cpuMs: 50, subRequests: 20 },
55  outbound: { customerId: '123', url: request.url }
56});
57```
58 
59## Deploy with Bindings
60```bash
61curl -X PUT ".../scripts/$SCRIPT_NAME" \
62  -F 'metadata={
63    "main_module": "worker.mjs",
64    "bindings": [
65      {"type": "kv_namespace", "name": "MY_KV", "namespace_id": "'$KV_ID'"}
66    ],
67    "tags": ["customer-123", "production"],
68    "compatibility_date": "2026-01-01"  // Use current date for new projects
69  };type=application/json' \
70  -F '[email protected];type=application/javascript+module'
71```
72 
73## List/Delete Workers
74 
75```bash
76# List
77curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/workers/dispatch/namespaces/$NAMESPACE/scripts" \
78  -H "Authorization: Bearer $API_TOKEN"
79 
80# Delete by name
81curl -X DELETE ".../scripts/$SCRIPT_NAME" -H "Authorization: Bearer $API_TOKEN"
82 
83# Delete by tag
84curl -X DELETE ".../scripts?tags=customer-123%3Ayes" -H "Authorization: Bearer $API_TOKEN"
85```
86 
87**Pagination:** SDK supports async iteration. Manual: add `?per_page=100&page=1` query params.
88 
89## Static Assets
90 
91**3-step process:** Create session → Upload files → Deploy Worker
92 
93### 1. Create Upload Session
94```bash
95curl -X POST ".../scripts/$SCRIPT_NAME/assets-upload-session" \
96  -H "Authorization: Bearer $API_TOKEN" \
97  -d '{
98    "manifest": {
99      "/index.html": {"hash": "08f1dfda4574284ab3c21666d1ee8c7d4", "size": 1234}
100    }
101  }'
102# Returns: jwt, buckets
103```
104 
105**Hash:** SHA-256 truncated to first 16 bytes (32 hex characters)
106 
107### 2. Upload Files
108```bash
109curl -X POST ".../workers/assets/upload?base64=true" \
110  -H "Authorization: Bearer $UPLOAD_JWT" \
111  -F '08f1dfda4574284ab3c21666d1ee8c7d4=<BASE64_CONTENT>'
112# Returns: completion jwt
113```
114 
115**Multiple buckets:** Upload to all returned bucket URLs (typically 2 for redundancy) using same JWT and hash.
116 
117### 3. Deploy with Assets
118```bash
119curl -X PUT ".../scripts/$SCRIPT_NAME" \
120  -F 'metadata={
121    "main_module": "index.js",
122    "assets": {"jwt": "<COMPLETION_TOKEN>"},
123    "bindings": [{"type": "assets", "name": "ASSETS"}]
124  };type=application/json' \
125  -F 'index.js=export default {...};type=application/javascript+module'
126```
127 
128**Asset Isolation:** Assets shared across namespace by default. For customer isolation, salt hash: `sha256(customerId + fileContents).slice(0, 32)`
129 
130## Dispatch Workers
131 
132### Subdomain Routing
133```typescript
134export default {
135  async fetch(request: Request, env: Env): Promise<Response> {
136    const userWorkerName = new URL(request.url).hostname.split(".")[0];
137    const userWorker = env.DISPATCHER.get(userWorkerName);
138    return await userWorker.fetch(request);
139  },
140};
141```
142 
143### Path Routing
144```typescript
145const pathParts = new URL(request.url).pathname.split("/").filter(Boolean);
146const userWorker = env.DISPATCHER.get(pathParts[0]);
147return await userWorker.fetch(request);
148```
149 
150### KV Routing
151```typescript
152const hostname = new URL(request.url).hostname;
153const userWorkerName = await env.ROUTING_KV.get(hostname);
154const userWorker = env.DISPATCHER.get(userWorkerName);
155return await userWorker.fetch(request);
156```
157 
158## Outbound Workers
159 
160Control external fetch from user Workers:
161 
162### Configure
163```typescript
164const userWorker = env.DISPATCHER.get(
165  workerName, {},
166  { outbound: { customer_context: { customer_name: workerName, url: request.url } } }
167);
168```
169 
170### Implement
171```typescript
172export default {
173  async fetch(request: Request, env: Env): Promise<Response> {
174    const customerName = env.customer_name;
175    const url = new URL(request.url);
176    
177    // Block domains
178    if (["malicious.com"].some(d => url.hostname.includes(d))) {
179      return new Response("Blocked", { status: 403 });
180    }
181    
182    // Inject auth
183    if (url.hostname === "api.example.com") {
184      const headers = new Headers(request.headers);
185      headers.set("Authorization", `Bearer ${generateJWT(customerName)}`);
186      return fetch(new Request(request, { headers }));
187    }
188    
189    return fetch(request);
190  },
191};
192```
193 
194**Note:** Doesn't intercept DO/mTLS fetch.
195 
196See [README.md](./README.md), [configuration.md](./configuration.md), [patterns.md](./patterns.md), [gotchas.md](./gotchas.md)
197