REST API Reference

Projects and Build Configuration/Templates Lists


List of projects	GET http://teamcity:8111/app/rest/projects
Project details	GET http://teamcity:8111/app/rest/projects/<projectLocator> where `<projectLocator>` can be `id:<internal_project_id>` or `name:<project%20name>`
List of build configurations	GET http://teamcity:8111/app/rest/buildTypes
List of build configurations of a project	GET http://teamcity:8111/app/rest/projects/<projectLocator>/buildTypes
Get projects with subprojects' build configurations data and their order as configured by the specified user on the Overview page	GET http://teamcity:8111/app/rest/projects?locator=selectedByUser:current&fields=count,project(id,parentProjectId,projects(count,project(id),$locator(selectedByUser:current)),buildTypes(count,buildType(id),$locator(selectedByUser:current)))
List of templates for a particular project	GET http://teamcity:8111/app/rest/projects/<projectLocator>/templates
List of all the templates on the server	GET http://teamcity:8111/app/rest/buildTypes?locator=templateFlag:true

Project Settings


Get project details	GET http://teamcity:8111/app/rest/projects/<projectLocator>
Delete a project	DELETE http://teamcity:8111/app/rest/projects/<projectLocator>
Create a new empty project	POST plain text (name) to http://teamcity:8111/app/rest/projects/
Create (or copy) a project	POST XML <newProjectDescription name='New Project Name' id='newProjectId' copyAllAssociatedSettings='true'><parentProject locator='id:project1'/><sourceProject locator='id:project2'/></newProjectDescription> to http://teamcity:8111/app/rest/projects Also see an example.
Edit project parameters	GET/DELETE/PUT http://teamcity:8111/app/rest/projects/<projectLocator>/parameters/<parameter_name> Accepts plain text and XML and JSON. Produces XML, JSON, and plain text depending on the "Accept" header. Also supported requests: `.../parameters/<parameter_name>/name` and `.../parameters/<parameter_name>/value`.
Project name/description/archived status	GET/PUT http://teamcity:8111/app/rest/projects/<projectLocator>/<field_name> where `<field_name>` is one of `name`, `description`, `archived`. Accepts/produces text/plain.
Project's parent project	GET/PUT XML http://teamcity:8111/app/rest/projects/<projectLocator>/parentProject

Project Features

Project features (for example, issue trackers, versioned settings, custom charts, shared resources and third-party report tabs) are exposed as entries under the "project" node and via dedicated requests.


List of project features	http://teamcity:8111/app/rest/projects/<projectLocator>/projectFeatures To filter features, add `?locator=<projectFeaturesLocator>` to the URL, for example to find all issue tracker features of GitHub type, use the locator `type:IssueTracker,property(name:type,value:GithubIssues)`.
Create a feature	`POST` to `/projects/<projectLocator>/projectFeatures`.
Edit features	GET/DELETE/PUT http://teamcity:8111/app/rest/projects/<projectLocator>/projectFeatures/<featureId>

VCS Roots


List all VCS roots	GET http://teamcity:8111/app/rest/vcs-roots Add the `locator=<vcsRootLocator>` parameter to list only the matched VCS roots.
Get details of a VCS root/delete a VCS root	GET/DELETE http://teamcity:8111/app/rest/vcs-roots/<vcsRootLocator> where `<vcsRootLocator>` can be `id:<internal VCS root id>` or other VCS root locator.
Create a new VCS root	`POST VCS root XML` (similar to the one retrieved by a GET request for VCS root details) to `http://teamcity:8111/app/rest/vcs-roots`. Also supported: `GET/PUT` `http://teamcity:8111/app/rest/vcs-roots/<vcsRootLocator>/properties/<property_name>` `GET/PUT` `http://teamcity:8111/app/rest/vcs-roots/<vcsRootLocator>/<field_name>` where `<field_name>` is `id`, `name`, `project` (post the project locator to `project` to associate a VCS root with a specific project).
List VCS root instances*	GET http://teamcity:8111/app/rest/vcs-root-instances?locator=<vcsRootInstancesLocator>

Since TeamCity 10.0:

There are two endpoints dedicated to being used in commit hooks from the version control repositories: POST http://teamcity:8111/app/rest/vcs-root-instances/checkingForChangesQueue?locator=<vcsRootInstancesLocator>

It schedules checking for changes for the matched VCS root instances and returns the list of VCS root instances matched (just like GET http://teamcity:8111/app/rest/vcs-root-instances?locator=<vcsRootInstancesLocator>): POST http://teamcity:8111/app/rest/vcs-root-instances/commitHookNotification?locator=<vcsRootInstancesLocator>

It schedules checking for changes for the matched VCS root instances and returns plain-text human-readable message on the action performed, HTTP response 202 in case of successful operation.

Both perform the same action (put the VCS root instances matched by the <locator>) to the queue for "checking for changes" process and differ only in responses they produce.

Note that since the matched VCS root instances are the same as for ../app/rest/vcs-root-instances?locator=<locator> request and that means that by default only the first 100 are matched and the rest are ignored. If this limit is reached, consider tweaking the <locator> to match fewer instances (recommended) or increase the limit, for example by adding ,count:1000 to the locator.

VCS root instance locator

Some supported <vcsRootInstancesLocator> from above:

type:<VCS root type> — VCS root instances of the specified version control (for example, jetbrains.git, mercurial, svn).
vcsRoot:(<vcsRootLocator>) — VCS root instances corresponding to the VCS root matched by <vcsRootLocator>.
buildType:(<buildTypeLocator>) — VCS root instances attached to the matching build configuration.
property:(name:<name>,value:<value>,matchType:<matching>) — VCS root instances with the property of name <name> and value matching condition <matchType> (for example, equals, contains) by the value <value>.

Cloud Profiles

TeamCity REST API exposes the same cloud integration details as those provided in the TeamCity UI.


List all cloud profiles	GET http://teamcity:8111/app/rest/cloud/profiles
List all cloud images	GET http://teamcity:8111/app/rest/cloud/images
List all cloud instances	GET http://teamcity:8111/app/rest/cloud/instances To filter the listing results, you can add a locator to the request.
Start a new instance	POST http://teamcity:8111/app/rest/cloud/instances The posted XML/JSON contents are the same as returned by `GET` for one instance. Example of XML for an instance: <cloudInstance id="profileId:<profileId>,imageId:<imageId>,id:<instanceId>" name="<instanceName>"> <image id="profileId:<profileId>,id:<imageId>" name="<imageName>"/> </cloudInstance>
Stop a running instance	DELETE http://teamcity:8111/app/rest/cloud/instances/<instanceLocator>

Build Configuration And Template Settings


Get build configuration/template details	GET http://teamcity:8111/app/rest/buildTypes/<buildConfigurationLocator> Read more on the build configuration locator. Note that there is no transaction, for example support for settings editing in TeamCity, so all the settings modified via REST API are taken into account at once. This can result in half-configured builds triggered and other issues. Make sure you pause a build configuration before changing its settings if this aspect is important for your case. To get aggregated status for several build configurations, see the Build Status Icon section.
Get/set paused build configuration state	GET/PUT http://teamcity:8111/app/rest/buildTypes/<buildTypeLocator>/paused Put `true` or `false` text as text/plain.
Build configuration settings	GET/DELETE/PUT http://teamcity:8111/app/rest/buildTypes/<buildTypeLocator>/settings/<setting_name>
Build configuration parameters	GET/DELETE/PUT http://teamcity:8111/app/rest/buildTypes/<buildTypeLocator>/parameters/<parameter_name> It produces XML, JSON, and plain text depending on the `Accept` header, accepts plain text, XML, and JSON. The `.../parameters/<parameter_name>/name` and `.../parameters/<parameter_name>/value` requests are also supported.
Build configuration steps	GET/DELETE http://teamcity:8111/app/rest/buildTypes/<buildTypeLocator>/steps/<step_id>
Create build configuration step	POST http://teamcity:8111/app/rest/buildTypes/<buildTypeLocator>/steps The XML/JSON posted is the same as retrieved by GET request to `.../steps/<step_id>` except for the secure settings like password: these are not included into responses and should be supplied before POSTing back.
Features, triggers, agent requirements, artifact, and snapshot dependencies follow the same pattern as steps (above) with the respective URLs	http://teamcity:8111/app/rest/buildTypes/<buildTypeLocator>/features/<id> http://teamcity:8111/app/rest/buildTypes/<buildTypeLocator>/triggers/<id> http://teamcity:8111/app/rest/buildTypes/<buildTypeLocator>/agent-requirements/ http://teamcity:8111/app/rest/buildTypes/<buildTypeLocator>/artifact-dependencies/<id> http://teamcity:8111/app/rest/buildTypes/<buildTypeLocator>/snapshot-dependencies/<id> Since TeamCity 10, it is possible to disable/enable artifact dependencies and agent requirements.
Disable/enable an artifact dependency	PUT http://teamcity:8111/app/rest/buildTypes/<buildTypeLocator>/artifact-dependencies/<id>/disabled Put `true` or `false` text as text/plain.
Build configuration VCS roots	GET/DELETE http://teamcity:8111/app/rest/buildTypes/<buildTypeLocator>/vcs-root-entries/<id>
Attach VCS root to a build configuration	POST http://teamcity:8111/app/rest/buildTypes/<buildTypeLocator>/vcs-root-entries The XML/JSON posted is the same as retrieved by GET request to `http://teamcity:8111/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.
Create a new build configuration with all settings	POST http://teamcity:8111/app/rest/buildTypes The XML/JSON posted is the same as retrieved by GET request. Note that `/app/rest/project/XXX/buildTypes` still uses the previous version notation and accepts another entity.
Create a new empty build configuration	`POST` plain text (name) to `http://teamcity:8111/app/rest/projects/<projectLocator>/buildTypes`.
Copy a build configuration	POST XML <newBuildTypeDescription name='Conf Name' sourceBuildTypeLocator='id:XXX' copyAllAssociatedSettings='true' shareVCSRoots='false'/> to `http://teamcity:8111/app/rest/projects/<projectLocator>/buildTypes`.
Read, detach, and attach a build configuration from/to a template	Since TeamCity 2017.2: GET/DELETE/POST/PUT http://teamcity:8111/app/rest/buildTypes/<buildTypeLocator>/templates Before TeamCity 2017.2: GET/DELETE/POST/PUT http://teamcity:8111/app/rest/buildTypes/<buildTypeLocator>/template Put accepts template locator with the `text/plain` Content-Type).
Set build number counter	curl -v --basic --user <username>:<password> --request PUT http://<teamcity.url>/app/rest/buildTypes/<buildTypeLocator>/settings/buildNumberCounter --data <new number> --header "Content-Type: text/plain"
Set build number format	curl -v --basic --user <username>:<password> --request PUT http://<teamcity.url>/app/rest/buildTypes/<buildTypeLocator>/settings/buildNumberPattern --data <new format> --header "Content-Type: text/plain"

Build Configuration Locator

The most frequently used values for <buildTypeLocator> are id:<buildConfigurationOrTemplate_id> and name:<Build%20Configuration%20name>.

Since TeamCity 2017.2, the experimental type locator is supported with one of the values: regular, composite, or deployment.

Other supported dimensions are (these are in experimental state):

internalId — internal ID of the build configuration.
project — <projectLocator> to limit the build configurations to those belonging to a single project.
affectedProject — <projectLocator> to limit the build configurations under a single project (recursively).
template — <buildTypeLocator> of a template to list only build configurations using the template.
templateFlag — boolean value to get only templates or only non-templates.
paused — boolean value to filter paused/not paused build configurations.

Build Requests


List builds	GET http://teamcity:8111/app/rest/builds/?locator=<buildLocator>
Get details of a specific build	GET http://teamcity:8111/app/rest/builds/<buildLocator> Also supports `DELETE` to delete a build.
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/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.

For some requests, a default filtering is applied which returns only "normal" builds (finished builds which are not canceled, not failed-to-start, not personal, and on default branch (in branched build configurations)), unless those types of builds are specifically requested via the locator. To turn off this default filter and process all builds, add the defaultFilter:false dimension to the build locator. Default filtering varies depending on the specified locator dimensions. For example, when agent or user dimensions are present, personal, canceled, and failed to start builds are included into the results.

Examples of supported build locators:

id:<internal build id> — use internal build ID when you need to refer to a specific build.
number:<build number> — to find build by build number, provided build configuration is already specified.
<dimension1>:<value1>,<dimension2>:<value2> — to find builds by multiple criteria.

The list of supported build locator dimensions:

project:<project locator> — limit the list to the builds of the specified project (belonging to any build type directly 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)
buildType:(<buildTypeLocator>),defaultFilter:false — all the builds of the specified build configuration
tag:<tag> — since TeamCity 10, get tagged builds. If a list of tags is specified, for example tag:<tag1>, tag:<tag2>, only the builds containing all the specified tags are returned. The legacy tags:<tags> locator is supported for compatibility.
status:<SUCCESS/FAILURE/UNKNOWN> — list builds with the specified status only.
user:(<userLocator>) — limit builds to only those triggered by the user specified.
personal:<true/false/any> — limit builds by the personal flag. By default, personal builds are not included.
canceled:<true/false/any> — limit builds by the canceled flag. By default, canceled builds are not included.
failedToStart:<true/false/any> — limit builds by the failed to start flag. By default, failed to start builds are not included.
state:<queued/running/finished> — limit builds by the specified state.
running:<true/false/any> — limit builds by the running flag. By default, running builds are not included.
state:running,hanging:true — fetch hanging builds (since TeamCity 10.0).
pinned:<true/false/any> — limit builds by the pinned flag.
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: /app/rest/builds/?locator=buildType:One_Git,branch:default:any.
revision:<REVISION> — find builds by revision, for example all builds of the given build configuration with the revision: /app/rest/builds?locator=revision:(REVISION),buildType:(id:BUILD_TYPE_ID). See more information below.
agentName:<name> — agent name to return only builds ran on the agent with the specified name.
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 (for example, 20130305T170030+0400).
queuedDate/startDate/finishDate:(date:<time-date>,build:<build locator>,condition:<before/after>) — filter builds based on the time specified by the build locator, for example for the builds finished after November 23, 2017, 20:34:46, GMT+1 timezone use: finishDate:(date:20171123T203446%2B0100,condition:after).
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 (the default is 5000). If none of the latest N builds match the other specified criteria of the build locator, 404 response is returned for single build request and empty collection for multiple builds request. See the related note.

Queued Builds


Get a build queue	GET http://teamcity:8111/app/rest/buildQueue Supported locators: `project:<locator>` `buildType:<locator>`
Get details of a queued build	GET http://teamcity:8111/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 compatible agents for queued builds (useful for builds having "No agents" to run on)	GET http://teamcity:8111/app/rest/buildQueue/id:XXX/compatibleAgents

Get a build queue

GET http://teamcity:8111/app/rest/buildQueue

Supported locators:

project:<locator>
buildType:<locator>

Get details of a queued build

GET http://teamcity:8111/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 compatible agents for queued builds (useful for builds having "No agents" to run on)

GET http://teamcity:8111/app/rest/buildQueue/id:XXX/compatibleAgents

Examples:


List queued builds per project	GET http://teamcity:8111/app/rest/buildQueue?locator=project:<locator>
List queued builds per build configuration	GET http://teamcity:8111/app/rest/buildQueue?locator=buildType:<locator>

Triggering a Build

To start a build, send a POST request to http://teamcity:8111/app/rest/buildQueue with the "build" node (see below) in content — the same node as details of a queued build or finished build. The queued build details will be returned.

When the build is started, the request to the queued build (/app/rest/buildQueue/XXX) will return running/finished build data. This way, you can monitor the build completeness by querying build details using the href attribute of the build details returned on build triggering, until the build has the state="finished" attribute.

Build node example

Basic build for a build configuration:

<build>
    <buildType id="buildConfID"/>
</build>
 

Build for a branch marked as personal with a fixed agent, comment and a custom parameter:

<build personal="true" branchName="logicBuildBranch">
    <buildType id="buildConfID"/>
    <agent id="3"/>
    <comment><text>build triggering comment</text></comment>
    <properties>
        <property name="env.myEnv" value="bbb"/>
    </properties>
</build>
 

Queued build assignment to an agent pool:

<build>...
  <agent>
    <pool id="N"/>
  </agent>
...
</build>
 

Build on a change of given revision, forced rebuild of all dependencies and clean sources before the build, moved to the build queue top on triggering. (Note that the change should be already known to TeamCity (displayed in UI for the build configuration, more on the "lastChanges" element):

<build>
  <triggeringOptions cleanSources="true" rebuildAllDependencies="true" queueAtTop="true"/>
  <buildType id="buildConfID"/>
   <lastChanges>
    <change locator="version:a286767fc1154b0c2b93d5728dd5bbcdefdfaca,buildType:(id:buildConfID)"/>
  </lastChanges>
</build>
 

Example command line for the build triggering:

curl -v -u user:password http://teamcity.server.url:8111/app/rest/buildQueue --request POST --header "Content-Type:application/xml" --data-binary @build.xml
 

Build Tags


Get tags	GET http://teamcity:8111/app/rest/builds/<buildLocator>/tags/
Replace tags	PUT http://teamcity:8111/app/rest/builds/<buildLocator>/tags/ Put the same XML or JSON as returned by `GET`.
Add tags	POST http://teamcity:8111/app/rest/builds/<buildLocator>/tags/ Post the same XML or JSON as returned by `GET` or just a plain-text tag name; `<buildLocator>` here should match a single build only. Example of XML for two tags: <tags> <tag name="<tag1>"/> <tag name="<tag2>"/> </tags>

Get tags

GET http://teamcity:8111/app/rest/builds/<buildLocator>/tags/

Replace tags

PUT http://teamcity:8111/app/rest/builds/<buildLocator>/tags/

Put the same XML or JSON as returned by GET.

Add tags

POST http://teamcity:8111/app/rest/builds/<buildLocator>/tags/

Post the same XML or JSON as returned by GET or just a plain-text tag name; <buildLocator> here should match a single build only.

Example of XML for two tags:

<tags>
    <tag name="<tag1>"/>
    <tag name="<tag2>"/>
</tags>

Build Pinning


Get current pin status	GET http://teamcity:8111/app/rest/builds/<buildLocator>/pin/
Pin a build	PUT http://teamcity:8111/app/rest/builds/<buildLocator>/pin/ The text in the request data is added as a comment for the action.
Unpin a build	DELETE http://teamcity:8111/app/rest/builds/<buildLocator>/pin/ The text in the request data is added as a comment for the action; `<buildLocator>` here should match a single build only.

Build Canceling/Stopping


Cancel a queued build	POST the `<buildCancelRequest comment='CommentText' readdIntoQueue='false'/>` item to the URL of a queued build. Example: 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. Example: curl -v -u user:password --request POST "http://teamcity:8111/app/rest/builds/<buildLocator>" --data "<buildCancelRequest comment='' readdIntoQueue='true' />" --header "Content-Type: application/xml" Set `readdIntoQueue` to `false` to stop the build without readding it to the queue.
See the `canceledInfo` element of the build item	Available via `GET http://teamcity:8111/app/rest/builds/<buildLocator>`.

Cancel a queued build

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

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. Example:

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

Set readdIntoQueue to false to stop the build without readding it to the queue.

See the canceledInfo element of the build item

Available via GET http://teamcity:8111/app/rest/builds/<buildLocator>.

Build Artifacts


Return the content of a build artifact file for a build determined by `<build_locator>`	GET http://teamcity:8111/app/rest/builds/<build_locator>/artifacts/content/<path> `<path>` can be empty for the root of build's artifacts or be a path within the build's artifacts. The path can span into the archive content, for example, `dir/path/archive.zip!/path_within_archive`. Media-Type: application/octet-stream or a more specific media type (determined from artifact file extension). Possible error: 400 if the specified path references a directory.
Return information about a build artifact	GET http://teamcity:8111/app/rest/builds/<build_locator>/artifacts/metadata/<path> Media-Type: application/xml or application/json.
Return the list of artifact children for directories and archives	GET http://teamcity:8111/app/rest/builds/<build_locator>/artifacts/children/<path> Media-Type: application/xml or application/json. Possible error: 400 if the artifact is neither a directory nor an archive.
Return an archive containing the list of artifacts under the path specified	GET http://teamcity:8111/app/rest/builds/<build_locator>/artifacts/archived/<path>?locator=pattern:<wildcard> The optional `locator` parameter can have file `<wildcard>` to limit the files only to those matching the wildcard. `<artifact relative name>` supports referencing files under archives using the `!/` delimiter after the archive name. Media-Type: application/zip. Possible error: 400 if the artifact is neither a directory nor an archive.

Examples:

GET http://teamcity:8111/app/rest/builds/id:100/artifacts/children/my-great-tool-0.1.jar!/META-INF
GET http://teamcity:8111/app/rest/builds/buildType:(id:Build_Intallers),status:SUCCESS/artifacts/metadata/my-great-tool-0.1.jar!/META-INF/MANIFEST.MF
GET http://teamcity:8111/app/rest/builds/buildType:(id:Build_Intallers),number:16.7.0.2/artifacts/metadata/my-great-tool-0.1.jar!/lib/commons-logging-1.1.1.jar!/META-INF/MANIFEST.MF
GET http://teamcity:8111/app/rest/builds/buildType:(id:Build_Intallers),tag:release/artifacts/content/my-great-tool-0.1.jar!/lib/commons-logging-1.1.1.jar!/META-INF/MANIFEST.MF
    

Authentication

If you download artifacts from within a TeamCity build, consider using values of teamcity.auth.userId/teamcity.auth.password system properties as credentials for the download artifacts request: this way TeamCity will have a way to record that one build used artifacts of another and will display it on the build's Dependencies tab.

Other Build Requests

Changes

<changes> is meant to represent changes the same way as displayed in the build's Changes in TeamCity UI. In the most cases these are the commits between the current and previous build. The <changes> tag is not included into the build by default, it has the href attribute only. If you execute the request specified in href, you'll get the required changes.


Get the list of all changes included into the build	GET http://teamcity:8111/app/rest/changes?locator=build:(id:<buildId>)
Get details of an individual change	GET http://teamcity:8111/app/rest/changes/id:changeId
Get information about a changed file action	The file's node lists changed files. The information about the changed file action is reported via the `changeType` attribute for the files listed as `added`, `edited`, `removed`, `copied`, or `unchanged`.
Filter all changes by a locator	GET http://teamcity:8111/app/rest/changes?locator=<changeLocator> The change ID is the change's internal 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/app/rest/changes?locator=buildType:(id:buildConfigurationId),sinceChange:(id:changeId)
Get pending changes for a build configuration	http://teamcity:8111/app/rest/changes?locator=buildType:(id:BUILD_CONF_ID),pending:true

The <lastChanges> tag contains information about the last commit included into the build. When triggering a build, its nested <change> element can contain the locator field that specifies what change to use for the build triggering.

Revisions

The <revisions> tag the same as revisions table on the build's Changes tab in TeamCity UI: it lists the revisions of all VCS repositories associated with this build that will be checked out by the build on the agent. A revision might or might not correspond to a change known to TeamCity. For example, for a newly created build configuration and a VCS root, a revision will have no corresponding change.


Get all builds with the specified revision	GET http://teamcity:8111/app/rest/builds?locator=revision(version:XXXX)

Since TeamCity 10, <versionedSettingsRevision> is added to represent revision of the versioned settings of the build.

Snapshot dependencies


Find all the snapshot dependency builds in the build chain upstream for the build with the ID `XXXX`.	GET http://teamcity:8111/app/rest/builds?locator=snapshotDependency:(to:(id:XXXX),includeInitial:true),defaultFilter:false
Find all the snapshot-dependent builds in all build chains downstream for the build with the ID `XXXX`.	GET http://teamcity:8111/app/rest/builds?locator=snapshotDependency:(from:(id:XXXX),includeInitial:true),defaultFilter:false

Artifact dependencies

Since TeamCity 10.0.3, there is an experimental ability to:


Get all the builds which downloaded artifacts from the build with the given ID (Delivered artifacts in the TeamCity web UI)	GET http://teamcity:8111/app/rest/builds?locator=artifactDependency:(from:(id:<build ID>),recursive:false)
Get all the builds whose artifacts were downloaded by the build with the given ID (Downloaded artifacts in the TeamCity web UI)	GET http://teamcity:8111/app/rest/builds?locator=artifactDependency:(to:(id:<build ID>),recursive:false)

VCS Labels


Get VCS labels of a build	by adding the `vcsLabels` field: GET http://teamcity:8111/app/rest/builds?locator=<buildLocator>&fields=build(id,vcsLabels:$long) or via a separate request: GET http://teamcity:8111/app/rest/builds/<buildLocator>/vcsLabels?fields=status,text
Add a VCS label to a build	POST http://teamcity:8111/app/rest/builds/<buildLocator>/vcsLabels?locator=<vcsRootInstanceLocator>&fields=build(id,vcsLabels) where `locator` is optional and specifies where to put labels; if not specified, a label will be added to all instances of a VCS root.

Get VCS labels of a build

by adding the vcsLabels field:

GET http://teamcity:8111/app/rest/builds?locator=<buildLocator>&fields=build(id,vcsLabels:$long)

or via a separate request:

GET http://teamcity:8111/app/rest/builds/<buildLocator>/vcsLabels?fields=status,text

Add a VCS label to a build

POST http://teamcity:8111/app/rest/builds/<buildLocator>/vcsLabels?locator=<vcsRootInstanceLocator>&fields=build(id,vcsLabels)

where locator is optional and specifies where to put labels; if not specified, a label will be added to all instances of a VCS root.

Build Parameters


Get the parameters of a build	GET http://teamcity:8111/app/rest/builds/id:<build_id>/resulting-properties

Build Fields


Get a single build's field	GET http://teamcity:8111/app/rest/builds/<buildLocator>/<field_name> This accepts/produces text/plain where `<field_name>` is one of `number`, `status`, `id`, `branchName`, and other build's bean attributes.

Statistics


Get statistics for a single build	GET http://teamcity:8111/app/rest/builds/<buildLocator>/statistics/ Only standard/bundled statistic values are listed. See also Custom Charts.
Get single build statistics value	GET http://teamcity:8111/app/rest/builds/<buildLocator>/statistics/<value_name>
Get statistics for a list of builds	GET http://teamcity:8111/app/rest/builds?locator=BUILDS_LOCATOR&fields=build(id,number,status,buildType(id,name,projectName),statistics(property(name,value)))

Build Log

Downloading build logs via a REST request is not supported, but there is a way to download the log files described here.

Tests and Build Problems


List build problems	GET http://teamcity:8111/app/rest/problemOccurrences?locator=build:(BUILD_LOCATOR)
List tests	GET http://teamcity:8111/app/rest/testOccurrences?locator=<locator dimension>:<value>

Supported locators:

build:(<build locator>) — test run in the build.
build:(<build locator>),muted:true — failed tests which were muted in the build.
currentlyFailing:true,affectedProject:<project_locator> — tests currently failing under the project specified (recursively).
currentlyMuted:true,affectedProject:<project_locator> — tests currently muted under the project specified (recursively). See also the project's Muted Problems tab.
includePersonal:true- include tests from personal builds.

Examples:


List all build's tests	GET http://teamcity:8111/app/rest/testOccurrences?locator=build:<buildLocator>
Get individual test history	GET http://teamcity:8111/app/rest/testOccurrences?locator=test:<testLocator>
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>

There is an experimental support for exposing single test invocations / runs:


Get invocations of a test	GET http://teamcity:8111/app/rest/testOccurrences?locator=build:(id:XXX),test:(id:XXX)&fields=$long,testOccurrence($short,invocations($long))
List all test runs with all the invocations flattened	GET http://teamcity:8111/app/rest/testOccurrences?locator=build:(id:XXX),test:(id:XXX),expandInvocations:true

Muted Tests and Build Problems

Since TeamCity 2017.2


List all muted tests and build problems	GET http://teamcity:8111/app/rest/mutes
Unmute a test or build problems	DELETE http://teamcity:81111/app/rest/mutes/id:XXXX
Mute a test or build problems	POST http://teamcity:8111/app/rest/mutes Use the same XML or JSON as returned by `GET`. Example of XML for muting a test: <mute> <scope><project id="<projectID>"/></scope> <target><tests><test name="<testName>"/></tests></target> <resolution type="whenFixed"/> </mute>

List all muted tests and build problems

GET http://teamcity:8111/app/rest/mutes

Unmute a test or build problems

DELETE http://teamcity:81111/app/rest/mutes/id:XXXX

Mute a test or build problems

POST http://teamcity:8111/app/rest/mutes

Use the same XML or JSON as returned by GET.

Example of XML for muting a test:

<mute>
    <scope><project id="<projectID>"/></scope>
    <target><tests><test name="<testName>"/></tests></target>
    <resolution type="whenFixed"/>
</mute>

Investigations


List investigations in the Root project and its subprojects	GET http://teamcity:8111/app/rest/investigations Supported locators: `test: (id:TEST_NAME_ID)` `test: (name:FULL_TEST_NAME)` `assignee: (<user_locator>)` `buildType:(id:XXXX)`
Get investigations for a specific test	http://teamcity:8111/app/rest/investigations?locator=test:(id:TEST_NAME_ID) http://teamcity:8111/app/rest/investigations?locator=test:(name:FULL_TEST_NAME)
Get investigations assigned to a user	GET http://teamcity:8111/app/rest/investigations?locator=assignee:(<user locator>)
Get investigations for a build configuration	GET http://teamcity:8111/app/rest/investigations?locator=buildType:(id:XXXX)
To assign/replace investigations	A single investigation: `POST/PUT` to `http://teamcity:8111/app/rest/investigations` Experimental support for multiple investigations: `POST/PUT` to `http://teamcity:8111/app/rest/investigations/multiple` (accepts a list of investigations). Use the same XML or JSON as returned by `GET`. Example of XML for assigning an investigation: <investigation state="TAKEN"> <assignee username="<username>"/> <scope><buildType id="<buildTypeID>"/></scope> <target anyProblem="true"/> <resolution type="whenFixed"/> </investigation>

Agents


List agents (only authorized agents are included by default)	GET http://teamcity:8111/app/rest/agents
List all connected authorized agents	GET http://teamcity:8111/app/rest/agents?locator=connected:true,authorized:true
List all authorized agents	GET http://teamcity:8111/app/rest/agents?locator=authorized:true
List all enabled authorized agents	GET http://teamcity:8111/app/rest/agents?locator=enabled:true,authorized:true
List all agents (including unauthorized)	GET http://teamcity:8111/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:8111/app/rest/agents/<agentLocator>/enabled Put `true` or `false` text as text/plain. See an example.
Authorize/unauthorize an agent	PUT http://teamcity:8111/app/rest/agents/<agentLocator>/authorized Put `true` or `false` text as text/plain.
Get/put an agent's single field	GET/PUT http://teamcity:8111/app/rest/agents/<agentLocator>/<field_name>
Delete a build agent	DELETE http://teamcity:8111/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:8111/app/rest/agents/<agentLocator>/enabledInfo` and `http://teamcity:8111/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:8111/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:8111/app/rest/agentPools
Get/modify/remove an agent pool with `ID`	GET/PUT/DELETE http://teamcity:8111/app/rest/agentPools/id:ID
Add an agent pool	`POST` the `agentPool name='PoolName'` element to `http://teamcity:8111/app/rest/agentPools`.
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`.

Example:

curl -v -u user:password [http://teamcity.url/app/rest/agentPools/id:XXX/agents](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


Add a project to a pool	`POST` the `<project>` node to `http://teamcity.url/app/rest/agentPools/id:XXX/projects`.
Delete a project from a pool	DELETE http://teamcity.url/app/rest/agentPools/id:XXX/projects/id:YYY

Users


List of users	GET http://teamcity:8111/app/rest/users
Get specific user details	GET http://teamcity:8111/app/rest/users/<userLocator>
Create a user	POST http://teamcity:8111/app/rest/users
Update/remove specific user	PUT/DELETE http://teamcity:8111/app/rest/users/<userLocator>

For the POST and PUT requests for a user, post data in the form retrieved by the corresponding GET request. Only the following attributes/elements are supported: name, username, email, password, roles, groups, properties.


Work with user roles	GET http://teamcity:8111/app/rest/users/<userLocator>/roles `<userLocator>` can be of a form: `id:<internal user id>` — to reference the user by internal ID `username:<user's username>` — to reference the user by username/login name
User's single field	GET/PUT http://teamcity:8111/app/rest/users/<userLocator>/<field_name>
User's single property	GET/DELETE/PUT http://teamcity:8111/app/rest/users/<userLocator>/properties/<property_name>

Work with user roles

GET http://teamcity:8111/app/rest/users/<userLocator>/roles

<userLocator> can be of a form:

id:<internal user id> — to reference the user by internal ID
username:<user's username> — to reference the user by username/login name

User's single field

GET/PUT http://teamcity:8111/app/rest/users/<userLocator>/<field_name>

User's single property

GET/DELETE/PUT http://teamcity:8111/app/rest/users/<userLocator>/properties/<property_name>
 

User Groups


List of groups	GET http://teamcity:8111/app/rest/userGroups
List of users within a group	GET http://teamcity:8111/app/rest/userGroups/key:Group_Key
Create a group	POST http://teamcity:8111/app/rest/userGroups
Delete a group	DELETE http://teamcity:8111/app/rest/userGroups/key:Group_Key

User Access Tokens


List of access tokens	GET http://teamcity:8111/app/rest/users/<userLocator>/tokens
Create an access token	POST http://teamcity:8111/app/rest/users/<userLocator>/tokens/<tokenName>
Delete an access token	DELETE http://teamcity:8111/app/rest/users/<userLocator>/tokens/<tokenName>

Audit Records


To access the records of user actions, also available on the Audit page in TeamCity	GET http://teamcity:8111/app/rest/audit

You can filter records by user, system action, build type, and so on (use GET http://teamcity:8111/app/rest/audit?locator=$help to see all available filters).

Data Backup


Start backup	POST http://teamcity:8111/app/rest/server/backup?includeConfigs=true&includeDatabase=true&includeBuildLogs=true&fileName= where `<fileName>` is the prefix of the file to save backup to. The file will be created in the default backup directory (see more).
Get current backup status (idle/running)	GET http://teamcity:8111/app/rest/server/backup

Typed Parameters Specification


List typed parameters	For a project: GET http://teamcity:8111/app/rest/projects/<locator>/parameters For a build configuration: GET http://teamcity:8111/app/rest/buildTypes/<locator>/parameters The information returned is: `parameters count`, `property name`, `value`, and `type`. The `rawValue` of the `type` element is the parameter specification as defined in the UI.
Get details of a specific parameter	GET http://teamcity:8111/app/rest/buildTypes/<locator>/parameters/<name> Accepts/returns plain-text, XML, JSON. Supply the relevant Content-Type header to the request.
Create a new parameter	`POST` the same XML or JSON or just plain-text as returned by `GET` to `http://teamcity:8111/app/rest/buildTypes/<locator>/parameters/`. Note that secure parameters, for example `type=password`, are listed, but the values not included into response, so the result should be amended before POSTing back. Example of XML for setting a property: <property name="<parameterName>" value=""> <type rawValue="password"/> </property>

List typed parameters

For a project:

GET http://teamcity:8111/app/rest/projects/<locator>/parameters

For a build configuration:

GET http://teamcity:8111/app/rest/buildTypes/<locator>/parameters

The information returned is: parameters count, property name, value, and type. The rawValue of the type element is the parameter specification as defined in the UI.

Get details of a specific parameter

GET http://teamcity:8111/app/rest/buildTypes/<locator>/parameters/<name>

Accepts/returns plain-text, XML, JSON. Supply the relevant Content-Type header to the request.

Create a new parameter

POST the same XML or JSON or just plain-text as returned by GET to http://teamcity:8111/app/rest/buildTypes/<locator>/parameters/. Note that secure parameters, for example type=password, are listed, but the values not included into response, so the result should be amended before POSTing back.

Example of XML for setting a property:

<property name="<parameterName>" value="">
    <type rawValue="password"/>
</property>

Since TeamCity 9.1, partial updates of a parameter are possible (currently in an experimental state):

Name: PUT the same XML or JSON as returned by GET to http://teamcity:8111/app/rest/buildTypes/<locator>/parameters/NAME
Type: GET/PUT accepting XML and JSON as returned by GET to the URL http://teamcity:8111/app/rest/buildTypes/<locator>/parameters/NAME/type
Type's rawValue: GET/PUT accepting plain text http://teamcity:8111/app/rest/buildTypes/<locator>/parameters/NAME/type/rawValue

Build Status Icon

Icon that represents a build status:


An `.svg` icon (recommended)	GET http://teamcity:8111/app/rest/builds/<buildLocator>/statusIcon.svg
A `.png` icon	GET http://teamcity:8111/app/rest/builds/<buildLocator>/statusIcon
Icon that represents build status for several builds (since TeamCity 10.0)	`GET` request and `strob` build locator dimension.

Example request:

For project with the PROJECT_ID ID:

GET http://teamcity:8111/app/rest/builds/aggregated/strob:(buildType:(project:(id:PROJECT_ID)))/statusIcon.svg
 

For all active branches in a build configuration with the BUILD_CONF_ID ID:

GET http://teamcity:8111/app/rest/builds/aggregated/strob:(branch:(buildType:(id:BUILD_CONF_ID),policy:active_history_and_active_vcs_branches),locator:(buildType:(id:BUILD_CONF_ID)))/statusIcon.svg
 

For request /app/rest/builds/aggregated/<build locator> the status is calculated by list of the builds: app/rest/builds?locator=<build locator>. This allows embedding a build status icon into any HTML page with a simple img tag:

For build configuration with the BUILD_CONF_ID ID:

Status of the last build:

<img src="http://teamcity:8111/app/rest/builds/buildType:(id:BUILD_CONF_ID)/statusIcon.svg"/>
 

Status of the last build tagged with the myTag tag:

<img src="http://teamcity:8111/app/rest/builds/buildType:(id:BUILD_CONF_ID),tag:myTag/statusIcon.svg"/>
 

All other build locators are supported.

For example, you can use the following markdown markup to add the build status for GitHub repository for the build configuration with ID TeamCityPluginsByJetBrains_TeamcityGoogleTagManagerPlugin_Build and server https://teamcity.jetbrains.com with guest authentication enabled:

[![Build status](https://teamcity.jetbrains.com/guestAuth/app/rest/builds/buildType:(id:TeamCityPluginsByJetBrains_TeamcityGoogleTagManagerPlugin_Build)/statusIcon.svg](https://teamcity.jetbrains.com/viewType.html?buildTypeId=TeamCityPluginsByJetBrains_TeamcityGoogleTagManagerPlugin_Build)
 

If the returned image contains "no permission to get data" text (

), ensure that one of the following is true:

The server has the guest user access enabled, and the guest user has permissions to access the build configuration referenced, or
The build configuration referenced has the "enable status widget" option ON.
You are logged in to the TeamCity server in the same browser and you have permissions to view the build configuration referenced. Note that this will not help for embedded images in GitHub pages as GitHub retrieves the images from the server side.

TeamCity Licensing Information Requests

Since TeamCity 10:


Licensing information	GET http://teamcity:8111/app/rest/server/licensingData
List of license keys	GET http://teamcity:8111/app/rest/server/licensingData/licenseKeys
License key details	GET http://teamcity:8111/app/rest/server/licensingData/licenseKeys/<license_key>
Add license key(s)	`POST` text/plain newline-delimited keys to `http://teamcity:8111/app/rest/server/licensingData/licenseKeys`.
Delete a license key	DELETE http://teamcity:8111/app/rest/server/licensingData/licenseKeys/<license_key>

CCTray

CCTray-compatible XML is available via http://teamcity:8111/app/rest/cctray/projects.xml.

Without authentication (only build configurations available for guest user): http://teamcity:8111/guestAuth/app/rest/cctray/projects.xml.

The CCTray-format XML does not include paused build configurations by default. The URL accepts the locator parameter instead with standard build configuration locator.

Request Examples

You can use curl command line tool to interact with the TeamCity REST API.

Example command:

curl -v --basic --user USERNAME:PASSWORD --request POST "http://teamcity:8111/app/rest/users/" --data @data.xml --header "Content-Type: application/xml"
 

where USERNAME, PASSWORD, teamcity:8111 are to be substituted with real values, and data.xml file contains the data to send to the server.

Creating a new project

Using curl tool:

curl -v -u USER:PASSWORD http://teamcity:8111/app/rest/projects --header "Content-Type: application/xml" --data-binary
"<newProjectDescription name='New Project Name' id='newProjectId'><parentProject locator='id:project1'/></newProjectDescription>"
 

Making user a system administrator

Get super user token.
Issue the request.
Get curl command line tool and use a command line:

curl -v -u :SUPERUSER_TOKEN --request PUT http://teamcity:8111/app/rest/users/username:USERNAME/roles/SYSTEM_ADMIN/g/
 

where SUPERUSER_TOKEN is the super user token unique for each server start; teamcity:8111 — the TeamCity server URL; USERNAME — the username of the user to be made the system administrator.

Last modified: 25 March 2021