Builds API reference

import { Aside } from "~/components";

This guide shows you how to use the Workers Builds REST API to connect a Worker to a Git repository, manage build settings and Previews, and monitor builds. The examples use curl commands that you can run directly in your terminal or adapt to your preferred programming language. Some examples pipe output through jq to filter JSON responses.

Before you start

Create an API token

The Builds API requires a user-scoped API token. Account-scoped tokens are not supported and will return "Invalid token" errors.

Create your token at dash.cloudflare.com/profile/api-tokens with the following permissions:

Get your Worker tag

The Builds API identifies Workers by their tag, an immutable ID assigned by Cloudflare, not by their name. In API requests and responses, this value appears as script_tag.

To find your Worker's tag, call the Workers Scripts API:

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/workers/scripts" \
  --header "Authorization: Bearer <API_TOKEN>" \
  | jq '.result[] | {name: .id, tag: .tag}'

{
	"name": "my-worker",
	"tag": "1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d"
}

Connect a Worker to a repository

One request connects your Worker to a repository and sets the build settings for your production branch and your Previews.

Prerequisites

1. Install the Cloudflare GitHub App. In the Cloudflare dashboard, go to Workers & Pages, select any Worker, and go to Settings > Builds > Connect. Select GitHub and authorize the app for your account or organization. You only need to do this once.

2. Get your GitHub account and repository IDs:

   curl -s "https://api.github.com/users/<GITHUB_USERNAME>" | jq '.id'
   curl -s "https://api.github.com/repos/<GITHUB_USERNAME>/<REPO_NAME>" | jq '.id'
   

3. Get a build token UUID. Select or create a build token in your Worker's Settings > Builds > API token, or list your build tokens with the GET /builds/tokens endpoint:

   curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/tokens" \
     --header "Authorization: Bearer <API_TOKEN>" \
     | jq '.result[] | {build_token_uuid, build_token_name}'
   

Create the build configuration

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/workers" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --header "Content-Type: application/json" \
  --request POST \
  --data '{
    "script_tag": "<WORKER_TAG>",
    "git_repository": {
      "provider_type": "github",
      "provider_account_id": "<GITHUB_USER_ID>",
      "provider_account_name": "<GITHUB_USERNAME>",
      "repo_id": "<GITHUB_REPO_ID>",
      "repo_name": "<REPO_NAME>",
      "branch": "main"
    },
    "production_settings": {
      "build_command": "npm run build",
      "deploy_command": "npx wrangler deploy",
      "build_token_uuid": "<BUILD_TOKEN_UUID>",
      "environment_variables": {
        "NODE_ENV": {"value": "production", "is_secret": false}
      }
    },
    "previews_enabled": true,
    "previews_base_config": {
      "build_command": "npm run build",
      "deploy_command": "npx wrangler preview",
      "build_token_uuid": "<BUILD_TOKEN_UUID>",
      "environment_variables": {
        "NODE_ENV": {"value": "development", "is_secret": false}
      }
    }
  }'

Pushes to main now deploy your Worker with wrangler deploy. Pushes to any other branch create or update a Preview with wrangler preview, without affecting your live deployment. To connect the Worker without Previews, set previews_enabled to false.

production_settings and previews_base_config accept the same fields:

View and update build settings

Get build settings

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/workers/{worker_tag}" \
  --header "Authorization: Bearer <API_TOKEN>"

The response has the same git_repository, production_settings, previews_enabled, and previews_base_config fields you set when creating the build configuration.

Update build settings

Send only the fields you want to change. For example, to change the production build command and add a Preview build variable:

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/workers/{worker_tag}" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --header "Content-Type: application/json" \
  --request PATCH \
  --data '{
    "production_settings": {
      "build_command": "npm run build:prod"
    },
    "previews_base_config": {
      "environment_variables": {
        "API_URL": {"value": "https://staging.example.com", "is_secret": false},
        "OLD_VARIABLE": null
      }
    }
  }'

• To delete an environment variable, set it to null.
• To change your production branch, send {"git_repository": {"branch": "<BRANCH_NAME>"}}.
• To turn Previews on or off, send {"previews_enabled": true} or {"previews_enabled": false}.
• Changes to previews_base_config apply to Previews created afterward. To also update every existing Preview, add ?patch_existing_previews=true to the URL.

Manage Previews

When Previews are enabled, the first push to a branch that is not your production branch creates a Preview for that branch. Each Preview gets its own copy of previews_base_config.

List Previews

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/workers/{worker_tag}/previews" \
  --header "Authorization: Bearer <API_TOKEN>" \
  | jq '.result[] | {preview_id, branch, auto_build, auto_delete}'

To get a single Preview and its build settings, send a GET request to /builds/workers/{worker_tag}/previews/{preview_id}.

Update a Preview

Send only the fields you want to change. For example, to stop pushes from building a Preview and change its build command:

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/workers/{worker_tag}/previews/{preview_id}" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --header "Content-Type: application/json" \
  --request PATCH \
  --data '{
    "auto_build": false,
    "settings": {
      "build_command": "npm run build:preview"
    }
  }'

Build a Preview

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/workers/{worker_tag}/previews/{preview_id}/builds" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --header "Content-Type: application/json" \
  --request POST \
  --data '{"branch": "feature-branch"}'

To list a Preview's builds, send a GET request to the same URL.

Work with builds

Start a production build

To start a production build without pushing a commit, create a Deploy Hook for your production branch and send a POST request to its URL.

List builds

Use the GET /builds/workers/{worker_tag}/builds endpoint:

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/workers/{worker_tag}/builds" \
  --header "Authorization: Bearer <API_TOKEN>" \
  | jq '.result[] | {build_uuid, status, build_outcome, branch: .build_trigger_metadata.branch, created_on}'

Builds older than 90 days are not returned. Refer to Limits & pricing.

Get build logs

Use the GET /builds/builds/{build_uuid}/logs endpoint with a build_uuid from List builds:

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/builds/{build_uuid}/logs" \
  --header "Authorization: Bearer <API_TOKEN>"

Build logs are retained for 90 days after the build finishes. To keep them longer, save the response.

Cancel a build

Use the PUT /builds/builds/{build_uuid}/cancel endpoint:

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/builds/{build_uuid}/cancel" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --request PUT

Related resources

• Workers Builds REST API reference - Complete endpoint documentation
• Build configuration - Build settings and options
• Previews - Branch-isolated previews of your Worker
• Deploy Hooks - Start builds from external systems
• Troubleshooting builds - Common Builds API errors