Buildkite APIs

The Buildkite APIs documentation contains docs for all API-related features of Buildkite available across Buildkite Pipelines (including its test suites features) 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.

Programmatic token issuance

Buildkite also supports OAuth-based flows for issuing access tokens without manually creating one in the Buildkite interface:

OAuth Token Exchange lets a service mint short-lived, scoped API access tokens for users by exchanging a signed JWT assertion, suitable for centralized token authorities and non-interactive automation.
OAuth device authorization lets applications running in environments without browser access (such as SSH sessions, remote development environments, or constrained devices) authenticate by directing the user to complete authorization in a browser on any device.

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, and how to manage portals programmatically through the Portals REST API.

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 Pipelines test suites and Package Registries registries, webhooks can be configured directly on each suite or registry.

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.