Builds API reference·续

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/triggers/{trigger_uuid}/purge_build_cache" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --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.

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 ↗︎.
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:

# Get your GitHub user/org ID
curl -s "https://api.github.com/users/<GITHUB_USERNAME>" | jq '.id'

# Get a repository ID
curl -s "https://api.github.com/repos/<GITHUB_USERNAME>/<REPO_NAME>" | jq '.id'

Step 2: Create a repository connection

Create a connection between your GitHub repository and Cloudflare:

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/repos/connections" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --header "Content-Type: application/json" \
  --request PUT \
  --data '{
    "provider_type": "github",
    "provider_account_id": "<GITHUB_USER_ID>",
    "provider_account_name": "<GITHUB_USERNAME>",
    "repo_id": "<GITHUB_REPO_ID>",
    "repo_name": "<REPO_NAME>"
  }'

Save the repo_connection_uuid from the response.

Step 3: Get your Worker tag

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/workers/scripts" \
  --header "Authorization: Bearer <API_TOKEN>" \
  | 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 ↗︎.
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:

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

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:

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/triggers" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --header "Content-Type: application/json" \
  --request POST \
  --data '{
    "external_script_id": "<WORKER_TAG>",
    "repo_connection_uuid": "<REPO_CONNECTION_UUID>",
    "build_token_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:

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/triggers" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --header "Content-Type: application/json" \
  --request POST \
  --data '{
    "external_script_id": "<WORKER_TAG>",
    "repo_connection_uuid": "<REPO_CONNECTION_UUID>",
    "build_token_uuid": "<BUILD_TOKEN_UUID>",
    "trigger_name": "Deploy preview branches",
    "build_command": "npm run build",
    "deploy_command": "npx wrangler preview",
    "root_directory": "/",
    "branch_includes": ["*"],
    "branch_excludes": ["main"],
    "path_includes": ["*"],
    "path_excludes": []
  }'

Note the different deploy_command: production uses wrangler deploy while preview uses wrangler preview to create Previews without affecting the live deployment.

Step 7: Set environment variables for each trigger

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

Set preview environment variables:

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

Step 8: Trigger your first build

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/triggers/{production_trigger_uuid}/builds" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --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.

Step 1: Get the active deployment's version ID

Use the GET /workers/scripts/{script_name}/deployments endpoint with the worker_name from Step 1:

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/workers/scripts/{worker_name}/deployments" \
  --header "Authorization: Bearer <API_TOKEN>" \
  | 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 endpoint with the version_id from the previous step:

curl -s "https://api.cloudflare.com/client/v4/accounts/{account_id}/builds/builds?version_ids={version_id}" \
  --header "Authorization: Bearer <API_TOKEN>" \
  | 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 endpoint with the values from the previous step:

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": "{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 to get your Worker tag.

For other build errors, refer to Troubleshooting builds.

Related resources

• Workers Builds REST API reference - Complete endpoint documentation
• Workers Scripts REST API reference - For retrieving Worker tags
• Workers Builds overview - Dashboard setup and configuration
• Build configuration - Build settings and options
• Create API token - How to create tokens with the correct permissions

Was this helpful?

YesNo

On this page

Docs

{"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/workers/ci-cd/builds/api-reference/#page","headline":"Builds API reference","description":"Learn how to programmatically trigger builds, manage triggers, and monitor your Workers Builds using the API.","url":"https://developers.cloudflare.com/workers/ci-cd/builds/api-reference/","inLanguage":"en","image":"https://developers.cloudflare.com/workers/ci-cd/builds/api-reference/og.png?v=953239305931e5fe","dateModified":"2026-09-22","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}}

description: Learn about the pull requests Workers Builds creates to configure your project or resolve issues. title: Automatic pull requests image: https://developers.cloudflare.com/workers/ci-cd/builds/automatic-prs/og.png?v=74e3558ea7009c6f

Skip to content

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.