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.

Endpoints

This section lists all the available endpoints organized by resource type. Each endpoint includes its HTTP method, path structure, and links to detailed documentation with request and response examples and additional relevant information.

Organizations

Organization members

Pipelines

Builds

Jobs

Annotations

Artifacts

Agents

Teams

Team members

Team pipelines

Team suites

Clusters

Cluster queues

Cluster agent tokens

Pipeline templates

Rules

Emojis

User

Access token

Meta

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.

Public key

API access tokens can be created with a public key pair instead of a static token. The private key can be used to sign JWTs to authenticate API calls. You must use the API access token's UUID as the iss claim in the JWT, have an iat within 10 seconds of the current time, and an exp within 5 minutes of your iat.

For example, in Ruby - where private_key.pem contains the private key corresponding to an access token's public key and $UUID is the UUID of the access token:

require "net/http"
require "openssl"
require "jwt" # https://rubygems.org/gems/jwt

claims = {
  "iss" => "$UUID",
  "iat" => Time.now.to_i - 5,
  "exp" => Time.now.to_i + 60,
}

private_key = OpenSSL::PKey::RSA.new(File.read("private_key.pem"))

jwt = JWT.encode(claims, private_key, "RS256")

Net::HTTP.get(URI("https://api.buildkite.com/v2/access-token"), "Authorization" => "Bearer #{jwt}")

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