Skip to content
Cloudflare Docs

Changelog

New updates and improvements at Cloudflare.

Subscribe to RSS
View all RSS feeds

hero image
← Back to all posts

A new, simpler REST API for Cloudflare Workers (Beta)

Workers

You can now manage Workers, Versions, and Deployments as separate resources with a new, resource-oriented API (Beta).

This new API is supported in the Cloudflare Terraform provider ↗ and the Cloudflare Typescript SDK ↗, allowing platform teams to manage a Worker's infrastructure in Terraform, while development teams handle code deployments from a separate repository or workflow. We also designed this API with AI agents in mind, as a clear, predictable structure is essential for them to reliably build, test, and deploy applications.

Try it out

Before and after

Before: Eight endpoints with mixed responsibilities

The existing API was originally designed for simple, one-shot script uploads.

Terminal window
curl -X PUT "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/workers/scripts/$SCRIPT_NAME" \
    -H "X-Auth-Email: $CLOUDFLARE_EMAIL" \
    -H "X-Auth-Key: $CLOUDFLARE_API_KEY" \
    -H "Content-Type: multipart/form-data" \
    -F 'metadata={
      "main_module": "worker.js",
      "compatibility_date": "$today$"
    }' \
    -F "worker.js=@worker.js;type=application/javascript+module"

This API worked for creating a basic Worker, uploading all of its code, and deploying it immediately — but came with challenges:

  • A Worker couldn't exist without code: To create a Worker, you had to upload its code in the same API request. This prevented platform teams in larger organizations from provisioning Workers with the proper settings, and then handing them off to development teams to deploy the actual code.

  • Updating settings was confusing and fragmented: With the existing API, configuration is scattered across eight different endpoints with overlapping responsibilities. This made it challenging for human developers (and even more difficult for AI agents) to reliably update a Worker's settings. You had to guess between /settings and /script-settings, with not a lot of clarity about which endpoint updated all versions or a specific version of a Worker.

  • Scripts used names as primary identifiers: The existing API uses the Worker script name as the primary identifier for a Worker, which meant that if you wanted to rename a Worker via API, you needed to deploy an entirely new script and update every reference across your infrastructure. If you were using Terraform, renaming a Worker could inadvertently result in destroying the Worker altogether.

After: Three resources with clear boundaries

The new API has three core resources with distinct boundaries: Worker, Versions, and Deployment. All endpoints now use clean JSON payloads, with script content embedded as base64-encoded string, a simpler and more reliable approach than the previous multipart/form-data format.

  • Worker: The parent resource representing your application. It has a stable UUID and holds persistent settings like name, tags, and logpush. You can now create a Worker to establish its identity and settings before any code is uploaded.

  • Version: An immutable snapshot of your code and its specific configuration, like bindings and compatibility_date. Creating a new version is a safe action that doesn't affect live traffic.

  • Deployment: An explicit action that directs traffic to a specific version.

Why this matters

Separation of concerns

The new API enables proper separation of concerns between infrastructure and application teams.

Example: Typescript SDK

// Step 1: Platform team creates the Worker resource (no code needed)
const worker = await client.workers.beta.workers.create({
  name: "payment-service",
  account_id: "...",
  observability: {
    enabled: true,
  },
});


// Step 2: Development team adds code and creates a version later
const version = await client.workers.beta.workers.versions.create(worker.id, {
  account_id: "...",
  main_module: "worker.js",
  compatibility_date: "$today",
  bindings: [ /*...*/ ],
  modules: [
    {
      name: "worker.js",
      content_type: "application/javascript+module",
      content_base64: Buffer.from(scriptContent).toString("base64"),
    },
  ],
});


// Step 3: Deploy explicitly when ready
const deployment = await client.workers.scripts.deployments.create(worker.name, {
  account_id: "...",
  strategy: "percentage",
  versions: [
    {
      percentage: 100,
      version_id: version.id,
    },
  ],
});

Example: Terraform

If you use Terraform, you can now declare the Worker in your Terraform configuration and manage configuration outside of Terraform in your Worker's wrangler.jsonc file and deploy code changes using Wrangler.

resource "cloudflare_worker" "my_worker" {
  account_id = "..."
  name = "my-important-service"
}
# Manage Versions and Deployments here or outside of Terraform
# resource "cloudflare_worker_version" "my_worker_version" {}
# resource "cloudflare_workers_deployment" "my_worker_deployment" {}

No more confusing /settings API endpoints

Configuration now has an obvious home. Worker settings persist across all versions of the Worker, and Version settings are specific to a code snapshot.

Terminal window
# Worker settings (the parent resource)
PUT /workers/workers/{id}
{
  "name": "payment-service",
  "tags": ["production"],
  "logpush": true,
}
Terminal window
# Version settings (the "code")
POST /workers/workers/{id}/versions
{
  "compatibility_date": "$today",
  "bindings": [...],
  "modules": [...]
}

/workers API endpoints now support UUIDs (in addition to names)

The /workers/workers/ path now supports addressing a Worker by both its immutable UUID and its mutable name.

Terminal window
# Both work for the same Worker
GET /workers/workers/29494978e03748669e8effb243cf2515  # UUID (stable for automation)
GET /workers/workers/payment-service                  # Name (convenient for humans)

This dual approach means:

  • Developers can use readable names for debugging.
  • Automation can rely on stable UUIDs to prevent errors when Workers are renamed
  • Terraform can rename Workers without destroying and recreating them.

Learn more

Technical notes

  • You can still use the preexisting Workers REST API, and it remains fully supported.
  • Legacy Terraform resources and SDK methods will be supported until the next major version.