TeamCity REST API Reference 2024.07 Help

Manage Agents

This article lists REST API requests concerning agents.

Get Agents

The general endpoint for retrieving agents:

/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:

/app/rest/agents?locator=connected:true,authorized:true

To list all enabled authorized agents, use:

/app/rest/agents?locator=enabled:true,authorized:true

To list all agents (including unauthorized), use:

/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:

/app/rest/agents/<agentLocator>/enabled

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

/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:

/app/rest/agents/<agentLocator>/authorized

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

/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:

/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:

/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:

/app/rest/agents/<agentLocator>
Last modified: 29 March 2022