Agent REST API overview

The agent REST API is used to retrieve agent metrics, register agents, de-register them, start jobs on agents, and finish jobs on them.

The agent REST API's publicly available endpoints include:

  • /metrics: Used to retrieve information about current self-hosted agents associated with a Buildkite cluster. The Buildkite Agent Metrics CLI tool uses the data returned by the metrics endpoint for agent autoscaling.
  • /stacks: Used to implement a stack on a self-hosted queue. A stack is a long-running controller process that watches the queue for jobs, and runs Buildkite agents on demand to run these jobs.

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 agent also includes an internal API, called the internal job API, which is used to query and mutate the state of if a job running on the agent, using environment variables.

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":"👋","timestamp":1719276157}

Authentication

Unlike the Buildkite REST API, which uses an API access token, the agent REST API's public endpoints use an agent token for authentication.

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

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