At a glance
- Availability: Experimental (how to enable).
- Auth: API key.
- Connection: The key comes from
BUILDKITE_API_TOKEN. - Docs: https://buildkite.com/docs/apis/rest-api
Credentials
Set these per environment. See Connect an integration.| Variable | Required | Description |
|---|---|---|
BUILDKITE_API_TOKEN | Yes | Buildkite API access token with read_pipelines and read_builds scopes (write_builds to trigger builds) Docs. |
Setup
- Sign in to Buildkite: Use an existing organization or create one at https://buildkite.com - free plans include API access. You need at least one pipeline to query builds.
- Create an API access token: Go to https://buildkite.com/user/api-access-tokens, create a token scoped to your organization, and enable the read_pipelines, read_builds, and read_organizations REST scopes. Add write_builds if you want to trigger builds.
- Set the environment variable: Add the token to your .env as BUILDKITE_API_TOKEN=…
- Verify access: Run List Organizations, then List Pipelines with your organization slug.
- Requests authenticate with ‘Authorization: Bearer <token>’ against https://api.buildkite.com/v2
- API tokens are scoped per organization and per REST scope - missing scopes return 403
- Pagination uses page and per_page query parameters (max 100 per page)
Tools
| Tool | Access | Description |
|---|---|---|
| List Organizations | Read | List Buildkite organizations the token can access |
| List Pipelines | Read | List pipelines in an organization |
| Get Pipeline | Read | Get a pipeline’s configuration and build stats |
| List Builds | Read | List builds for a pipeline, optionally filtered by branch or state |
| Get Build | Read | Get a build including its jobs and their states |
| Create Build | Write | Trigger a new build on a pipeline |
Example prompts
- List the failed Buildkite builds on my main pipeline from today and summarize the commit messages.
- Trigger a new Buildkite build of HEAD on the main branch of my pipeline.