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:

Permission Access level Why you need it
Workers Builds Configuration Edit Manage build settings and Previews, and work with builds
Workers Scripts Read Only needed to get your Worker tag

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.

Field Description
git_repository The repository to connect. branch is your production branch.
production_settings Build settings for pushes to your production branch
previews_enabled Whether pushes to other branches create or update Previews
previews_base_config Build settings copied to each new Preview. deploy_command is your Preview command.

production_settings and previews_base_config accept the same fields:

Field Type Description
build_command string Command to build your project (for example, npm run build)
deploy_command string Command to deploy your Worker (for example, npx wrangler deploy or npx wrangler preview)
build_token_uuid string UUID of the build token used to deploy your Worker
root_directory string Path to your project, relative to the repository root. Defaults to /.
path_includes array File path patterns that start a build
path_excludes array File path patterns that do not start a build
build_caching_enabled boolean Whether builds reuse cached dependencies and build artifacts. Defaults to true.
environment_variables object Build-time variables. Set is_secret to true to mask a value in build logs.

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
      }
    }
  }'

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}'
Field Description
preview_id Identifier of the Preview
branch Git branch the Preview tracks
auto_build Whether pushes to the branch build this Preview. Manual builds and Deploy Hooks run regardless.
auto_delete Whether deleting the Git branch also deletes this Preview

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
版本号 #2
由 壳壳虫 创建于 2026-11-01 05:33:48 UTC
由 壳壳虫 更新于 2026-11-01 05:33:50 UTC