You are viewing the documentation of TeamCity 10.x and 2017.x, which is not the most recently released version of TeamCity.
View this page in the latest documentation or refer to the listing to choose the documentation corresponding to your TeamCity version.


Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: changes related to https://youtrack.jetbrains.com/issue/TW-20440; disable build agent example, formatting


http://teamcity:8111/httpAuth/app/rest/projects gets you the list of projects
http://teamcity:8111/httpAuth/app/rest/projects/<projectsLocator> <projectsLocator> http://teamcity:8111/httpAuth/app/rest/projects/id:RESTAPIPlugin (the example id is used) gets you the full data for the REST API Plugin project.
http://teamcity:8111/httpAuth/app/rest/buildTypes/id:bt284/builds?locator=<buildLocator> - http://teamcity:8111/httpAuth/app/rest/buildTypes/id:bt284/builds?locator=status:SUCCESS,tag:EAP - (example ids are used) to get builds
http://teamcity:8111/httpAuth/app/rest/builds/?locator=<buildLocator> - to get builds by build locator.
http://teamcity:8111/httpAuth/app/rest/changes?locator=<changeLocator> <changeLocator> http://teamcity:8111/httpAuth/app/rest/changes?locator=buildType:(id:bt133),sinceChange:(id:24234) - to get all the changes in the build configuration since the change identified by the id.

Supported HTTP Methods

  • GET: retrieves the requested data
  • POST: creates the entity in the request adding it to the existing collection. When posting XML, be sure to specify the "Content-Type: application/xml" HTTP header.
  • PUT: based on the existence of the entity, creates or updates the entity in the request
  • DELETE: removes the requested data


TeamCity REST can be configured to allow cross-origin requests.
If you want to allow requests from a page loaded from a specific domain, add the domain to comma-separated internal property rest.cors.origins.


If that does not work, enable debug logging and investigate the log.


Cancel a running or a queued build:  POST the <buildCancelRequest comment='CommentText' readdIntoQueue='false' /> item to the URL of  a running or a queued build:

titleExample of cancelling a queued build: click to expand

curl -v -u user:password --request POST "http://teamcity:8111/app/rest/buildQueue/<buildLocator>" --data "<buildCancelRequest comment='' readdIntoQueue='false' />" --header "Content-Type: application/xml"

Stop a running build and readd it to the queue:  POST the <buildCancelRequest comment='CommentText' readdIntoQueue='true' /> item to the URL of a running build:


List tests:
GET http://teamcity:8111/app/rest/testOccurrences?locator=<locator dimension>:<value>
Supported locators:

  • build

  • build:(id:buildId),muted:true (tests which were muted when the build ran)

  • build:(id:buildId),currentlyMuted:true (failures were not muted, but the tests were muted since the failure)

  • test

  • currentlyFailing:true,affectedProject:<project locator>

  • currentlyMuted:true,affectedProject:<project locator>

List all build's tests: GET http://teamcity:8111/app/rest/testOccurrences?locator=build:<build locator>

Get individual test history:
http://teamcity:8111/app/rest/testOccurrences?locator=test:<test locator>

List build's tests which were muted when the build ran:
GET http://teamcity:8111/app/rest/testOccurrences?locator=build:(id:XXX),muted:true

List currently muted tests (muted since the failure):
GET http://teamcity:8111/app/rest/testOccurrences?locator=build:(id:XXX),currentlyMuted:true

Supported test locators:

  • "id:<internal test id>" available as a part of the URL on the test history page
  • "name:<full test name>"


Get investigations assigned to a user: http://teamcity:8111/app/rest/investigations?locator=assignee:(<user locator>)

Get investigations for a build configuration: http://teamcity:8111/app/rest/investigations?locator=buildType:(id:XXXX)


List all agents: GET http://teamcity:8111/httpAuth/app/rest/agents
List all connected authorized agents: GET http://teamcity:8111/httpAuth/app/rest/agents?locator=connected:true,authorized:true
List all authorized agents: GET http://teamcity:8111/httpAuth/app/rest/agents?locator=authorized:true
List all enabled authorized agents: GET http://teamcity:8111/httpAuth/app/rest/agents?locator=enabled:true,authorized:true


On PUT only status and comment/text sub-items are taken into account.:

titleExample of disabling an agent with a comment: click to expand

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

Get/PUT agent's single field: GET/PUT http://teamcity:8111/httpAuth/app/rest/agents/<agentLocator>/<field name>
Delete a build agent: DELETE http://teamcity:8111/httpAuth/app/rest/agents/<agentLocator>


Move an agent to the pool from the previous pool:
POST <agent id='YYY'/> to the pool's agents http://teamcity.url/app/rest/agentPools/id:XXX/agents


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

Assigning Projects to Agent Pools


1. Enable superuser in REST
create a file <TeamCity Data Directory>\config\internal.properties with the content:


(add the line if the file already exists)


2. Get authToken
restart the TeamCity server and look into <TeamCity home>\logs\teamcity-rest.log for a line:

Authentication token for superuser generated: 'XXX-YYY-...-ZZZ'.

Copy this "XXX-YYY-...-ZZZ" string. The string is unique for each server restart

3. Issue the request
Get curl command line tool and use a command line:

curl -v --request PUT http://USER:PASSWORD@teamcity:8111/httpAuth/app/rest/users/username:USERNAME/roles/SYSTEM_ADMIN/g/?authToken=XXX-YYY-...-ZZZ

"USER" and "PASSWORD" - the credentials of a valid TeamCity user (that you can log in with)
"teamcity:8111" - the TeamCity server URL
"USERNAME" - the username of the user to be made the system administrator
"XXX-YYY-...-ZZZ" - the authentication token retrieved earlier