Agent REST API overview

The Agent REST API is used for agent registration, agent deregistration, starting jobs on agents, finishing jobs on agents, and agent metrics.

The only publicly available endpoint is /metrics. The Buildkite metrics agent uses the data returned by the metrics endpoint for agent autoscaling.

All other endpoints in the Agent API are intended only for use by the Buildkite Agent, therefore stability and backwards compatibility are not guaranteed, and changes won't be announced.

The current version of the Agent API is v3.

Schema

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

curl https://agent.buildkite.com

{
  "message":"👋"
}

Authentication

Unlike the Buildkite REST API, which uses an API access token, the Agent REST API uses an Agent registration token for authentication.

To authenticate using an Agent registration token, set the Authorization HTTP header to the word Token, followed by a space, followed by the access token. For example:

curl -H "Authorization: Token $TOKEN" https://agent.buildkite.com/v3/metrics