导航|地址|刷新
Builds API reference

Skip to contentDocumentation 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.



DocsDirectoryAPISDKsChangelog

Search

Log in






Workers

/




Overview


Getting started


CLI

Dashboard

Prompting

Templates





Examples

Tutorials


Best practices


Workers Best Practices






Demos and architectures


Overview

Build an Interactive ChatGPT App






Local development


Overview

Environment variables and secrets

Vite Plugin ↗

Choosing between Wrangler & Vite

Developing with multiple Workers

Adding local data

Supported bindings per development mode

Local Explorer

Share a local dev server





Playground


Configuration


Overview


Workers Sites


Overview

Start from existing

Start from scratch

Start from Worker

Workers Sites configuration





Bindings ↗

Compatibility dates

Compatibility flags

Cron Triggers

Environment variables


Integrations


Overview

APIs

External Services





Multipart upload metadata

Page Rules

PlacementBeta


Routes and domains


Overview

Custom Domains

Routes

workers.dev





Secrets






Versions & deployments


Overview

Deployment management

Preview URLs


Gradual deployments


Overview

Version affinity

With Durable Objects





Version overrides

Rollbacks






CI/CD


Overview


Builds


Overview

Configuration

Automatic pull requests


Git integration


Overview

GitHub integration

GitLab integration





Build image

Build caching

Build branches

Build watch paths

Deploy Hooks

Advanced setups

Event subscriptions

Troubleshooting builds

Builds API reference

Limits & pricing

MCP serverMCP






External CI/CD


Overview

GitHub Actions

GitLab CI/CD










Workers Cache


Overview

Configuration

Cache keys

Purging the cache

Examples

Debugging

Limitations






Runtime APIs


Overview


Remote-procedure call (RPC)


Overview

Lifecycle

Reserved Methods

Visibility and Security Model

TypeScript

Error handling






WebAssembly (Wasm)


Overview

Wasm in JavaScript






Bindings (env)


Overview

AI ↗

Analytics Engine ↗

Assets ↗

Browser Run ↗

D1 ↗

Dispatcher (Workers for Platforms) ↗

Durable Objects ↗

Dynamic Worker Loaders

Environment Variables ↗

Hyperdrive ↗

Images ↗

KV ↗

Media Transformations ↗

mTLS

Queues ↗

R2 ↗

Rate Limiting

Secrets ↗

Secrets Store ↗Beta


Service bindings


Overview

HTTP

RPC (WorkerEntrypoint)





Stream ↗

Vectorize ↗

Version metadataBeta

Workflows ↗





Cache

Console

Context (ctx)

Encoding

EventSource

Fetch


Handlers


Overview

Alarm Handler ↗

Email Handler ↗

Fetch Handler

Queue Handler ↗

Scheduled Handler

Tail Handler





Headers

HTMLRewriter

MessageChannel


Node.js compatibility


Overview

assert

AsyncLocalStorage

Buffer

crypto

Diagnostics Channel

dns

EventEmitter

fs

http

https

net

path

process

Streams

StringDecoder

test

timers

tls

url

util

zlib





Performance and timers

Request

Response

Scheduler


Streams


Overview

ReadableStream

ReadableStream BYOBReader

ReadableStream DefaultReader

TransformStream

WritableStream

WritableStream DefaultWriter





TCP sockets

Web Crypto

Web standards

WebSockets






Static Assets


Overview

Get Started

Configuration and Bindings


Routing


Full-stack application

Single Page Application (SPA)

Static Site Generation (SSG) and custom 404 pages

Worker script


Advanced


Gradual rollouts ↗

HTML handling

Serving a subdirectory









Headers

Redirects

Direct Uploads

Billing and Limitations


Migration Guides


Migrate from Pages to Workers

Migrate from Netlify to Workers

Migrate from Vercel to Workers










Framework guides


Deploy an existing project


Web applications


React + Vite

Astro

React Router (formerly Remix)

Next.js

Vue

RedwoodSDK

TanStack Start

Microfrontends

SvelteKit

Vike


More guides...


Analog

Angular

Docusaurus

Gatsby

Hono

Nuxt

Qwik

SolidBeta

Waku










Mobile applications


Expo






APIs


FastAPI ↗

Hono ↗






AI & agents


Agents SDK ↗

LangChain ↗










Databases


Connect to databases

Analytics Engine ↗

Vectorize (vector database) ↗

Cloudflare D1 ↗

Hyperdrive ↗


3rd Party Integrations


Overview

Neon

PlanetScale

Supabase

Turso

Upstash

Xata










Testing


Overview


Vitest integration


Overview

Write your first test

Recipes and examples

Configuration

Test APIs

Isolation and concurrency

Debugging

Known issues


Migration guides


Migrate from Vitest 3 to Vitest 4

Migrate from Miniflare 2's test environments

Migrate from unstable_dev










Integration test harness


Overview

Get started

Configure the test harness

Prepare test state

Interact with Workers

Integrations






Miniflare


Overview

Get Started

Writing tests


Core


Compatibility Dates

Fetch Events

Modules

Multiple Workers

Queues

Scheduled Events

Variables and Secrets

Web Standards

WebSockets






Developing


Attaching a Debugger

Live Reload






Migrations


Migrating from Version 2






Storage


Cache

D1

Durable Objects

KV

R2









Wrangler's unstable_startWorker()






Observability


Overview

Metrics and analytics


Logs


Overview

Workers Logs

Real-time logs

Tail Workers

Workers Logpush






TracesBeta


Overview

Custom spansBeta

Spans and attributes

Known limitations






DevTools


Overview

Breakpoints

Profiling CPU usage

Profiling Memory





Query Builder


Exporting OpenTelemetry Data


Overview

Export to Honeycomb

Export to Grafana Cloud

Export to Axiom

Export to Sentry

Export to PostHog





MCP serverMCP

Errors and exceptions


Integrations


Sentry





Source maps and stack traces






Wrangler


Overview

Install/Update Wrangler


Migrations


Migrate from Wrangler v3 to v4

Migrate from Wrangler v2 to v3


Migrate from Wrangler v1 to v2



Wrangler v1 (legacy)


Overview

Install / Update

Authentication

Commands

Configuration

Webpack





1. Migrate webpack projects

2. Update to Wrangler v2









API


Commands


Overview

Workers

General commands

Artifacts

Browser

Certificates

Containers

D1

Flagship

Hyperdrive

KV

Pages

Pipelines

Queues

R2

Secrets Store

Tunnel

Vectorize

VPC

Workers for Platforms

Workflows





Authentication profiles

Bundling

Configuration

Custom builds

Deprecations

Environments

System environment variables






Vite plugin


Overview

Get started

Tutorial - React SPA with an API


Reference


API

Static Assets

Debugging

Migrating from wrangler dev

Secrets

Vite Environments

Cloudflare Environments

Non-JavaScript modules

Programmatic configuration










Languages


Overview


JavaScript


Overview

Examples ↗






TypeScript


Overview

Examples ↗






Python WorkersBeta


Overview

The Basics

How Python Workers Work

Foreign Function Interface (FFI)

Standard Library

Examples


Packages


Overview

FastAPI

Langchain










RustBeta


Overview

Supported crates










Platform


Overview

Pricing


Changelog


Overview

Workers (Historic)

Wrangler





Limits

Choose a data or storage product

Betas

Deploy to Cloudflare buttons

Claim deployments (temporary accounts)

Built with Cloudflare button

Known issues

Workers for Platforms ↗

Infrastructure as Code (IaC)





Glossary


Reference


How the Cache works

How Workers works

Migrate from Service Workers to ES Modules

Protocols

Security model






Agent resources


Agent setup ↗

Cloudflare Skills ↗

Code Mode MCP Server ↗

Domain-specific MCP Servers ↗MCP

Workers llms.txt ↗

Workers llms-full.txt ↗

Cloudflare Docs llms.txt ↗

Cloudflare Docs llms-full.txt ↗













Home

/Workers

/…
CI/CD


/Builds

/Builds API reference



Builds API reference


Last updated May 29, 2026|Copy as Markdown|View as Markdown|Agent setup

OverviewBefore you start 1. Create an API token with the correct permissions 2. Worker tags (documented as external_script_id) 3. What is a trigger?Workflow overviewStep 1: Get your Worker tagStep 2: Get your trigger UUIDStep 3: Work with builds Trigger a manual build List builds for a Worker Get build logs Cancel a running buildUpdate trigger configurationManage build environment variables List environment variables Set environment variables Delete an environment variablePurge build cacheExamples Set up Workers Builds from scratch Redeploy current deploymentTroubleshooting "Resource not found" errorRelated resources




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	…(内容过长已截断)

------
导航页 打开网址