Changelog

The latest release of the Agents SDK ↗ brings readonly connections, MCP protocol and security improvements, x402 payment protocol v2 migration, and the ability to customize OAuth for MCP server connections.

Agents can now restrict WebSocket clients to read-only access, preventing them from modifying agent state. This is useful for dashboards, spectator views, or any scenario where clients should observe but not mutate.

New hooks: shouldConnectionBeReadonly, setConnectionReadonly, isConnectionReadonly. Readonly connections block both client-side setState() and mutating @callable() methods, and the readonly flag survives hibernation.

class MyAgent extends Agent {
	shouldConnectionBeReadonly(connection) {
		// Make spectators readonly
		return connection.url.includes("spectator");
	}
}

class MyAgent extends Agent {
	shouldConnectionBeReadonly(connection) {
		// Make spectators readonly
		return connection.url.includes("spectator");
	}
}

The new createMcpOAuthProvider method on the Agent class allows subclasses to override the default OAuth provider used when connecting to MCP servers. This enables custom authentication strategies such as pre-registered client credentials or mTLS, beyond the built-in dynamic client registration.

class MyAgent extends Agent {
	createMcpOAuthProvider(callbackUrl) {
		return new MyCustomOAuthProvider(this.ctx.storage, this.name, callbackUrl);
	}
}

class MyAgent extends Agent {
	createMcpOAuthProvider(callbackUrl: string): AgentMcpOAuthProvider {
		return new MyCustomOAuthProvider(this.ctx.storage, this.name, callbackUrl);
	}
}

Upgraded the MCP SDK to 1.26.0 to prevent cross-client response leakage. Stateless MCP Servers should now create a new McpServer instance per request instead of sharing a single instance. A guard is added in this version of the MCP SDK which will prevent connection to a Server instance that has already been connected to a transport. Developers will need to modify their code if they declare their McpServer instance as a global variable.

Added callbackPath option to addMcpServer to prevent instance name leakage in MCP OAuth callback URLs. When sendIdentityOnConnect is false, callbackPath is now required — the default callback URL would expose the instance name, undermining the security intent. Also fixes callback request detection to match via the state parameter instead of a loose /callback URL substring check, enabling custom callback paths.

onStateChanged is a drop-in rename of onStateUpdate (same signature, same behavior). onStateUpdate still works but emits a one-time console warning per class. validateStateChange rejections now propagate a CF_AGENT_STATE_ERROR message back to the client.

Migrated the x402 MCP payment integration from the legacy x402 package to @x402/core and @x402/evm v2.

Breaking changes for x402 users:

• Peer dependencies changed: replace x402 with @x402/core and @x402/evm
• PaymentRequirements type now uses v2 fields (e.g. amount instead of maxAmountRequired)
• X402ClientConfig.account type changed from viem.Account to ClientEvmSigner (structurally compatible with privateKeyToAccount())

npm uninstall x402
npm install @x402/core @x402/evm

Network identifiers now accept both legacy names and CAIP-2 format:

// Legacy name (auto-converted)
{
	network: "base-sepolia",
}

// CAIP-2 format (preferred)
{
	network: "eip155:84532",
}

Other x402 changes:

• X402ClientConfig.network is now optional — the client auto-selects from available payment requirements
• Server-side lazy initialization: facilitator connection is deferred until the first paid tool invocation
• Payment tokens support both v2 (PAYMENT-SIGNATURE) and v1 (X-PAYMENT) HTTP headers
• Added normalizeNetwork export for converting legacy network names to CAIP-2 format
• Re-exports PaymentRequirements, PaymentRequired, Network, FacilitatorConfig, and ClientEvmSigner from agents/x402

• Fix useAgent and AgentClient crashing when using basePath routing
• CORS handling delegated to partyserver's native support (simpler, more reliable)
• Client-side onStateUpdateError callback for handling rejected state updates

To update to the latest version:

npm i agents@latest

The Sandbox SDK ↗ now supports PTY (pseudo-terminal) passthrough, enabling browser-based terminal UIs to connect to sandbox shells via WebSocket.

The new terminal() method proxies a WebSocket upgrade to the container's PTY endpoint, with output buffering for replay on reconnect.

// Worker: proxy WebSocket to container terminal
return sandbox.terminal(request, { cols: 80, rows: 24 });

// Worker: proxy WebSocket to container terminal
return sandbox.terminal(request, { cols: 80, rows: 24 });

Each session can have its own terminal with an isolated working directory and environment, so users can run separate shells side-by-side in the same container.

// Multiple isolated terminals in the same sandbox
const dev = await sandbox.getSession("dev");
return dev.terminal(request);

// Multiple isolated terminals in the same sandbox
const dev = await sandbox.getSession("dev");
return dev.terminal(request);

The new @cloudflare/sandbox/xterm export provides a SandboxAddon for xterm.js ↗ with automatic reconnection (exponential backoff + jitter), buffered output replay, and resize forwarding.

import { SandboxAddon } from "@cloudflare/sandbox/xterm";

const addon = new SandboxAddon({
	getWebSocketUrl: ({ sandboxId, origin }) =>
		`${origin}/ws/terminal?id=${sandboxId}`,
	onStateChange: (state, error) => updateUI(state),
});
terminal.loadAddon(addon);
addon.connect({ sandboxId: "my-sandbox" });

import { SandboxAddon } from "@cloudflare/sandbox/xterm";

const addon = new SandboxAddon({
	getWebSocketUrl: ({ sandboxId, origin }) =>
		`${origin}/ws/terminal?id=${sandboxId}`,
	onStateChange: (state, error) => updateUI(state),
});
terminal.loadAddon(addon);
addon.connect({ sandboxId: "my-sandbox" });

To update to the latest version:

npm i @cloudflare/sandbox@latest

Get your content updates into AI Search faster and avoid a full rescan when you do not need it.

Updated a file or need to retry one that errored? When you know exactly which file changed, you can now reindex it directly instead of rescanning your entire data source.

Go to Overview > Indexed Items and select the sync icon next to any file to reindex it immediately.

By default, AI Search crawls all sitemaps listed in your robots.txt, up to the maximum files per index limit. If your site has multiple sitemaps but you only want to index a specific set, you can now specify a single sitemap URL to limit what the crawler visits.

For example, if your robots.txt lists both blog-sitemap.xml and docs-sitemap.xml, you can specify just https://example.com/docs-sitemap.xml to index only your documentation.

Configure your selection anytime in Settings > Parsing options > Specific sitemaps, then trigger a sync to apply the changes.

Learn more about indexing controls and website crawling configuration.

R2 SQL now supports five approximate aggregation functions for fast analysis of large datasets. These functions trade minor precision for improved performance on high-cardinality data.

• APPROX_PERCENTILE_CONT(column, percentile) — Returns the approximate value at a given percentile (0.0 to 1.0). Works on integer and decimal columns.
• APPROX_PERCENTILE_CONT_WITH_WEIGHT(column, weight, percentile) — Weighted percentile calculation where each row contributes proportionally to its weight column value.
• APPROX_MEDIAN(column) — Returns the approximate median. Equivalent to APPROX_PERCENTILE_CONT(column, 0.5).
• APPROX_DISTINCT(column) — Returns the approximate number of distinct values. Works on any column type.
• APPROX_TOP_K(column, k) — Returns the k most frequent values with their counts as a JSON array.

All functions support WHERE filters. All except APPROX_TOP_K support GROUP BY.

-- Percentile analysis on revenue data
SELECT approx_percentile_cont(total_amount, 0.25),
       approx_percentile_cont(total_amount, 0.5),
       approx_percentile_cont(total_amount, 0.75)
FROM my_namespace.sales_data

-- Median per department
SELECT department, approx_median(total_amount)
FROM my_namespace.sales_data
GROUP BY department

-- Approximate distinct customers by region
SELECT region, approx_distinct(customer_id)
FROM my_namespace.sales_data
GROUP BY region

-- Top 5 most frequent departments
SELECT approx_top_k(department, 5)
FROM my_namespace.sales_data

-- Combine approximate and standard aggregations
SELECT COUNT(*),
       AVG(total_amount),
       approx_percentile_cont(total_amount, 0.5),
       approx_distinct(customer_id)
FROM my_namespace.sales_data
WHERE region = 'North'

For the full syntax and additional examples, refer to the SQL reference.

The Workers Observability dashboard ↗ has some major updates to make it easier to debug your application's issues and share findings with your team.

You can now:

• Create visualizations — Build charts from your Worker data directly in a Worker's Observability tab
• Export data as JSON or CSV — Download logs and traces for offline analysis or to share with teammates
• Share events and traces — Generate direct URLs to specific events, invocations, and traces that open standalone pages with full context
• Customize table columns — Improved field picker to add, remove, and reorder columns in the events table
• Expandable event details — Expand events inline to view full details without leaving the table
• Keyboard shortcuts — Navigate the dashboard with hotkey support

These updates are now live in the Cloudflare dashboard, both in a Worker's Observability tab and in the account-level Observability dashboard for a unified experience. To get started, go to Workers & Pages > select your Worker > Observability.

Cloudflare Queues is now part of the Workers free plan, offering guaranteed message delivery across up to 10,000 queues to either Cloudflare Workers or HTTP pull consumers. Every Cloudflare account now includes 10,000 operations per day across reads, writes, and deletes. For more details on how each operation is defined, refer to Queues pricing ↗.

All features of the existing Queues functionality are available on the free plan, including unlimited event subscriptions. Note that the maximum retention period on the free tier, however, is 24 hours rather than 14 days.

If you are new to Cloudflare Queues, follow this guide ↗ or try one of our tutorials to get started.

Cloudflare Workflows now automatically generates visual diagrams from your code

Your Workflow is parsed to provide a visual map of the Workflow structure, allowing you to:

• Understand how steps connect and execute
• Visualize loops and nested logic
• Follow branching paths for conditional logic

You can collapse loops and nested logic to see the high-level flow, or expand them to see every step.

Workflow diagrams are available in beta for all JavaScript and TypeScript Workflows. Find your Workflows in the Cloudflare dashboard ↗ to see their diagrams.

The latest release of the Agents SDK ↗ brings first-class support for Cloudflare Workflows, synchronous state management, and new scheduling capabilities.

Agents excel at real-time communication and state management. Workflows excel at durable execution. Together, they enable powerful patterns where Agents handle WebSocket connections while Workflows handle long-running tasks, retries, and human-in-the-loop flows.

Use the new AgentWorkflow class to define workflows with typed access to your Agent:

import { AgentWorkflow } from "agents/workflows";

export class ProcessingWorkflow extends AgentWorkflow {
	async run(event, step) {
		// Call Agent methods via RPC
		await this.agent.updateStatus(event.payload.taskId, "processing");

		// Non-durable: progress reporting to clients
		await this.reportProgress({ step: "process", percent: 0.5 });
		this.broadcastToClients({ type: "update", taskId: event.payload.taskId });

		// Durable via step: idempotent, won't repeat on retry
		await step.mergeAgentState({ taskProgress: 0.5 });

		const result = await step.do("process", async () => {
			return processData(event.payload.data);
		});

		await step.reportComplete(result);
		return result;
	}
}

import { AgentWorkflow } from "agents/workflows";
import type { AgentWorkflowEvent, AgentWorkflowStep } from "agents/workflows";

export class ProcessingWorkflow extends AgentWorkflow<MyAgent, TaskParams> {
	async run(event: AgentWorkflowEvent<TaskParams>, step: AgentWorkflowStep) {
		// Call Agent methods via RPC
		await this.agent.updateStatus(event.payload.taskId, "processing");

		// Non-durable: progress reporting to clients
		await this.reportProgress({ step: "process", percent: 0.5 });
		this.broadcastToClients({ type: "update", taskId: event.payload.taskId });

		// Durable via step: idempotent, won't repeat on retry
		await step.mergeAgentState({ taskProgress: 0.5 });

		const result = await step.do("process", async () => {
			return processData(event.payload.data);
		});

		await step.reportComplete(result);
		return result;
	}
}

Start workflows from your Agent with runWorkflow() and handle lifecycle events:

export class MyAgent extends Agent {
	async startTask(taskId, data) {
		const instanceId = await this.runWorkflow("PROCESSING_WORKFLOW", {
			taskId,
			data,
		});
		return { instanceId };
	}

	async onWorkflowProgress(workflowName, instanceId, progress) {
		this.broadcast(JSON.stringify({ type: "progress", progress }));
	}

	async onWorkflowComplete(workflowName, instanceId, result) {
		console.log(`Workflow ${instanceId} completed`);
	}

	async onWorkflowError(workflowName, instanceId, error) {
		console.error(`Workflow ${instanceId} failed:`, error);
	}
}

export class MyAgent extends Agent {
	async startTask(taskId: string, data: string) {
		const instanceId = await this.runWorkflow("PROCESSING_WORKFLOW", {
			taskId,
			data,
		});
		return { instanceId };
	}

	async onWorkflowProgress(
		workflowName: string,
		instanceId: string,
		progress: unknown,
	) {
		this.broadcast(JSON.stringify({ type: "progress", progress }));
	}

	async onWorkflowComplete(
		workflowName: string,
		instanceId: string,
		result?: unknown,
	) {
		console.log(`Workflow ${instanceId} completed`);
	}

	async onWorkflowError(
		workflowName: string,
		instanceId: string,
		error: unknown,
	) {
		console.error(`Workflow ${instanceId} failed:`, error);
	}
}

Key workflow methods on your Agent:

• runWorkflow(workflowName, params, options?) — Start a workflow with optional metadata
• getWorkflow(workflowId) / getWorkflows(criteria?) — Query workflows with cursor-based pagination
• approveWorkflow(workflowId) / rejectWorkflow(workflowId) — Human-in-the-loop approval flows
• pauseWorkflow(), resumeWorkflow(), terminateWorkflow() — Workflow control

State updates are now synchronous with a new validateStateChange() validation hook:

export class MyAgent extends Agent {
	validateStateChange(oldState, newState) {
		// Return false to reject the change
		if (newState.count < 0) return false;
		// Return modified state to transform
		return { ...newState, lastUpdated: Date.now() };
	}
}

export class MyAgent extends Agent<Env, State> {
	validateStateChange(oldState: State, newState: State): State | false {
		// Return false to reject the change
		if (newState.count < 0) return false;
		// Return modified state to transform
		return { ...newState, lastUpdated: Date.now() };
	}
}

The new scheduleEvery() method enables fixed-interval recurring tasks with built-in overlap prevention:

// Run every 5 minutes
await this.scheduleEvery("syncData", 5 * 60 * 1000, { source: "api" });

// Run every 5 minutes
await this.scheduleEvery("syncData", 5 * 60 * 1000, { source: "api" });

• Client-side RPC timeout — Set timeouts on callable method invocations
• StreamingResponse.error(message) — Graceful stream error signaling
• getCallableMethods() — Introspection API for discovering callable methods
• Connection close handling — Pending calls are automatically rejected on disconnect

await agent.call("method", [args], {
	timeout: 5000,
	stream: { onChunk, onDone, onError },
});

await agent.call("method", [args], {
	timeout: 5000,
	stream: { onChunk, onDone, onError },
});

Secure email reply routing — Email replies are now secured with HMAC-SHA256 signed headers, preventing unauthorized routing of emails to agent instances.

Routing improvements:

• basePath option to bypass default URL construction for custom routing
• Server-sent identity — Agents send name and agent type on connect
• New onIdentity and onIdentityChange callbacks on the client

const agent = useAgent({
	basePath: "user",
	onIdentity: (name, agentType) => console.log(`Connected to ${name}`),
});

const agent = useAgent({
	basePath: "user",
	onIdentity: (name, agentType) => console.log(`Connected to ${name}`),
});

To update to the latest version:

npm i agents@latest

For the complete Workflows API reference and patterns, see Run Workflows.

Local Uploads is now available in open beta. Enable it on your R2 bucket to improve upload performance when clients upload data from a different region than your bucket. With Local Uploads enabled, object data is written to storage infrastructure near the client, then asynchronously replicated to your bucket. The object is immediately accessible and remains strongly consistent throughout. Refer to How R2 works for details on how data is written to your bucket.

In our tests, we observed up to 75% reduction in Time to Last Byte (TTLB) for upload requests when Local Uploads is enabled.

This feature is ideal when:

• Your users are globally distributed
• Upload performance and reliability is critical to your application
• You want to optimize write performance without changing your bucket's primary location

To enable Local Uploads on your bucket, find Local Uploads in your bucket settings in the Cloudflare Dashboard ↗, or run:

npx wrangler r2 bucket local-uploads enable <BUCKET_NAME>

Enabling Local Uploads on a bucket is seamless: existing uploads will complete as expected and there’s no interruption to traffic. There is no additional cost to enable Local Uploads. Upload requests incur the standard Class A operation costs same as upload requests made without Local Uploads.

For more information, refer to Local Uploads.

The minimum cacheTtl parameter for Workers KV has been reduced from 60 seconds to 30 seconds. This change applies to both get() and getWithMetadata() methods.

This reduction allows you to maintain more up-to-date cached data and have finer-grained control over cache behavior. Applications requiring faster data refresh rates can now configure cache durations as low as 30 seconds instead of the previous 60-second minimum.

The cacheTtl parameter defines how long a KV result is cached at the global network location it is accessed from:

// Read with custom cache TTL
const value = await env.NAMESPACE.get("my-key", {
	cacheTtl: 30, // Cache for minimum 30 seconds (previously 60)
});

// getWithMetadata also supports the reduced cache TTL
const valueWithMetadata = await env.NAMESPACE.getWithMetadata("my-key", {
	cacheTtl: 30, // Cache for minimum 30 seconds
});

The default cache TTL remains unchanged at 60 seconds. Upgrade to the latest version of Wrangler to be able to use 30 seconds cacheTtl.

This change affects all KV read operations using the binding API. For more information, consult the Workers KV cache TTL documentation.

We have partnered with Black Forest Labs (BFL) again to bring their optimized FLUX.2 [klein] 9B model to Workers AI. This distilled model offers enhanced quality compared to the 4B variant, while maintaining cost-effective pricing. With a fixed 4-step inference process, Klein 9B is ideal for rapid prototyping and real-time applications where both speed and quality matter.

Read the BFL blog ↗ to learn more about the model itself, or try it out yourself on our multi modal playground ↗.

Pricing documentation is available on the model page or pricing page.

The model hosted on Workers AI is optimized for speed with a fixed 4-step inference process and supports up to 4 image inputs. Since this is a distilled model, the steps parameter is fixed at 4 and cannot be adjusted. Like FLUX.2 [dev] and FLUX.2 [klein] 4B, this image model uses multipart form data inputs, even if you just have a prompt.

With the REST API, the multipart form data input looks like this:

curl --request POST \
  --url 'https://api.cloudflare.com/client/v4/accounts/{ACCOUNT}/ai/run/@cf/black-forest-labs/flux-2-klein-9b' \
  --header 'Authorization: Bearer {TOKEN}' \
  --header 'Content-Type: multipart/form-data' \
  --form 'prompt=a sunset at the alps' \
  --form width=1024 \
  --form height=1024

With the Workers AI binding, you can use it as such:

const form = new FormData();
form.append("prompt", "a sunset with a dog");
form.append("width", "1024");
form.append("height", "1024");

// FormData doesn't expose its serialized body or boundary. Passing it to a
// Request (or Response) constructor serializes it and generates the Content-Type
// header with the boundary, which is required for the server to parse the multipart fields.
const formResponse = new Response(form);
const formStream = formResponse.body;
const formContentType = formResponse.headers.get('content-type');

const resp = await env.AI.run("@cf/black-forest-labs/flux-2-klein-9b", {
	multipart: {
		body: formStream,
		contentType: formContentType,
	},
});

The parameters you can send to the model are detailed here:

The FLUX.2 klein-9b model supports generating images based on reference images, just like FLUX.2 [dev] and FLUX.2 [klein] 4B. You can use this feature to apply the style of one image to another, add a new character to an image, or iterate on past generated images. You would use it with the same multipart form data structure, with the input images in binary. The model supports up to 4 input images.

For the prompt, you can reference the images based on the index, like take the subject of image 1 and style it like image 0 or even use natural language like place the dog beside the woman.

You must name the input parameter as input_image_0, input_image_1, input_image_2, input_image_3 for it to work correctly. All input images must be smaller than 512x512.

curl --request POST \
  --url 'https://api.cloudflare.com/client/v4/accounts/{ACCOUNT}/ai/run/@cf/black-forest-labs/flux-2-klein-9b' \
  --header 'Authorization: Bearer {TOKEN}' \
  --header 'Content-Type: multipart/form-data' \
  --form 'prompt=take the subject of image 1 and style it like image 0' \
  --form input_image_0=@/Users/johndoe/Desktop/icedoutkeanu.png \
  --form input_image_1=@/Users/johndoe/Desktop/me.png \
  --form width=1024 \
  --form height=1024

Through Workers AI Binding:

//helper function to convert ReadableStream to Blob
async function streamToBlob(stream: ReadableStream, contentType: string): Promise<Blob> {
  const reader = stream.getReader();
  const chunks = [];

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    chunks.push(value);
  }

  return new Blob(chunks, { type: contentType });
}

const image0 = await fetch("http://image-url");
const image1 = await fetch("http://image-url");
const form = new FormData();

const image_blob0 = await streamToBlob(image0.body, "image/png");
const image_blob1 = await streamToBlob(image1.body, "image/png");
form.append('input_image_0', image_blob0)
form.append('input_image_1', image_blob1)
form.append('prompt', 'take the subject of image 1 and style it like image 0')

// FormData doesn't expose its serialized body or boundary. Passing it to a
// Request (or Response) constructor serializes it and generates the Content-Type
// header with the boundary, which is required for the server to parse the multipart fields.
const formResponse = new Response(form);
const formStream = formResponse.body;
const formContentType = formResponse.headers.get('content-type');

const resp = await env.AI.run("@cf/black-forest-labs/flux-2-klein-9b", {
    multipart: {
        body: formStream,
        contentType: formContentType
    }
})

Paid plans can now have up to 100,000 files per Pages site, increased from the previous limit of 20,000 files.

To enable this increased limit, set the environment variable PAGES_WRANGLER_MAJOR_VERSION=4 in your Pages project settings.

The Free plan remains at 20,000 files per site.

For more details, refer to the Pages limits documentation.

You can now store up to 10 million vectors in a single Vectorize index, doubling the previous limit of 5 million vectors. This enables larger-scale semantic search, recommendation systems, and retrieval-augmented generation (RAG) applications without splitting data across multiple indexes.

Vectorize continues to support indexes with up to 1,536 dimensions per vector at 32-bit precision. Refer to the Vectorize limits documentation for complete details.

You can now configure Workers to run close to infrastructure in legacy cloud regions to minimize latency to existing services and databases. This is most useful when your Worker makes multiple round trips.

To set a placement hint, set the placement.region property in your Wrangler configuration file:

{
	"placement": {
		"region": "aws:us-east-1",
	},
}

[placement]
region = "aws:us-east-1"

Placement hints support Amazon Web Services (AWS), Google Cloud Platform (GCP), and Microsoft Azure region identifiers. Workers run in the Cloudflare data center ↗ with the lowest latency to the specified cloud region.

If your existing infrastructure is not in these cloud providers, expose it to placement probes with placement.host for layer 4 checks or placement.hostname for layer 7 checks. These probes are designed to locate single-homed infrastructure and are not suitable for anycasted or multicasted resources.

{
	"placement": {
		"host": "my_database_host.com:5432",
	},
}

[placement]
host = "my_database_host.com:5432"

{
	"placement": {
		"hostname": "my_api_server.com",
	},
}

[placement]
hostname = "my_api_server.com"

This is an extension of Smart Placement, which automatically places your Workers closer to back-end APIs based on measured latency. When you do not know the location of your back-end APIs or have multiple back-end APIs, set mode: "smart":

{
	"placement": {
		"mode": "smart",
	},
}

[placement]
mode = "smart"

AI Search now includes path filtering for both website and R2 data sources. You can now control which content gets indexed by defining include and exclude rules for paths.

By controlling what gets indexed, you can improve the relevance and quality of your search results. You can also use path filtering to split a single data source across multiple AI Search instances for specialized search experiences.

Path filtering uses micromatch ↗ patterns, so you can use * to match within a directory and ** to match across directories.

Configure path filters when creating a new instance or update them anytime from Settings. Check out path filtering to learn more.

You can now create AI Search instances programmatically using the API. For example, use the API to create instances for each customer in a multi-tenant application or manage AI Search alongside your other infrastructure.

If you have created an AI Search instance via the dashboard before, you already have a service API token registered and can start creating instances programmatically right away. If not, follow the API guide to set up your first instance.

For example, you can now create separate search instances for each language on your website:

for lang in en fr es de; do
  curl -X POST "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-search/instances" \
    -H "Authorization: Bearer $API_TOKEN" \
    -H "Content-Type: application/json" \
    --data '{
      "id": "docs-'"$lang"'",
      "type": "web-crawler",
      "source": "example.com",
      "source_params": {
        "path_include": ["**/'"$lang"'/**"]
      }
    }'
done

Refer to the REST API reference for additional configuration options.

Workers KV has an updated dashboard UI with new dashboard styling that makes it easier to navigate and see analytics and settings for a KV namespace.

The new dashboard features a streamlined homepage for easy access to your namespaces and key operations, with consistent design with the rest of the dashboard UI updates. It also provides an improved analytics view.

The updated dashboard is now available for all Workers KV users. Log in to the Cloudflare Dashboard ↗ to start exploring the new interface.

Disclaimer: Please note that v6.0.0-beta.1 is in Beta and we are still testing it for stability.

Full Changelog: v5.2.0...v6.0.0-beta.1 ↗

In this release, you'll see a large number of breaking changes. This is primarily due to a change in OpenAPI definitions, which our libraries are based off of, and codegen updates that we rely on to read those OpenAPI definitions and produce our SDK libraries. As the codegen is always evolving and improving, so are our code bases.

Some breaking changes were introduced due to bug fixes, also listed below.

Please ensure you read through the list of changes below before moving to this version - this will help you understand any down or upstream issues it may cause to your environments.

• BGPPrefixCreateParams.cidr: optional → required
• PrefixCreateParams.asn: number | null → number
• PrefixCreateParams.loa_document_id: required → optional
• ServiceBindingCreateParams.cidr: optional → required
• ServiceBindingCreateParams.service_id: optional → required

• ConfigurationUpdateResponse removed
• PublicSchema → OldPublicSchema
• SchemaUpload → UserSchemaCreateResponse
• ConfigurationUpdateParams.properties removed; use normalize

• ThreatEventBulkCreateResponse: number → complex object with counts and errors

• DatabaseQueryParams: simple interface → union type (D1SingleQuery | MultipleQueries)
• DatabaseRawParams: same change
• Supports batch queries via batch array

All record type interfaces renamed from *Record to short names:

• RecordResponse.ARecord → RecordResponse.A
• RecordResponse.AAAARecord → RecordResponse.AAAA
• RecordResponse.CNAMERecord → RecordResponse.CNAME
• RecordResponse.MXRecord → RecordResponse.MX
• RecordResponse.NSRecord → RecordResponse.NS
• RecordResponse.PTRRecord → RecordResponse.PTR
• RecordResponse.TXTRecord → RecordResponse.TXT
• RecordResponse.CAARecord → RecordResponse.CAA
• RecordResponse.CERTRecord → RecordResponse.CERT
• RecordResponse.DNSKEYRecord → RecordResponse.DNSKEY
• RecordResponse.DSRecord → RecordResponse.DS
• RecordResponse.HTTPSRecord → RecordResponse.HTTPS
• RecordResponse.LOCRecord → RecordResponse.LOC
• RecordResponse.NAPTRRecord → RecordResponse.NAPTR
• RecordResponse.SMIMEARecord → RecordResponse.SMIMEA
• RecordResponse.SRVRecord → RecordResponse.SRV
• RecordResponse.SSHFPRecord → RecordResponse.SSHFP
• RecordResponse.SVCBRecord → RecordResponse.SVCB
• RecordResponse.TLSARecord → RecordResponse.TLSA
• RecordResponse.URIRecord → RecordResponse.URI
• RecordResponse.OpenpgpkeyRecord → RecordResponse.Openpgpkey

• ResourceGroupCreateResponse.scope: optional single → required array
• ResourceGroupCreateResponse.id: optional → required

• OriginCACertificateCreateParams.csr: optional → required
• OriginCACertificateCreateParams.hostnames: optional → required
• OriginCACertificateCreateParams.request_type: optional → required

• Renamed: DeploymentsSinglePage → DeploymentListResponsesV4PagePaginationArray
• Domain response fields: many optional → required

• Entire v0 API deprecated; use v1 methods (createV1, listV1, etc.)
• New sub-resources: Sinks, Streams

• EventNotificationUpdateParams.rules: optional → required
• Super Slurper: bucket, secret now required in source params

• dataSource: string → typed enum (23 values)
• eventType: string → typed enum (6 values)
• V2 methods require dimension parameter (breaking signature change)

• Removed: status_message field from all recipient response types

• Consolidated SchemaCreateResponse, SchemaListResponse, SchemaEditResponse, SchemaGetResponse → PublicSchema
• Renamed: SchemaListResponsesV4PagePaginationArray → PublicSchemasV4PagePaginationArray

• Renamed union members: AppListResponse.UnionMember0 → SpectrumConfigAppConfig
• Renamed union members: AppListResponse.UnionMember1 → SpectrumConfigPaygoAppConfig

• Removed: WorkersBindingKindTailConsumer type (all occurrences)
• Renamed: ScriptsSinglePage → ScriptListResponsesSinglePage
• Removed: DeploymentsSinglePage

• datasets.create(), update(), get() return types changed
• PredefinedGetResponse union members renamed to UnionMember0-5

• Removed: CloudflaredCreateResponse, CloudflaredListResponse, CloudflaredDeleteResponse, CloudflaredEditResponse, CloudflaredGetResponse
• Removed: CloudflaredListResponsesV4PagePaginationArray

• Reports: create, list, get
• Mitigations: sub-resource for abuse mitigations

• Instances: create, update, list, delete, read, stats
• Items: list, get
• Jobs: create, list, get, logs
• Tokens: create, update, list, delete, read

• Directory Services: create, update, list, delete, get
• Supports IPv4, IPv6, dual-stack, and hostname configurations

• Organizations: create, update, list, delete, get
• OrganizationProfile: update, get
• Hierarchical organization support with parent/child relationships

• Catalog: list, enable, disable, get
• Credentials: create
• MaintenanceConfigs: update, get
• Namespaces: list
• Tables: list, maintenance config management
• Apache Iceberg integration

• Apps: get, post
• Meetings: create, get, participant management
• Livestreams: 10+ methods for streaming
• Recordings: start, pause, stop, get
• Sessions: transcripts, summaries, chat
• Webhooks: full CRUD
• ActiveSession: polls, kick participants
• Analytics: organization analytics

• Configuration: create, list, delete, edit, get
• Credentials: update
• Rules: create, list, delete, bulkCreate, bulkEdit, edit, get
• JWT validation with RS256/384/512, PS256/384/512, ES256, ES384

• create, update, list, delete, get

• create, update, list, delete, get, beginVerification

• Sinks: create, list, delete, get
• Streams: create, update, list, delete, get

• Portals: create, update, list, delete, read
• Servers: create, update, list, delete, read, sync

• managed_by field with parent_org_id, parent_org_name

• auto_generated field on LOADocumentCreateResponse

• delegate_loa_creation, irr_validation_state, ownership_validation_state, ownership_validation_token, rpki_validation_state

• Added toMarkdown.supported() method to get all supported conversion formats

• zdr field added to all responses and params

• New alert type: abuse_report_alert
• type field added to PolicyFilter

• ContentCreateParams: refined to discriminated union (Variant0 | Variant1)
• Split into URL-based and HTML-based parameter variants for better type safety

• reactivate parameter in edit

• ThreatEventCreateParams.indicatorType: required → optional
• hasChildren field added to all threat event response types
• datasetIds query parameter on AttackerListParams, CategoryListParams, TargetIndustryListParams
• categoryUuid field on TagCreateResponse
• indicators array for multi-indicator support per event
• uuid and preserveUuid fields for UUID preservation in bulk create
• format query parameter ('json' | 'stix2') on ThreatEventListParams
• createdAt, datasetId fields on ThreatEventEditParams

• Added create(), update(), get() methods

• New page types: basic_challenge, under_attack, waf_challenge

• served_by_colo - colo that handled query
• jurisdiction - 'eu' | 'fedramp'
• Time Travel (client.d1.database.timeTravel): getBookmark(), restore() - point-in-time recovery

• New fields on InvestigateListResponse/InvestigateGetResponse: envelope_from, envelope_to, postfix_id_outbound, replyto
• New detection classification: 'outbound_ndr'
• Enhanced Finding interface with attachment, detection, field, portion, reason, score
• Added cursor query parameter to InvestigateListParams

• New list types: CATEGORY, LOCATION, DEVICE

• New issue type: 'configuration_suggestion'
• payload field: unknown → typed Payload interface with detection_method, zone_tag

• Added detections.get() method

• New datasets: dex_application_tests, dex_device_state_events, ipsec_logs, warp_config_changes, warp_toggle_changes

• Monitor.port: number → number | null
• Pool.load_shedding: LoadShedding → LoadShedding | null
• Pool.origin_steering: OriginSteering → OriginSteering | null

• license_key field on connectors
• provision_license parameter for auto-provisioning
• IPSec: custom_remote_identities with FQDN support
• Snapshots: Bond interface, probed_mtu field

• New response types: ProjectCreateResponse, ProjectListResponse, ProjectEditResponse, ProjectGetResponse
• Deployment methods return specific response types instead of generic Deployment

• Added subscriptions.get() method
• Enhanced SubscriptionGetResponse with typed event source interfaces
• New event source types: Images, KV, R2, Vectorize, Workers AI, Workers Builds, Workflows

• Sippy: new provider s3 (S3-compatible endpoints)
• Sippy: bucketUrl field for S3-compatible sources
• Super Slurper: keys field on source response schemas (specify specific keys to migrate)
• Super Slurper: pathPrefix field on source schemas
• Super Slurper: region field on S3 source params

• Added geolocations.list(), geolocations.get() methods
• Added V2 dimension-based methods (summaryV2, timeseriesGroupsV2) to radar sub-resources

• Added terminal boolean field to Resource Error interfaces

• Added id field to ItemDeleteParams.Item

• New buffering fields on SetConfigRule: request_body_buffering, response_body_buffering

• New scopes: 'dex', 'access' (in addition to 'workers', 'ai_gateway')

• Response types now proper interfaces (was unknown)
• Fields now required: id, certificates, hosts, status, type

• payload field: unknown → typed Payload interface with detection_method, zone_tag

• Added: CloudflareTunnelsV4PagePaginationArray pagination class

• Added subdomains.delete() method
• Worker.references - track external dependencies (domains, Durable Objects, queues)
• Worker.startup_time_ms - startup timing
• Script.observability - observability settings with logging
• Script.tag, Script.tags - immutable ID and tags
• Placement: support for region, hostname, host-based placement
• tags, tail_consumers now accept | null
• Telemetry: traces field, $containers event info, durableObjectId, transactionName, abr_level fields

• ScriptUpdateResponse: new fields entry_point, observability, tag, tags
• placement field now union of 4 variants (smart mode, region, hostname, host)
• tags, tail_consumers now nullable
• TagUpdateParams.body now accepts null

• instance_retention: unknown → typed InstanceRetention interface with error_retention, success_retention
• New status option: 'restart' added to StatusEditParams.status

• External emergency disconnect settings (4 new fields)
• antivirus device posture check type
• os_version_extra documentation improvements

• New response types: SubscriptionCreateResponse, SubscriptionUpdateResponse, SubscriptionGetResponse

• New ApplicationType values: 'mcp', 'mcp_portal', 'proxy_endpoint'
• New destination type: ViaMcpServerPortalDestination for MCP server access

• Added rules.listTenant() method

• ProxyEndpoint: interface → discriminated union (ZeroTrustGatewayProxyEndpointIP | ZeroTrustGatewayProxyEndpointIdentity)
• ProxyEndpointCreateParams: interface → union type
• Added kind field: 'ip' | 'identity'

• WARPConnector*Response: union type → interface

• API Gateway: UserSchemas, Settings, SchemaValidation resources
• Audit Logs: auditLogId.not (use id.not)
• CloudforceOne: ThreatEvents.get(), IndicatorTypes.list()
• Devices: public_ip field (use DEX API)
• Email Security: item_count field in Move responses
• Pipelines: v0 methods (use v1)
• Radar: old summary() and timeseriesGroups() methods (use V2)
• Rulesets: disable_apps, mirage fields
• WARP Connector: connections field
• Workers: environment parameter in Domains
• Zones: ResponseBuffering page rule

• mcp: correct code tool API endpoint (599703c ↗)
• mcp: return correct lines on typescript errors (5d6f999 ↗)
• organization_profile: fix bad reference (d84ea77 ↗)
• schema_validation: correctly reflect model to openapi mapping (bb86151 ↗)
• workers: fix tests (2ee37f7 ↗)

• Added deprecation notices with migration paths
• api_gateway: deprecate API Shield Schema Validation resources (8a4b20f ↗)
• Improved JSDoc examples across all resources
• workers: expose subdomain delete documentation (4f7cc1f ↗)

In January 2025, we announced the launch of the new Terraform v5 Provider. We greatly appreciate the proactive engagement and valuable feedback from the Cloudflare community following the v5 release. In response, we've established a consistent and rapid 2-3 week cadence ↗ for releasing targeted improvements, demonstrating our commitment to stability and reliability.

With the help of the community, we have a growing number of resources that we have marked as stable ↗, with that list continuing to grow with every release. The most used resources ↗ are on track to be stable by the end of March 2026, when we will also be releasing a new migration tool to you migrate from v4 to v5 with ease.

Thank you for continuing to raise issues. They make our provider stronger and help us build products that reflect your needs.

This release includes bug fixes, the stabilization of even more popular resources, and more.

• custom_pages: add "waf_challenge" as new supported error page type identifier in both resource and data source schemas
• list: enhance CIDR validator to check for normalized CIDR notation requiring network address for IPv4 and IPv6
• magic_wan_gre_tunnel: add automatic_return_routing attribute for automatic routing control
• magic_wan_gre_tunnel: add BGP configuration support with new BGP model attribute
• magic_wan_gre_tunnel: add bgp_status computed attribute for BGP connection status information
• magic_wan_gre_tunnel: enhance schema with BGP-related attributes and validators
• magic_wan_ipsec_tunnel: add automatic_return_routing attribute for automatic routing control
• magic_wan_ipsec_tunnel: add BGP configuration support with new BGP model attribute
• magic_wan_ipsec_tunnel: add bgp_status computed attribute for BGP connection status information
• magic_wan_ipsec_tunnel: add custom_remote_identities attribute for custom identity configuration
• magic_wan_ipsec_tunnel: enhance schema with BGP and identity-related attributes
• ruleset: add request body buffering support
• ruleset: enhance ruleset data source with additional configuration options
• workers_script: add observability logs attributes to list data source model
• workers_script: enhance list data source schema with additional configuration options

• account_member: fix resource importability issues
• dns_record: remove unnecessary fmt.Sprintf wrapper around LoadTestCase call in test configuration helper function
• load_balancer: fix session_affinity_ttl type expectations to match Float64 in initial creation and Int64 after migration
• workers_kv: handle special characters correctly in URL encoding

• account_subscription: update schema description for rate_plan.sets attribute to clarify it returns an array of strings
• api_shield: add resource-level description for API Shield management of auth ID characteristics
• api_shield: enhance auth_id_characteristics.name attribute description to include JWT token configuration format requirements
• api_shield: specify JSONPath expression format for JWT claim locations
• hyperdrive_config: add description attribute to name attribute explaining its purpose in dashboard and API identification
• hyperdrive_config: apply description improvements across resource, data source, and list data source schemas
• hyperdrive_config: improve schema descriptions for cache settings to clarify default values
• hyperdrive_config: update port description to clarify defaults for different database types

• Terraform Provider ↗
• Documentation on using Terraform with Cloudflare
• List of stabilized resources ↗

Auxiliary Workers are now fully supported when using full-stack frameworks, such as React Router and TanStack Start, that integrate with the Cloudflare Vite plugin. They are included alongside the framework's build output in the build output directory. Note that this feature requires Vite 7 or above.

Auxiliary Workers are additional Workers that can be called via service bindings from your main (entry) Worker. They are defined in the plugin config, as in the example below:

import { defineConfig } from "vite";
import { tanstackStart } from "@tanstack/react-start/plugin/vite";
import { cloudflare } from "@cloudflare/vite-plugin";

export default defineConfig({
	plugins: [
		tanstackStart(),
		cloudflare({
			viteEnvironment: { name: "ssr" },
			auxiliaryWorkers: [{ configPath: "./wrangler.aux.jsonc" }],
		}),
	],
});

See the Vite plugin API docs for more info.

The .sql file extension is now automatically configured to be importable in your Worker code when using Wrangler or the Cloudflare Vite plugin. This is particular useful for importing migrations in Durable Objects and means you no longer need to configure custom rules when using Drizzle ↗.

SQL files are imported as JavaScript strings:

// `example` will be a JavaScript string
import example from "./example.sql";

We have made it easier to validate connectivity when deploying WARP Connector as part of your software-defined private network.

You can now ping the WARP Connector host directly on its LAN IP address immediately after installation. This provides a fast, familiar way to confirm that the Connector is online and reachable within your network before testing access to downstream services.

Starting with version 2025.10.186.0, WARP Connector responds to traffic addressed to its own LAN IP, giving you immediate visibility into Connector reachability.

Learn more about deploying WARP Connector and building private network connectivity with Cloudflare One.

We've partnered with Black Forest Labs (BFL) again to bring their optimized FLUX.2 [klein] 4B model to Workers AI! This distilled model offers faster generation and cost-effective pricing, while maintaining great output quality. With a fixed 4-step inference process, Klein 4B is ideal for rapid prototyping and real-time applications where speed matters.

Read the BFL blog ↗ to learn more about the model itself, or try it out yourself on our multi modal playground ↗.

Pricing documentation is available on the model page or pricing page.

The model hosted on Workers AI is optimized for speed with a fixed 4-step inference process and supports up to 4 image inputs. Since this is a distilled model, the steps parameter is fixed at 4 and cannot be adjusted. Like FLUX.2 [dev], this image model uses multipart form data inputs, even if you just have a prompt.

With the REST API, the multipart form data input looks like this:

curl --request POST \
  --url 'https://api.cloudflare.com/client/v4/accounts/{ACCOUNT}/ai/run/@cf/black-forest-labs/flux-2-klein-4b' \
  --header 'Authorization: Bearer {TOKEN}' \
  --header 'Content-Type: multipart/form-data' \
  --form 'prompt=a sunset at the alps' \
  --form width=1024 \
  --form height=1024

With the Workers AI binding, you can use it as such:

const form = new FormData();
form.append("prompt", "a sunset with a dog");
form.append("width", "1024");
form.append("height", "1024");

// FormData doesn't expose its serialized body or boundary. Passing it to a
// Request (or Response) constructor serializes it and generates the Content-Type
// header with the boundary, which is required for the server to parse the multipart fields.
const formResponse = new Response(form);
const formStream = formResponse.body;
const formContentType = formResponse.headers.get('content-type');

const resp = await env.AI.run("@cf/black-forest-labs/flux-2-klein-4b", {
	multipart: {
		body: formStream,
		contentType: formContentType,
	},
});

The parameters you can send to the model are detailed here:

## Multi-Reference Images

The FLUX.2 klein-4b model supports generating images based on reference images, just like FLUX.2 [dev]. You can use this feature to apply the style of one image to another, add a new character to an image, or iterate on past generated images. You would use it with the same multipart form data structure, with the input images in binary. The model supports up to 4 input images.

For the prompt, you can reference the images based on the index, like `take the subject of image 1 and style it like image 0` or even use natural language like `place the dog beside the woman`.

Note: you have to name the input parameter as `input_image_0`, `input_image_1`, `input_image_2`, `input_image_3` for it to work correctly. All input images must be smaller than 512x512.

```bash
curl --request POST \
  --url 'https://api.cloudflare.com/client/v4/accounts/{ACCOUNT}/ai/run/@cf/black-forest-labs/flux-2-klein-4b' \
  --header 'Authorization: Bearer {TOKEN}' \
  --header 'Content-Type: multipart/form-data' \
  --form 'prompt=take the subject of image 1 and style it like image 0' \
  --form input_image_0=@/Users/johndoe/Desktop/icedoutkeanu.png \
  --form input_image_1=@/Users/johndoe/Desktop/me.png \
  --form width=1024 \
  --form height=1024

Through Workers AI Binding:

//helper function to convert ReadableStream to Blob
async function streamToBlob(stream: ReadableStream, contentType: string): Promise<Blob> {
  const reader = stream.getReader();
  const chunks = [];

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    chunks.push(value);
  }

  return new Blob(chunks, { type: contentType });
}

const image0 = await fetch("http://image-url");
const image1 = await fetch("http://image-url");
const form = new FormData();

const image_blob0 = await streamToBlob(image0.body, "image/png");
const image_blob1 = await streamToBlob(image1.body, "image/png");
form.append('input_image_0', image_blob0)
form.append('input_image_1', image_blob1)
form.append('prompt', 'take the subject of image 1 and style it like image 0')

// FormData doesn't expose its serialized body or boundary. Passing it to a
// Request (or Response) constructor serializes it and generates the Content-Type
// header with the boundary, which is required for the server to parse the multipart fields.
const formResponse = new Response(form);
const formStream = formResponse.body;
const formContentType = formResponse.headers.get('content-type');

const resp = await env.AI.run("@cf/black-forest-labs/flux-2-klein-4b", {
    multipart: {
        body: formStream,
        contentType: formContentType
    }
})

The wrangler types command now generates TypeScript types for bindings from all environments defined in your Wrangler configuration file by default.

Previously, wrangler types only generated types for bindings in the top-level configuration (or a single environment when using the --env flag). This meant that if you had environment-specific bindings — for example, a KV namespace only in production or an R2 bucket only in staging — those bindings would be missing from your generated types, causing TypeScript errors when accessing them.

Now, running wrangler types collects bindings from all environments and includes them in the generated Env type. This ensures your types are complete regardless of which environment you deploy to.

If you want the previous behavior of generating types for only a specific environment, you can use the --env flag:

wrangler types --env production

Learn more about generating types for your Worker in the Wrangler documentation.

Wrangler now supports a --check flag for the wrangler types command. This flag validates that your generated types are up to date without writing any changes to disk.

This is useful in CI/CD pipelines where you want to ensure that developers have regenerated their types after making changes to their Wrangler configuration. If the types are out of date, the command will exit with a non-zero status code.

npx wrangler types --check

If your types are up to date, the command will succeed silently. If they are out of date, you'll see an error message indicating which files need to be regenerated.

For more information, see the Wrangler types documentation.