REST API overview

Schema

All API access is over HTTPS, and accessed from the api.buildkite.com domain. All data is sent as JSON.

The following curl command:

curl https://api.buildkite.com

Generates a response like:

{"message":"🛠","timestamp":1719276157}

where the timestamp value is the current Unix time value.

Query string parameters

Some API endpoints accept query string parameters which are added to the end of the URL. For example, the builds listing APIs can be filtered by state using the following curl command:

curl -H "Authorization: Bearer $TOKEN" \
  -X GET "https://api.buildkite.com/v2/organizations/my-org/pipelines/my-pipeline/builds?state=passed"

Request body properties

Some API requests accept JSON request bodies for specifying data. For example, the build create API can be passed the required properties using the following curl command:

curl -H "Authorization: Bearer $TOKEN" \
  -X POST "https://api.buildkite.com/v2/organizations/my-org/pipelines/my-pipeline/builds" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "value"
  }'

The data encoding is assumed to be application/json. Unless explicitly stated you can not encode properties as www-form-urlencoded or multipart/form-data.

Authentication

You can authenticate with the Buildkite API using access tokens, represented by the value $TOKEN throughout this documentation.

API access tokens authenticate calls to the API and can be created from the API access tokens page. When configuring API access tokens, you can limit their access to individual organizations and permissions, and these tokens can be revoked at any time from the web interface or the REST API.

To authenticate an API call using an access token, set the Authorization HTTP header to the word Bearer, followed by a space, followed by the access token. For example:

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

API access using basic HTTP authentication is not supported.

Pagination

For endpoints which support pagination, the pagination information can be found in the Link HTTP response header containing zero or more of next, prev, first and last.

curl -i -H "Authorization: Bearer $TOKEN" \
  -X GET "https://api.buildkite.com/v2/organizations/my-great-org/pipelines/my-pipeline/builds"

HTTP/1.1 200 OK
...
Link: <https://api.buildkite.com/v2/organizations/my-great-org/pipelines/my-pipeline/builds?api_key=f8582f070276d764ce3dd4c6d57be92574dccf86&page=3>; rel="next", <https://api.buildkite.com/v2/organizations/my-great-org/pipelines/my-pipeline/builds?api_key=f8582f070276d764ce3dd4c6d57be92574dccf86&page=6>; rel="last"

You can set the page using the following query string parameters:

CORS headers

API responses include the following CORS headers allowing you to use the API directly from the browser:

• Access-Controller-Allow-Origin: *
• Access-Control-Expose-Headers: Link

For an example of this in use, see the Emojis API example on CodePen for adding emoji support to your own browser-based dashboards and build screens.

Migrating from v1 to v2

The following changes were made in v2 of our API:

• POST /v1/organizations/{org.slug}/agents has been removed
• DELETE /v1/organizations/{org.slug}/agents/{id} has been removed
• All project-related properties in JSON responses and requests have been renamed to pipeline
• The featured_build pipeline property has been removed
• The deprecated /accounts URL has been removed
• URLs containing /projects have been renamed to /pipelines

Clients

To make getting started easier, check out these clients available from our contributors:

• Buildkit for Ruby
• go-buildkite for Go
• PSBuildkite for PowerShell
• pybuildkite for Python
• buildkite-php for PHP
• buildkite-swift for Swift
• buildkite-api-client for Java