buildkite-api

name: buildkite-api description: > This skill should be used when the user asks to "call the Buildkite API", "use the REST API", "write a GraphQL query", "set up webhooks", "automate Buildkite", "integrate with Buildkite programmatically", "write a script that calls Buildkite", "handle webhook events", "paginate API results", or "authenticate with the Buildkite API". Also use when the user mentions api.buildkite.com, graphql.buildkite.com, Buildkite REST endpoints, GraphQL mutations, webhook payloads, API tokens, or asks about programmatic access to Buildkite data.

Buildkite API

Buildkite exposes a REST API and a GraphQL API for programmatic automation, plus webhooks for event-driven integrations. Use the REST API for straightforward CRUD operations on builds, pipelines, and organizations. Use the GraphQL API for mutations (queue creation, template management, cluster operations) and when fetching nested or specific fields. Use webhooks to react to build and agent events in real time.

To execute API calls interactively from the terminal, see the buildkite-cli skill for bk api commands. To use the Buildkite MCP server for direct agent access to builds, logs, and pipelines, the MCP server exposes its own tool schemas — no API construction needed.

Quick Start

List builds for a pipeline using the REST API:

curl -sS -H "Authorization: Bearer $BUILDKITE_API_TOKEN" \
  "https://api.buildkite.com/v2/organizations/my-org/pipelines/my-pipeline/builds?per_page=5" | jq '.[].state'

Query the same data via GraphQL:

curl -sS -X POST "https://graphql.buildkite.com/v1" \
  -H "Authorization: Bearer $BUILDKITE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "{ pipeline(slug: \"my-org/my-pipeline\") { builds(first: 5) { edges { node { state message } } } } }"
  }' | jq '.data.pipeline.builds.edges[].node'

Authentication

Bearer Token

All API requests require a Buildkite API access token passed as a Bearer token:

curl -H "Authorization: Bearer $BUILDKITE_API_TOKEN" \
  "https://api.buildkite.com/v2/organizations"

Create tokens at Buildkite → Personal Settings → API Access Tokens. Each token is scoped to specific organizations and permissions.

Token Scopes

Grant the minimum scopes required. A CI automation script that only triggers builds needs write_builds and read_pipelines — nothing else.

JWT Authentication (Public Key)

For machine-to-machine integrations without long-lived tokens, sign RS256 JWTs with claims iss (API token UUID), iat (within 10 seconds of server time), and exp (within 5 minutes of iat). Register the public key in Buildkite, then use the JWT as a bearer token.

import jwt, time
now = int(time.time())
token = jwt.encode({"iss": "your-token-uuid", "iat": now, "exp": now + 300},
                   open("private_key.pem").read(), algorithm="RS256")
headers = {"Authorization": f"Bearer {token}"}

REST API

Base URL: https://api.buildkite.com/v2

All responses return JSON. Use Content-Type: application/json for request bodies.

Endpoint Reference

All endpoints are under /organizations/{org.slug}. Abbreviated as /{org} below.

Pagination

REST responses are paginated using HTTP Link headers:

Link: <https://api.buildkite.com/v2/organizations/my-org/builds?page=2&per_page=30>; rel="next",
      <https://api.buildkite.com/v2/organizations/my-org/builds?page=5&per_page=30>; rel="last"

Parse the Link header to follow rel="next" until no next link exists.

List Builds

# Filter by state and branch
curl -sS -H "Authorization: Bearer $BUILDKITE_API_TOKEN" \
  "https://api.buildkite.com/v2/organizations/my-org/pipelines/my-pipeline/builds?state=failed&branch=main"

Build list query parameters:

Create a Build

curl -sS -X POST "https://api.buildkite.com/v2/organizations/my-org/pipelines/my-pipeline/builds" \
  -H "Authorization: Bearer $BUILDKITE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "commit": "HEAD",
    "branch": "main",
    "message": "Triggered via API",
    "env": {
      "DEPLOY_TARGET": "staging"
    },
    "meta_data": {
      "triggered_by": "automation"
    }
  }'

Also supports author (object: name, email), pull_request_id, pull_request_base_branch, pull_request_repository.

Rebuild a Build

curl -sS -X PUT "https://api.buildkite.com/v2/organizations/my-org/pipelines/my-pipeline/builds/42/rebuild" \
  -H "Authorization: Bearer $BUILDKITE_API_TOKEN"

Cancel a Build

curl -sS -X PUT "https://api.buildkite.com/v2/organizations/my-org/pipelines/my-pipeline/builds/42/cancel" \
  -H "Authorization: Bearer $BUILDKITE_API_TOKEN"

Download Artifacts

Two-step process: list artifacts for a build, then download by artifact ID. The download endpoint returns a redirect — use -L to follow it:

curl -sS -L -H "Authorization: Bearer $BUILDKITE_API_TOKEN" \
  "https://api.buildkite.com/v2/organizations/my-org/pipelines/my-pipeline/builds/42/artifacts/$ARTIFACT_ID/download" \
  -o artifact.tar.gz

Create a Pipeline

curl -sS -X POST "https://api.buildkite.com/v2/organizations/my-org/pipelines" \
  -H "Authorization: Bearer $BUILDKITE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Pipeline",
    "repository": "git@github.com:my-org/my-repo.git",
    "steps": [{"type": "script", "name": "Test", "command": "make test"}],
    "default_branch": "main"
  }'

Error Handling

API errors return JSON with a message field.

GraphQL API

Endpoint: https://graphql.buildkite.com/v1. The GraphQL API supports queries and mutations with cursor-based pagination. Use it for operations not available in the REST API (cluster management, pipeline templates, complex mutations) and when fetching nested or specific fields to reduce response size.

For full query/mutation examples, pagination details, and introspection guidance, see references/graphql-reference.md.

REST vs GraphQL Decision Guide

Webhooks

Webhooks deliver HTTP POST requests to a specified URL when events occur in Buildkite. Use them for event-driven automation: failure notifications, auto-retry logic, deployment triggers, status dashboards. Configure via the REST API at /{org}/webhooks with a target URL, event subscriptions, and optional HMAC-SHA256 signature verification.

Most commonly used events: build.finished (react to build completion), job.finished (react to individual job results), build.failing (early failure notification). Agent events (agent.connected, agent.disconnected, etc.) and job lifecycle events are also available.

For webhook creation parameters, payload structure, HTTP headers, signature verification code, and a complete handler example, see references/webhooks.md.

Common Mistakes

Additional Resources

• references/graphql-reference.md — Full GraphQL query/mutation examples, pagination, introspection
• references/webhooks.md — Webhook creation, payload structure, signature verification, handler example
• references/patterns.md — Common API usage patterns: fetching failed builds, build success rates, triggering downstream pipelines

Further Reading

• Buildkite Docs for LLMs
• Buildkite REST API reference
• Buildkite GraphQL API documentation
• Buildkite GraphQL Explorer
• Buildkite Webhooks guide
• API authentication and token management