Unable to render embedded object: File (TeamCity48.png) not found.

TeamCity 10.x and 2017.x Documentation


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: related to https://youtrack.jetbrains.com/issue/TW-40540


Note: If the value contains the "," symbol, it should be enclosed into parentheses: "(<value>)". The value of a dimension can also be encoded as Base64url and sent as "<dimension>:($base64:<base64-encoded-value>)" instead of "<dimension>:<value>".


http://teamcity:8111/httpAuth/app/rest/projects gets you the list of projects
http://teamcity:8111/httpAuth/app/rest/projects/<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.


  • Make root REST API URL configurable (e.g. allow to specify alternative for "app/rest/<version>" part of the URL). This will allow to direct the client to another version of API if necessary.
  • Ignore (do not error out) item's attributes and sub-items which are unknown to the client. New sub-items are sometimes added to API without version change and this will ensure the client is not affected by the change.
  • Set large (and make them configurable) request timeouts. Some API calls can take minutes, especially on a large server.
  • Use HTTP sessions to make consecutive requests (use TCSESSIONID cookie returned from the first authenticated response instead of supplying raw credentials all the time). This saves time on authentication which can be significant for external authentication providers.
  • Beware of partial answers when requesting list of items: some requests are paged by default. If necessary, read and process "nextHref" attribute of the response entity for items collections. Related locator dimensions are "count" and "lookupLimit". 
  • Do not abuse ability to execute automated requests for TeamCity API: do not query API too frequently and restrict the data requested to only that necessary (using due locators and specifying necessary fields). Check the server behavior under load from your requests. Make sure not to repeat the request frequently if it takes time to process the request.


Since TeamCity 10, it is possible to disable/enable artifact dependencies and agent requirements:
Disable/enable an artifact dependency PUT http://teamcity:8111/httpAuth/app/rest/buildTypes/<buildTypeLocator>/artifact-dependencies/<id>/disabled (put "true" or "false" text as text/plain)
Disable/enable an agent requirement PUT
  http://teamcity:8111/httpAuth/app/rest/buildTypes/<buildTypeLocator>/agent-requirements/<id>/disabled  (put "true" or "false" text as text/plain)

Build configuration VCS roots: GET/DELETE http://teamcity:8111/httpAuth/app/rest/buildTypes/<buildTypeLocator>/vcs-root-entries/<id>
Attach VCS root to a build configuration: POST http://teamcity:8111/httpAuth/app/rest/buildTypes/<buildTypeLocator>/vcs-root-entries. The XML/JSON posted is the same as retrieved by GET request to http://teamcity:8111/httpAuth/app/rest/buildTypes/<buildTypeLocator>/vcs-root-entries/<id> except for the secure settings like password: these are not included into responses and should be supplied before POSTing back.


Get the list of build configurations in a project with the status of the last finished build in each build configuration: 
GET http://teamcity:8111/httpAuth/app/rest/buildTypes?locator=affectedProject:(id:ProjectId)&fields=buildType(id,name,builds($locator(running:false,canceled:false,count:1),build(number,status,statusText)))


Build Locator

Using a locator in build-related requests, you can filter the builds to be returned in the build-related requests. It is referred to as "build locator" in the scope of REST API.


branch:<branch locator> - limit the builds by branch. <branch locator> can be the branch name displayed in the UI, or "(name:<name>,default:<true/false/any>,unspecified:<true/false/any>,branched:<true/false/any>)".  By default only builds from the default branch are returned. To retrieve all builds, add the following locator: branch:default:any. The whole path will look like this: /httpAuth/app/rest/builds/?locator=buildType:One_Git,branch:default:any
revision:<REVISION> - find builds by revision. The whole path is: /httpAuth/app/rest/app/rest/builds?locator=revision:(REVISION),buildType:(id:BUILD_TYPE_ID)
agentName:<name> - agent name to return only builds ran on the agent with name specified
sinceBuild:(<buildLocator>) - limit the list of builds only to those after the one specified
sinceDate:<date> - limit the list of builds only to those started after the date specified. The date should be in the same format as dates returned by REST API (e.g. "20130305T170030+0400").
project:<project locator> - limit the list to the builds of the specified project (belonging to any build type directly under the project). Before TeamCity 9.1 this traversed projects recursively: with meaning "belonging to any build type directly or indirectly under the project".
affectedProject:<project locator> -  limit the list to the builds of the specified project (belonging to any build type directly or indirectly under the project)
count:<number> - serve only the specified number of builds
start:<number> - list the builds from the list starting from the position specified (zero-based)
lookupLimit:<number> - limit processing to the latest N builds only. If none of the latest N builds match the other specified criteria of the build locator, 404 response is returned. 


Get details of a queued build:
GET http://teamcity:8111/httpAuth/app/rest/buildQueue/id:XXX
For queued builds with snapshot dependencies, the revisions are available in the revisions element of the queued build node if a revision is fixed (for regular builds without snapshot dependencies it is not).


GET http://teamcity:8111/httpAuth/app/rest/builds/<build_locator>/artifacts/archived/<path>?locator=pattern:<wildcard> (returns the archive containing the list of artifacts under the path specified. The optional locator parameter can have file <wildcard> to limit the files only to those matching the wildcard)
Media-Type: application/zip
Possible error: 400 if the artifact is neither a directory nor an archive

Wiki Markup
Since *TeamCity 9.1*:
"locator" parameter is supported for the artifacts listing requests, e.g. "{{recursive:true,browseArchives:true}}". "recursive:true" dimension allows to list files recursively, "browseArchives:true" treat supported archives as "directories", listing their content
<artifact relative name> supports referencing files under archives using "!/" delimiter after the archive name.


GET http://teamcity:8111/httpAuth/app/rest/builds/id:100/artifacts/children/my-great-tool-0.1.jar\!/META-INF
GET http://teamcity:8111/httpAuth/app/rest/builds/id:100/artifacts/metadata/my-great-tool-0.1.jar\!/META-INF/MANIFEST.MF
GET http://teamcity:8111/httpAuth/app/rest/builds/id:100/artifacts/metadata/my-great-tool-0.1.jar!/lib/commons-logging-1.1.1.jar!/META-INF/MANIFEST.MF
GET http://teamcity:8111/httpAuth/app/rest/builds/id:100/artifacts/content/my-great-tool-0.1.jar!/lib/commons-logging-1.1.1.jar!/META-INF/MANIFEST.MF


(info) Please note that the change id is the change's internal modification id, not the revision. The id can be seen in the change node listed by the REST API or in the URL of the change details (as modId).

Get all changes for a project: GET http://teamcity:8111/app/rest/changes?locator=project:projectId
Get all the changes in a build configuration since a particular change identified by its id: http://teamcity:8111/httpAuth/app/rest/changes?locator=buildType:(id:buildConfigurationId),sinceChange:(id:changeId)

Get details of an individual change: GET http://teamcity:8111/app/rest/changes/id:changeId
The files node lists changed files. SinceTeamCity 10.0, the information about the changed file action is reported via the changeType attribute for the files listed as one of the following:  added, edited, removed, copied or unchanged.


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>"


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

Enable/disable an agent:  PUT http://teamcity:8111/httpAuth/app/rest/agents/<agentLocator>/enabled (put "true" or "false" text as text/plain). See an example.
Authorize/unauthorize an agent: PUT http://teamcity:8111/httpAuth/app/rest/agents/<agentLocator>/authorized (put "true" or "false" text as text/plain)

Add a comment when enabling/disabling and authorizing/unauthorising an agent (since TeamCity 10.0):
Agent enabled/authorized data is exposed in the enabledInfo and authorizedInfo nodes:

Code Block
<agent id="1" name="agentName" typeId="1" connected="true" enabled="true" authorized="true" uptodate="true" ip="..........." href="/httpAuth/app/rest/agents/id:1">
 <enabledInfo status="true">
   <user username="userName" id="1" href="/httpAuth/app/rest/users/id:1"/>
 <authorizedInfo status="true">
   <user username="userName" id="1" href="/httpAuth/app/rest/users/id:1"/>


A .png icon: GET http://teamcity:8111/httpAuth/app/rest/builds/<buildLocator>/statusIcon
An .svg icon: GET http://teamcity:8111/httpAuth/app/rest/builds/<buildLocator>/statusIcon.svg

Icon that represents build status for several builds (since TeamCity 10.0):
GET http://teamcity:8111/httpAuth/app/rest/builds/aggregated/<build locator> request and "strob" build locator dimension:


titleExamples: click to expand

 Get the list of changes for a project: http://teamcity:8111/app/rest/changes?locator==project:projectId
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.


(warning) Note that editing via the TeamCity Web UI will ve disabled for projects created via the REST API