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.

All webhooks contain an X-Buildkite-Token header which allows you to verify the authenticity of the request.

API security

Buildkite is a member of the GitHub secret scanning program. This service alerts us when a Buildkite personal API access token has been leaked on GitHub in a public repository.

Once Buildkite receives a notification of a publicly leaked token from GitHub, Buildkite will:

Revoke the token immediately.
Email the user who generated the token to let them know it has been revoked.
Email the organizations associated with the token to let them know it has been revoked.

You can also:

Enable GitHub secret scanning for private repositories.
Generate a new access token for your Buildkite user account.

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

More information about the REST API.

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 information about the Buildkite's GraphQL API through its overview and Console and CLI tutorial pages.

Webhooks

Webhooks allow you 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 your 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.