Create a Buildkite build via the Buildkite REST API
domain: buildkite.com/docs · 5 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
Steps
Generate a Buildkite API access token under Personal Settings > API Access Tokens with 'Write Builds' and 'Read Builds' scopes
POST to 'https://api.buildkite.com/v2/organizations/{org-slug}/pipelines/{pipeline-slug}/builds' with Authorization header 'Bearer YOUR_TOKEN'
Include a JSON body with 'commit' (SHA or 'HEAD'), 'branch', and optionally 'message', 'env' (object of environment variables), and 'meta_data' (object of key-value strings)
The response includes the build 'number' and 'url'; poll GET '/v2/organizations/{org}/pipelines/{pipeline}/builds/{build-number}' checking 'state' for 'passed', 'failed', or 'canceled'
Retrieve individual job states via the 'jobs' array in the build response to identify which step failed
Known gotchas
Environment variables set via the API 'env' field are visible to all steps; avoid passing secrets this way — use Buildkite's secrets manager or agent environment hooks instead
The 'commit' field accepts 'HEAD' to build the branch tip, but the actual SHA used is resolved at agent checkout time, which may differ if commits are pushed between trigger and checkout
Buildkite enforces rate limits per token; bulk triggering many builds quickly may result in 429 responses requiring retry with backoff
Give your agent this knowledge — and 15,500+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?