Buildkite APIs

Authentication

The Buildkite REST and GraphQL APIs expect an access token to be provided using the Authorization HTTP header:

curl -H "Authorization: Bearer $TOKEN" https://api.buildkite.com/v2/user

Generate an access token.

If you are implementing Buildkite webhooks, all webhooks for Pipelines and Package Registries contain an X-Buildkite-Token header which allows you to verify the authenticity of the request.

Managing API access tokens

Learn more about how to manage Buildkite's API access tokens in Managing API access tokens, which covers the following topics:

The scopes which can be assigned to API access tokens.
Auditing token usage.
Removing Buildkite organization access to tokens.
Limiting a token's access by IP address.
A token's lifecycle characteristics.
Managing a token's security, including token rotation and GitHub's secret scanning program.

REST API

The Buildkite REST API aims to give you complete programmatic access and control of Buildkite to extend, integrate and automate anything to suit your particular needs.

Generate an API access token with as much scope as you need.
Make requests to https://api.buildkite.com using the token you generated in the Authorization header:
```
curl -H "Authorization: Bearer $TOKEN" https://api.buildkite.com/v2/user
```

Learn more about Buildkite's REST API in the REST API overview.

GraphQL

The Buildkite GraphQL API provides an alternative to the REST API. The GraphQL API allows for more efficient retrieval of data by enabling you to fetch multiple, nested resources in a single request.

You can access the GraphQL API through the GraphQL console (see the GraphQL overview page > Getting started section for more information), as well as at the command line (see the Console and CLI tutorial page for more information). For command line access, you'll need a Buildkite API access token with the Enable GraphQL API Access permission selected.

Learn more about:

Buildkite's GraphQL API in the GraphQL API overview and Console and CLI tutorial pages.
The differences between Buildkite's REST and GraphQL APIs in API differences.

Portals

Buildkite's portals provide an alternative to the REST and GraphQL APIs. Portals allow Buildkite organization administrators to define custom GraphQL operations, which can then be accessed through an authenticated URL endpoint by other members of the Buildkite organization.

Learn more about the portals feature in Portals.

MCP server

Buildkite provides both remote and local MCP servers, which provide your AI tools with access to Buildkite's REST API features.

Learn more about the Buildkite MCP server from the MCP server overview page.

Webhooks

Buildkite's webhooks allow your third-party applications and systems to monitor and respond to events within your Buildkite organization, providing a real time view of activity and allowing you to extend and integrate Buildkite into these systems.

For Pipelines, webhooks can be added and configured on your Buildkite organization's Notification Services settings page.

For Test Engine and Package Registries, webhooks can be configured through their specific test suites and registries, respectively.

Learn more about Buildkite's webhooks from the Webhooks overview page.