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`.

Example:

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