REST API overview

Schema

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

curl https://api.buildkite.com

{
  "response": "Hello World"
}

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 "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 -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.

API access tokens allow to call the API without using your username and password. They can be created on your API access tokens page, limited to individual organizations and permissions, and revoked at any time from the web interface or the REST API.

To authenticate using a 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" https://api.buildkite.com/v2/user

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