Workers

Manage and deploy Cloudflare Workers

The Workers API allows you to create, deploy, and manage Cloudflare Workers scripts, routes, and settings.

Overview

Access the Workers API through the SDK:

import Cloudflare from 'cloudflare';

const client = new Cloudflare({
  apiToken: process.env.CLOUDFLARE_API_TOKEN,
});

// Access workers resources
const workers = client.workers;

Scripts

Manage Worker scripts and their versions.

Upload a worker script

Create or update a Worker script with module syntax.

const version = await client.workers.beta.workers.versions.create(
  workerId,
  {
    account_id: '023e105f4ecef8ad9ca31a8372d0c353',
    main_module: 'worker.mjs',
    compatibility_date: '2024-03-01',
    bindings: [
      {
        type: 'plain_text',
        name: 'MESSAGE',
        text: 'Hello World!',
      },
    ],
    modules: [
      {
        name: 'worker.mjs',
        content_type: 'application/javascript+module',
        content_base64: Buffer.from(scriptContent).toString('base64'),
      },
    ],
  }
);

account_id · string · required

Your Cloudflare account ID

main_module · string · required

Name of the main module file (e.g., ‘worker.mjs’)

compatibility_date · string · required

Date in YYYY-MM-DD format for Workers runtime compatibility

modules · array · required

Array of module objects containing the script code and metadata

bindings · array

Environment bindings (KV, Durable Objects, secrets, etc.)

id · string

The version ID

main_module · string

The main module name

created_on · string

ISO 8601 timestamp when the version was created

List worker scripts

Retrieve all Worker scripts in your account.

for await (const script of client.workers.scripts.list({
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
})) {
  console.log(script);
}

account_id · string · required

Your Cloudflare account ID

Get worker script

Retrieve details about a specific Worker script.

const script = await client.workers.scripts.get(
  'my-worker',
  { account_id: '023e105f4ecef8ad9ca31a8372d0c353' }
);

Delete worker script

Delete a Worker script.

await client.workers.scripts.delete(
  'my-worker',
  { account_id: '023e105f4ecef8ad9ca31a8372d0c353' }
);

Routes

Manage routes that trigger your Workers.

Create a route

Create a route to trigger a Worker on specific URL patterns.

const route = await client.workers.routes.create({
  zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
  pattern: 'example.com/*',
  script: 'my-worker',
});

zone_id · string · required

The zone identifier

pattern · string · required

URL pattern that triggers the Worker (e.g., ‘example.com/*’)

script · string

Name of the Worker script to execute

List routes

Retrieve all routes in a zone.

for await (const route of client.workers.routes.list({
  zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
})) {
  console.log(route);
}

Update a route

Modify an existing route.

const route = await client.workers.routes.update(
  routeId,
  {
    zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
    pattern: 'example.com/api/*',
    script: 'my-api-worker',
  }
);

Delete a route

await client.workers.routes.delete(
  routeId,
  { zone_id: '023e105f4ecef8ad9ca31a8372d0c353' }
);

Deployments

Manage Worker deployments and traffic routing.

Create a deployment

Deploy a Worker version with traffic percentage allocation.

const deployment = await client.workers.scripts.deployments.create(
  'my-worker',
  {
    account_id: '023e105f4ecef8ad9ca31a8372d0c353',
    strategy: 'percentage',
    versions: [
      {
        percentage: 100,
        version_id: versionId,
      },
    ],
  }
);

strategy · string · required

Deployment strategy (e.g., ‘percentage’)

versions · array · required

Array of version objects with traffic percentage allocation

Subdomains

Manage workers.dev subdomain settings.

Get subdomain

Retrieve the workers.dev subdomain for your account.

const subdomain = await client.workers.subdomains.get({
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
});

Update subdomain

Configure the workers.dev subdomain.

const subdomain = await client.workers.subdomains.update({
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
  subdomain: 'my-subdomain',
});

Domains

Manage custom domains for Workers.

List domains

for await (const domain of client.workers.domains.list({
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
})) {
  console.log(domain);
}

Get domain

const domain = await client.workers.domains.get(
  domainId,
  { account_id: '023e105f4ecef8ad9ca31a8372d0c353' }
);

Account settings

Manage account-level Worker settings.

Get account settings

const settings = await client.workers.accountSettings.get({
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
});

Update account settings

const settings = await client.workers.accountSettings.update({
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
  default_usage_model: 'bundled',
});