Manage Agents

This article lists REST API requests concerning agents.

Get Agents

The general endpoint for retrieving agents:

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

The request returns an Agents entity which contains instances of an Agent entity. Only authorized agents are included by default. The request accepts locator parameter which should be typed as AgentLocator.

For example, to get all connected and authorized agents, use:

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

To list all enabled authorized agents, use:

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

To list all agents (including unauthorized), use:

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 locator dimension to the locator parameter.

Enable/Disable Agent

To enable or disable an agent, PUT true or false text as text/plain to the following endpoint:

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

To supply a comment with the request, PUT the EnabledInfo entity to:

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

Payload example:

<enabledInfo status="true">
  <comment text="string"/>
</enabledInfo>

{
  "comment" : {
    "text" : "text"
  },
  "status" : true
}

Authorize/Unauthorize Agent

To authorize or unauthorize an agent, you can (similarly to enabling/disabling agent) PUT true or false text as text/plain to the following endpoint:

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

To supply a comment with the request, PUT the AuthorizedInfo entity to:

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

Payload example:

<authorizedInfo status="true">
  <comment text="string"/>
</authorizedInfo>

{
  "comment" : {
    "text" : "text"
  },
  "status" : true
}

Get/Update Single Agent Property

To get a specific agent property, use this request:

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

For example, this request will return (in text/plain) the agent name for an agent with the ID 1:

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

To update the property, PUT the text/plain value to the same endpoint.

Delete Build Agent

To delete an agent, use:

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

Last modified: 14 October 2021