REST API Overview

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.

The current version of the Buildkite API is v2.

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

There are two ways to authenticate with the Buildkite API: access tokens and basic authentication.

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.

To authenticate using a token pass it in the access_token query parameter or in the Authorization HTTP request header.

To authenticate using an access_token query parameter:

curl "https://api.buildkite.com/v2/user?access_token=xxxx"

To authenticate using the Authorization HTTP header set the value be 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

Basic Authentication

You can authenticate with your email and password using basic authentication. This is designed for direct testing of the API and should only be used where access token authentication does not make sense.

curl -u "your@email.com" https://api.buildkite.com/v2/user

Enter host password for user 'your@email.com':
{
  "id": "dRjoWRjBildGyxZ2wvRUJv1j3cVdYoKjrPIeUuxWfnU",
  "name": "Jane Doe",
  "email": "jane@doe.com",
  "created_at": "2017-09-22 20:44:33 UTC"
}

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:

pageThe page of results to return

Default: 1

per_pageHow many results to return per-page

Default: 30

Maximum: 100

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: