Builds API reference

Last updated Sep 22, 2026 This guide shows you how to use the Workers Builds REST API to programmatically trigger builds, manage triggers, and monitor build status. 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 — install it if you do not have it already.

Before you start

1. Create an API token with the correct permissions

To use the Builds API, you need an API token to authenticate your requests. 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 Trigger builds, manage triggers, configure environment variables
Workers Scripts Read Only needed for one endpoint to retrieve your Worker's tag (documented as external_script_id)

Note

This API token is different from a build token. Build tokens are used by the build system to deploy your Worker — you will need a build token UUID when creating triggers. The API token described above is what you use to call the Builds API itself.

2. Worker tags (documented as external_script_id)

The Builds API identifies Workers by their tag, an immutable UUID assigned by Cloudflare. In API responses and parameters, this value appears as external_script_id.

Identifier Example Where it comes from
Worker name (id) my-worker The name you gave your Worker
Worker tag (external_script_id) 1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d Immutable UUID assigned by Cloudflare

Every Builds API endpoint that references a Worker requires the tag, not the name.

3. What is a trigger?

A trigger is a configuration that defines how your Worker gets built and deployed. It specifies the build command, deploy command, environment variables, and which branches should trigger builds. Each Worker has up to two triggers: one for production (runs on your production branch) and one for preview (runs on all other branches). To set up triggers, refer to Set up Workers Builds from scratch.

Trigger fields:

Field Type Description
trigger_name string Display name for the trigger
build_token_uuid string UUID of the build token used to deploy your Worker. Find this in your Worker's Settings > Builds > API token section, or via the GET /builds/tokens endpoint.
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)
root_directory string Path to your project root
branch_includes array Branch patterns that trigger builds (for example, ["main"] or ["*"])
branch_excludes array Branch patterns to exclude
path_includes array File path patterns that trigger builds
path_excludes array File path patterns to ignore
build_caching_enabled boolean Enable or disable build caching
environment_variables object Build-time variables specific to this trigger

Workflow overview

Most Builds API operations follow this pattern: first get your Worker's tag, then get the trigger UUID, then perform build operations.

Workflow overview: get Worker tag, then get trigger UUID, then perform build operations.

Step Action Endpoint
1 Get Worker tag GET /workers/scripts
2 Get trigger UUID GET /builds/workers/:worker_tag/triggers
3a Trigger a build POST /builds/triggers/:trigger_uuid/builds
3b List builds GET /builds/workers/:worker_tag/builds
3c Get build logs GET /builds/builds/:build_uuid/logs
3d Cancel a build PUT /builds/builds/:build_uuid/cancel

Step 1: Get your Worker tag

Call the Workers Scripts API to list all your Workers and find the tag for the Worker you want to work with:

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

Example output:

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

Save the tag value for your Worker. You will use it in all subsequent API calls.

Step 2: Get your trigger UUID

Use the GET /builds/workers/{tag}/triggers endpoint to list triggers for your Worker:

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/workers/{worker_tag}/triggers" \
  --header "Authorization: Bearer <API_TOKEN>" \
  | jq '.result[] | {trigger_uuid, trigger_name, branch_includes, branch_excludes}'

Example output:

{
  "trigger_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "trigger_name": "Deploy production",
  "branch_includes": ["main"],
  "branch_excludes": []
}
{
  "trigger_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "trigger_name": "Deploy preview builds",
  "branch_includes": ["*"],
  "branch_excludes": ["main"]
}

Save the trigger_uuid for the trigger you want to work with. Remember, you will have at most two triggers: one for your production branch (for example, main) that deploys to your live Worker, and optionally one for all other branches that creates preview deployments.

Step 3: Work with builds

Now that you have the Worker tag and trigger UUID, you can trigger builds, list build history, and get logs.

Trigger a manual build

Use the POST /builds/triggers/{uuid}/builds endpoint with the trigger_uuid from Step 2.

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

You must specify branch, commit_hash, or both:

Field Description
branch Git branch name to build (for example, main)
commit_hash Specific commit SHA to build. If provided without branch, builds the commit on its current branch.

The response includes the build_uuid which you can use to monitor the build.

List builds for a Worker

Use the GET /builds/workers/{tag}/builds endpoint with the worker_tag from Step 1.

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, branch, created_at}'

The response includes build_uuid for each build, which you need for getting logs or canceling builds.

Get build logs

Use the GET /builds/builds/{uuid}/logs endpoint. Get the build_uuid from:

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

Cancel a running build

Use the PUT /builds/builds/{uuid}/cancel endpoint. Get the build_uuid from:

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

Update trigger configuration

Use the PATCH /builds/triggers/{uuid} endpoint with the trigger_uuid from Step 2. You can update any of the trigger fields described in What is a trigger?.

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/triggers/{trigger_uuid}" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --header "Content-Type: application/json" \
  --request PATCH \
  --data '{
    "build_command": "npm run build:prod",
    "deploy_command": "npx wrangler deploy"
  }'

Manage build environment variables

Environment variables are set per trigger, meaning you can have different values for production and preview builds. For example, you might set NODE_ENV=production on your production trigger and NODE_ENV=development on your preview trigger. Refer to the environment variables API reference for full endpoint details.

Note

These are build-time environment variables, available only during the build process. For runtime environment variables, refer to Environment variables.

List environment variables

Use the trigger_uuid from Step 2.

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

Set environment variables

You can set different variables for each trigger. For example, to set production environment variables:

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/triggers/{production_trigger_uuid}/environment_variables" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --header "Content-Type: application/json" \
  --request PATCH \
  --data '{
    "NODE_ENV": {"value": "production", "is_secret": false},
    "API_KEY": {"value": "prod-secret-key", "is_secret": true}
  }'

And different values for preview builds:

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/triggers/{preview_trigger_uuid}/environment_variables" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --header "Content-Type: application/json" \
  --request PATCH \
  --data '{
    "NODE_ENV": {"value": "development", "is_secret": false},
    "API_KEY": {"value": "dev-secret-key", "is_secret": true}
  }'

Set is_secret to false for plain values and true for sensitive values that should be masked in logs.

Delete an environment variable

Use the trigger_uuid from Step 2. The variable_key is the key name you set (for example, NODE_ENV).

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/triggers/{trigger_uuid}/environment_variables/{variable_key}" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --request DELETE

Purge build cache

Use the POST /builds/triggers/{uuid}/purge_build_cache endpoint with the trigger_uuid from Step 2. This clears cached dependencies and build artifacts for that trigger.