TeamCity 2021.1 Help

Manage Agents

This article lists REST API requests concerning agents.

List agents (only authorized agents are included by default)

GET http://<TeamCity Server host>:<port>/app/rest/agents

List all connected authorized agents

GET http://<TeamCity Server host>:<port>/app/rest/agents?locator=connected:true,authorized:true

List all authorized agents

GET http://<TeamCity Server host>:<port>/app/rest/agents?locator=authorized:true

List all enabled authorized agents

GET http://<TeamCity Server host>:<port>/app/rest/agents?locator=enabled:true,authorized:true

List all agents (including unauthorized)

GET http://<TeamCity Server host>:<port>/app/rest/agents?locator=authorized:any

The request uses default filtering (depending on the specified locator dimensions, others can have default implied value). To disable this filtering, add ,defaultFilter:false to the locator.

Enable/disable an agent

PUT http://<TeamCity Server host>:<port>/app/rest/agents/<agentLocator>/enabled

Put true or false text as text/plain. See an example.

Authorize/unauthorize an agent

PUT http://<TeamCity Server host>:<port>/app/rest/agents/<agentLocator>/authorized

Put true or false text as text/plain.

Get/put an agent's single field

GET/PUT http://<TeamCity Server host>:<port>/app/rest/agents/<agentLocator>/<field_name>

Delete a build agent

DELETE http://<TeamCity Server host>:<port>/app/rest/agents/<agentLocator>

Add a comment when enabling/disabling and authorizing/unauthorizing an agent

Agent enabled/authorized data is exposed in the enabledInfo and authorizedInfo nodes:

<agent id="1" name="agentName" typeId="1" connected="true" enabled="true" authorized="true" uptodate="true" ip="..........." href="/app/rest/agents/id:1"> <enabledInfo status="true"> <comment> <user username="userName" id="1" href="/app/rest/users/id:1"/> <timestamp>20160406T175040+0300</timestamp> <text>newcomment</text> </comment> </enabledInfo> <authorizedInfo status="true"> <comment> <user username="userName" id="1" href="/app/rest/users/id:1"/> <timestamp>20160406T183033+0300</timestamp> </comment> </authorizedInfo> .... </agent>

GET and PUT requests are supported for the following URLs: http://<TeamCity Server host>:<port>/app/rest/agents/<agentLocator>/enabledInfo and http://<TeamCity Server host>:<port>/app/rest/agents/<agentLocator>/authorized.

On PUT only status and comment/text sub-items are taken into account. An example of disabling an agent with a comment:

curl -v -u user:password --request PUT "http://<TeamCity Server host>:<port>/app/rest/agents/id:1/enabledInfo" --data "<enabledInfo status='false'><comment><text>commentText</text></comment></enabledInfo>" --header "Content-Type:application/xml

Agent Pools

List all agent pools

GET http://<TeamCity Server host>:<port>/app/rest/agentPools

Get/modify/remove an agent pool with ID

GET/PUT/DELETE http://<TeamCity Server host>:<port>/app/rest/agentPools/id:ID

Add an agent pool

POST the agentPool name='PoolName' element to http://<TeamCity Server host>:<port>/app/rest/agentPools.

Move an agent to the pool from the previous pool

POST <agent id='YYY'/> to the pool's agents http://<TeamCity Server host>:<port>/app/rest/agentPools/id:XXX/agents.


curl -v -u user:password http://<TeamCity Server host>:<port>/app/rest/agentPools/id:XXX/agents --request POST --header "Content-Type:application/xml" --data "<agent id='1'/>"

Assigning Projects to Agent Pools

Add a project to a pool

POST the <project> node to http://<TeamCity Server host>:<port>/app/rest/agentPools/id:XXX/projects.

Delete a project from a pool

DELETE http://<TeamCity Server host>:<port>/app/rest/agentPools/id:XXX/projects/id:YYY
Last modified: 25 January 2021