--- title: Builds API reference description: Learn how to programmatically trigger builds, manage triggers, and monitor your Workers Builds using the API. image: https://developers.cloudflare.com/dev-products-preview.png --- > Documentation Index > Fetch the complete documentation index at: https://developers.cloudflare.com/workers/llms.txt > Use this file to discover all available pages before exploring further. [Skip to content](#%5Ftop) # Builds API reference This guide shows you how to use the [Workers Builds REST API](https://developers.cloudflare.com/api/resources/workers%5Fbuilds/) 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 ↗](https://jqlang.org/) 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 ↗](https://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](#step-1-get-your-worker-tag) to retrieve your Worker's tag (documented as [external\_script\_id](#2-worker-tags-documented-as-external%5Fscript%5Fid)) | 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](#step-4-get-your-build-token-uuid). 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](https://developers.cloudflare.com/workers/ci-cd/builds/build-branches/#change-production-branch)) and one for preview (runs on all other branches). To set up triggers, refer to [Set up Workers Builds from scratch](#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](https://developers.cloudflare.com/api/resources/workers%5Fbuilds/subresources/build%5Ftokens/methods/list/) 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.](https://developers.cloudflare.com/_astro/workflow-overview.D-gY5w1T_2n0lJ2.svg) | 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](https://developers.cloudflare.com/api/resources/workers/subresources/scripts/methods/list/) to list all your Workers and find the `tag` for the Worker you want to work with: Terminal window ``` curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/workers/scripts" \ --header "Authorization: Bearer " \ | 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](https://developers.cloudflare.com/api/resources/workers%5Fbuilds/subresources/triggers/methods/list/) endpoint to list triggers for your Worker: Terminal window ``` curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/workers/{worker_tag}/triggers" \ --header "Authorization: Bearer " \ | 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 non-production branches", "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](https://developers.cloudflare.com/api/resources/workers%5Fbuilds/subresources/builds/methods/create/) endpoint with the `trigger_uuid` from [Step 2](#step-2-get-your-trigger-uuid). Terminal window ``` curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/triggers/{trigger_uuid}/builds" \ --header "Authorization: Bearer " \ --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](https://developers.cloudflare.com/api/resources/workers%5Fbuilds/subresources/builds/methods/list/) endpoint with the `worker_tag` from [Step 1](#step-1-get-your-worker-tag). Terminal window ``` curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/workers/{worker_tag}/builds" \ --header "Authorization: Bearer " \ | 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](https://developers.cloudflare.com/api/resources/workers%5Fbuilds/subresources/builds/methods/get%5Flogs/) endpoint. Get the `build_uuid` from: * [List builds](#list-builds-for-a-worker) * The response when [triggering a build](#trigger-a-manual-build) * [Get latest builds by script IDs](https://developers.cloudflare.com/api/resources/workers%5Fbuilds/subresources/builds/methods/get%5Flatest%5Fby%5Fscript%5Fids/) * The last segment of the URL on your build details page in the dashboard Terminal window ``` curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/builds/{build_uuid}/logs" \ --header "Authorization: Bearer " ``` ### Cancel a running build Use the [PUT /builds/builds/{uuid}/cancel](https://developers.cloudflare.com/api/resources/workers%5Fbuilds/subresources/builds/methods/cancel/) endpoint. Get the `build_uuid` from: * [List builds](#list-builds-for-a-worker) * The response when [triggering a build](#trigger-a-manual-build) * [Get latest builds by script IDs](https://developers.cloudflare.com/api/resources/workers%5Fbuilds/subresources/builds/methods/get%5Flatest%5Fby%5Fscript%5Fids/) * The last segment of the URL on your build details page in the dashboard Terminal window ``` curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/builds/{build_uuid}/cancel" \ --header "Authorization: Bearer " \ --request PUT ``` ## Update trigger configuration Use the [PATCH /builds/triggers/{uuid}](https://developers.cloudflare.com/api/resources/workers%5Fbuilds/subresources/triggers/methods/update/) endpoint with the `trigger_uuid` from [Step 2](#step-2-get-your-trigger-uuid). You can update any of the trigger fields described in [What is a trigger?](#3-what-is-a-trigger). Terminal window ``` curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/triggers/{trigger_uuid}" \ --header "Authorization: Bearer " \ --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](https://developers.cloudflare.com/api/resources/workers%5Fbuilds/subresources/triggers/subresources/environment%5Fvariables/) 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](https://developers.cloudflare.com/workers/configuration/environment-variables/). ### List environment variables Use the `trigger_uuid` from [Step 2](#step-2-get-your-trigger-uuid). Terminal window ``` curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/triggers/{trigger_uuid}/environment_variables" \ --header "Authorization: Bearer " ``` ### Set environment variables You can set different variables for each trigger. For example, to set production environment variables: Terminal window ``` curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/triggers/{production_trigger_uuid}/environment_variables" \ --header "Authorization: Bearer " \ --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: Terminal window ``` curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/triggers/{preview_trigger_uuid}/environment_variables" \ --header "Authorization: Bearer " \ --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](#step-2-get-your-trigger-uuid). The `variable_key` is the key name you set (for example, `NODE_ENV`). Terminal window ``` curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/triggers/{trigger_uuid}/environment_variables/{variable_key}" \ --header "Authorization: Bearer " \ --request DELETE ``` ## Purge build cache Use the [POST /builds/triggers/{uuid}/purge\_build\_cache](https://developers.cloudflare.com/api/resources/workers%5Fbuilds/subresources/triggers/methods/purge%5Fbuild%5Fcache/) endpoint with the `trigger_uuid` from [Step 2](#step-2-get-your-trigger-uuid). This clears cached dependencies and build artifacts for that trigger. Terminal window ``` curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/triggers/{trigger_uuid}/purge_build_cache" \ --header "Authorization: Bearer " \ --request POST ``` ## Examples The following examples show common use cases for the Builds API. ### Set up Workers Builds from scratch This example walks through the complete process of connecting a GitHub repository to a Worker and setting up automated builds using only the API. ![Setup flow: get GitHub IDs, create repo connection, get Worker tag, create triggers, set env variables, trigger first build.](https://developers.cloudflare.com/_astro/setup-from-scratch.BUpowztp_1X7alF.svg) | Step | Action | Endpoint | | ---- | --------------------------- | ------------------------------------------------------------- | | 1 | Get GitHub account/repo IDs | GET api.github.com/users/... and GET api.github.com/repos/... | | 2 | Create repo connection | PUT /builds/repos/connections | | 3 | Get Worker tag | GET /workers/scripts | | 4 | Get build token UUID | GET /builds/tokens | | 5a | Create production trigger | POST /builds/triggers | | 5b | Create preview trigger | POST /builds/triggers | | 6 | Set environment variables | PATCH /builds/triggers/:trigger\_uuid/environment\_variables | | 7 | Trigger first build | POST /builds/triggers/:trigger\_uuid/builds | #### Prerequisites Before using the API, you must first install the Cloudflare GitHub App through the dashboard: 1. Go to **Workers & Pages** in the [Cloudflare dashboard ↗](https://dash.cloudflare.com). 2. Select any Worker and go to **Settings** \> **Builds** \> **Connect**. 3. Select **GitHub** and authorize the Cloudflare GitHub App for your account or organization. This one-time setup creates the connection between your GitHub account and Cloudflare. Once complete, you can use the API for everything else. #### Step 1: Get your GitHub account information After installing the GitHub App, you need your GitHub account ID and repository ID. You can find these from an existing trigger or from the GitHub API. From GitHub's API: Terminal window ``` # Get your GitHub user/org ID curl -s "https://api.github.com/users/" | jq '.id' # Get a repository ID curl -s "https://api.github.com/repos//" | jq '.id' ``` #### Step 2: Create a repository connection Create a connection between your GitHub repository and Cloudflare: Terminal window ``` curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/repos/connections" \ --header "Authorization: Bearer " \ --header "Content-Type: application/json" \ --request PUT \ --data '{ "provider_type": "github", "provider_account_id": "", "provider_account_name": "", "repo_id": "", "repo_name": "" }' ``` Save the `repo_connection_uuid` from the response. #### Step 3: Get your Worker tag Terminal window ``` curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/workers/scripts" \ --header "Authorization: Bearer " \ | jq '.result[] | {name: .id, tag: .tag}' ``` #### Step 4: Get your build token UUID A build token authorizes the build system to deploy your Worker. To get your build token UUID: 1. Go to your Worker in the [Cloudflare dashboard ↗](https://dash.cloudflare.com). 2. Navigate to **Settings** \> **Builds** \> **API token**. 3. Select an existing build token or create a new one. You can also list your build tokens via the API: Terminal window ``` curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/tokens" \ --header "Authorization: Bearer " \ | jq '.result[] | {build_token_uuid, build_token_name}' ``` Save the `build_token_uuid` for the next step. #### Step 5: Create a production trigger Create a trigger that deploys when you push to `main`: Terminal window ``` curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/triggers" \ --header "Authorization: Bearer " \ --header "Content-Type: application/json" \ --request POST \ --data '{ "external_script_id": "", "repo_connection_uuid": "", "build_token_uuid": "", "trigger_name": "Deploy production", "build_command": "npm run build", "deploy_command": "npx wrangler deploy", "root_directory": "/", "branch_includes": ["main"], "branch_excludes": [], "path_includes": ["*"], "path_excludes": [] }' ``` #### Step 6: Create a preview trigger (optional) Create a second trigger for preview deployments on all other branches: Terminal window ``` curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/triggers" \ --header "Authorization: Bearer " \ --header "Content-Type: application/json" \ --request POST \ --data '{ "external_script_id": "", "repo_connection_uuid": "", "build_token_uuid": "", "trigger_name": "Deploy preview branches", "build_command": "npm run build", "deploy_command": "npx wrangler versions upload", "root_directory": "/", "branch_includes": ["*"], "branch_excludes": ["main"], "path_includes": ["*"], "path_excludes": [] }' ``` Note the different `deploy_command`: production uses `wrangler deploy` while preview uses `wrangler versions upload` to create preview URLs without affecting the live deployment. #### Step 7: Set environment variables for each trigger Set production environment variables: Terminal window ``` curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/triggers/{production_trigger_uuid}/environment_variables" \ --header "Authorization: Bearer " \ --header "Content-Type: application/json" \ --request PATCH \ --data '{ "NODE_ENV": {"value": "production", "is_secret": false} }' ``` Set preview environment variables: Terminal window ``` curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/triggers/{preview_trigger_uuid}/environment_variables" \ --header "Authorization: Bearer " \ --header "Content-Type: application/json" \ --request PATCH \ --data '{ "NODE_ENV": {"value": "development", "is_secret": false} }' ``` #### Step 8: Trigger your first build Terminal window ``` curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/triggers/{production_trigger_uuid}/builds" \ --header "Authorization: Bearer " \ --header "Content-Type: application/json" \ --request POST \ --data '{"branch": "main"}' ``` Your Worker is now connected to GitHub. Future pushes to `main` will automatically trigger production deployments, and pushes to other branches will create preview deployments. ### Redeploy current deployment Redeploy your current active deployment to refresh build-time data. This is useful when you need to rebuild without code changes. ![Redeploy flow: get active deployment, find the build for that version, retrigger with same branch and commit.](https://developers.cloudflare.com/_astro/redeploy-flow.WidssEDb_Z1MmgGB.svg) | Step | Action | Endpoint | | ---- | --------------------------------- | ---------------------------------------------- | | 1 | Get active deployment | GET /workers/scripts/:worker\_name/deployments | | 2 | Find the build for that version | GET /builds/builds?version\_ids=:version\_id | | 3 | Retrigger with same branch/commit | POST /builds/triggers/:trigger\_uuid/builds | **Step 1: Get the active deployment's version ID** Use the [GET /workers/scripts/{script\_name}/deployments](https://developers.cloudflare.com/api/resources/workers/subresources/scripts/subresources/deployments/methods/list/) endpoint with the `worker_name` from [Step 1](#step-1-get-your-worker-tag): Terminal window ``` curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/workers/scripts/{worker_name}/deployments" \ --header "Authorization: Bearer " \ | jq '.result.deployments[0].versions[0].version_id' ``` Save the `version_id` from the output. **Step 2: Find the build for that version** Use the [GET /builds/builds](https://developers.cloudflare.com/api/resources/workers%5Fbuilds/subresources/builds/methods/get%5Fby%5Fversion%5Fids/) endpoint with the `version_id` from the previous step: Terminal window ``` curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/builds?version_ids={version_id}" \ --header "Authorization: Bearer " \ | jq '.result.builds' ``` From the response, note the `trigger.trigger_uuid`, `build_trigger_metadata.branch`, and `build_trigger_metadata.commit_hash`. **Step 3: Retrigger with the same branch and commit** Use the [POST /builds/triggers/{uuid}/builds](https://developers.cloudflare.com/api/resources/workers%5Fbuilds/subresources/builds/methods/create/) endpoint with the values from the previous step: Terminal window ``` curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/triggers/{trigger_uuid}/builds" \ --header "Authorization: Bearer " \ --header "Content-Type: application/json" \ --request POST \ --data '{ "branch": "{branch}", "commit_hash": "{commit_hash}" }' Passing both `branch` and `commit_hash` pins the build to that exact commit on that branch. ``` ## Troubleshooting ### "Resource not found" error You are likely using the Worker name instead of the Worker tag. The Builds API requires the `tag` (a UUID like `1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d`), not the Worker name. Refer to [Step 1](#step-1-get-your-worker-tag) to get your Worker tag. For other build errors, refer to [Troubleshooting builds](https://developers.cloudflare.com/workers/ci-cd/builds/troubleshoot/). ## Related resources * [Workers Builds REST API reference](https://developers.cloudflare.com/api/resources/workers%5Fbuilds/) \- Complete endpoint documentation * [Workers Scripts REST API reference](https://developers.cloudflare.com/api/resources/workers/subresources/scripts/) \- For retrieving Worker tags * [Workers Builds overview](https://developers.cloudflare.com/workers/ci-cd/builds/) \- Dashboard setup and configuration * [Build configuration](https://developers.cloudflare.com/workers/ci-cd/builds/configuration/) \- Build settings and options * [Create API token](https://developers.cloudflare.com/fundamentals/api/get-started/create-token/) \- How to create tokens with the correct permissions ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/workers/","name":"Workers"}},{"@type":"ListItem","position":3,"item":{"@id":"/workers/ci-cd/","name":"CI/CD"}},{"@type":"ListItem","position":4,"item":{"@id":"/workers/ci-cd/builds/","name":"Builds"}},{"@type":"ListItem","position":5,"item":{"@id":"/workers/ci-cd/builds/api-reference/","name":"Builds API reference"}}]} ```