Buildkite APIs

The Buildkite APIs documentation contains docs for all API-related features of Buildkite available across Buildkite Pipelines, Test Engine, and Package Registries.

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.

Managing API access tokens

Learn more about Buildkite's API access tokens and how to manage them 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.

Webhook authentication

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.

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. Using the Buildkite REST API is as easy as:

Ensuring you have generated an API access token with as many scopes as you require.
Making requests to https://api.buildkite.com using the token you generated in the Authorization header, for example:
```
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

In the absence of configurable scope restrictions on API access tokens for the GraphQL API, the portals feature provides a mechanism to restrict access to the Buildkite platform through the GraphQL API. Portals are GraphQL-based operations, which are stored by Buildkite, and are made accessible through authenticated URL endpoints.

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, along with its configurable tools and toolsets.

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.

This section also covers documentation on how to configure incoming webhooks for the Buildkite platform, available through pipeline triggers.

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