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.
For the list of existing disparities between the REST API and the GraphQL API, see API differences.
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
Access using basic HTTP authentication is no longer available.
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:
page |
The page of results to return Default: |
---|---|
per_page |
How many results to return per-page Default: Maximum: |
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