buildkite-api

What this skill does

# 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:

```bash
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:

```bash
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:

```bash
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

| Scope | Grants access to |
|-------|-----------------|
| `read_builds` / `write_builds` | List/inspect or create/cancel/retry builds |
| `read_pipelines` / `write_pipelines` | List/inspect or create/update/delete pipelines |
| `read_artifacts` / `write_artifacts` | Download or upload/delete artifacts |
| `read_build_logs` / `write_build_logs` | Read or delete job log output |
| `read_agents` / `write_agents` | List/inspect or stop/manage agents |
| `read_organizations` | List organizations |
| `read_teams` | List teams and memberships |
| `read_job_env` | Retrieve job environment variables |
| `read_user` | Inspect the authenticated user |
| `read_clusters` / `write_clusters` | List/inspect or manage clusters and queues |
| `read_suites` / `write_suites` | List/inspect or manage Test Engine suites |
| `read_registries` / `write_registries` | List/inspect or manage package registries |

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.

```python
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.

| Resource | Endpoint | Methods | Scope |
|----------|----------|---------|-------|
| Organizations | `/organizations` | GET | `read_organizations` |
| Pipelines | `/{org}/pipelines` | GET, POST | `read_pipelines`, `write_pipelines` |
| Pipeline | `/{org}/pipelines/{slug}` | GET, PUT, PATCH, DELETE | `read_pipelines`, `write_pipelines` |
| Builds (org) | `/{org}/builds` | GET | `read_builds` |
| Builds (pipeline) | `/{org}/pipelines/{slug}/builds` | GET, POST | `read_builds`, `write_builds` |
| Build | `/{org}/pipelines/{slug}/builds/{num}` | GET | `read_builds` |
| Jobs | `/{org}/pipelines/{slug}/builds/{num}/jobs` | GET | `read_builds` |
| Job log | `/{org}/pipelines/{slug}/builds/{num}/jobs/{id}/log` | GET, DELETE | `read_build_logs` |
| Job env | `/{org}/pipelines/{slug}/builds/{num}/jobs/{id}/env` | GET | `read_job_env` |
| Artifacts (build) | `/{org}/pipelines/{slug}/builds/{num}/artifacts` | GET | `read_artifacts` |
| Artifact download | `/{org}/pipelines/{slug}/builds/{num}/artifacts/{id}/download` | GET | `read_artifacts` |
| Annotations | `/{org}/pipelines/{slug}/builds/{num}/annotations` | GET | `read_builds` |
| Agents | `/{org}/agents` | GET | `read_agents` |
| Agent tokens | `/{org}/agent-tokens` | GET, POST | `read_agents`, `write_agents` |
| Members | `/{org}/members` | GET | `read_organizations` |
| Webhooks | `/{org}/webhooks` | GET, POST | — |

### 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"
```

| Parameter | Default | Max | Description |
|-----------|---------|-----|-------------|
| `page` | `1` | — | Page number |
| `per_page` | `30` | `100` | Results per page |

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

### List Builds

```bash
# 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:

| Parameter | Description | Example |
|-----------|-------------|---------|
| `state` | Filter: `running`, `scheduled`, `passed`, `failed`, `blocked`, `canceled`, `skipped`, `finished` | `state=failed` |
| `state[]` | Multiple states | `state[]=running&state[]=scheduled` |
| `branch` | Branch name | `branch=main` |
| `commit` | Commit SHA | `commit=abc123` |
| `created_from` | Builds after (ISO 8601) | `created_from=2024-01-01T00:00:00Z` |
| `created_to` | Builds before (ISO 8601) | `created_to=2024-12-31T23:59:59Z` |
| `include_retried_jobs` | Include retried executions | `include_retried_jobs=true` |
| `meta_data` | Filter by metadata | `meta_data[deploy]=true` |

### Create a Build

```bash
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"
    }
  }'
```

| Field | Required | Description |
|-------|----------|-------------|
| `commit` | Yes | Git ref, SHA, or `HEAD` |
| `branch` | Yes | Branch name |
| `message` | No | Build message (defaults to commit message) |
| `env` | No | Environment variables (object) |
| `meta_data` | No | Build metadata (object) — accessible via `buildkite-agent meta-data` |
| `clean_checkout` | No | Force clean checkout (`true`/`false`) |
| `ignore_pipeline_branch_filters` | No | Skip branch filtering rules |

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

### Rebuild a Build

```bash
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

```bash
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:

```b