The /api/v1/workers API

The most direct way to see existing workers and register new ones is via the /api/v1/workers API endpoint provided by the ATC.

It supports the following methods:

GET /api/v1/workers

List the current worker pool.

POST /api/v1/workers[?ttl=30s]

Register a worker, with an optional TTL.

For example, to register a worker for 10 seconds:

curl -XPOST -d '{
  "name": "image-building-box",
  "platform": "linux",
  "tags": ["hetzner"],
  "addr": "",
  "baggageclaim_url": "",
  "active_containers": 123,
  "resource_types": [
    {"type": "git", "image": "/opt/concourse/resources/git"}

The ?ttl=10s means that the worker's registration will go away in 10 seconds. Workers should continuously heartbeat their presence, so that if/when they go away the TTL will expire. Note that there is currently no way to explicitly unregister a worker; instead you should just submit a low TTL (e.g.1s).

The worker JSON object contains the following attributes:

name: string

Optional. A logical name for the worker. This should be something that stays the same throughout the worker's lifecycle, for example the hostname. If not specified, the addr is used.

platform: string

Required. The platform supported by the worker, e.g. linux, darwin, or windows.

tags: [string]

Optional. A set of arbitrary tags. Only steps specifying a matching a subset of these tags will be placed on the worker.

addr: string

Required. The address of the Garden server. Note that this address must be reachable by the ATC, and has no authentication. For this reason it should always be an address only reachable from within Concourse's private network. To register external workers, see Registering via the TSA.

Optional. The API endpoint for a Baggageclaim server to use for caching artifacts on the worker. If not specified, caching will not be utilized.

Optional. The number of containers currently running on the worker.

resource_types: [{type,image}]

Optional. The set of resource types supported by the worker. If specified, the worker may be used for running resource containers of the given type, using the specified image URI.