Icon

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

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: related to https://youtrack.jetbrains.com/issue/TW-45542, and minor formatting

...


List of templates for a particular project: http://teamcity:8111/httpAuth/app/projects/<projectLocator>/templates.
List of all the templates on the server: http://teamcity:8111/httpAuth/app/rest/buildTypes?locator=templateFlag:true

Build Configuration/Template details: GET http://teamcity:8111/httpAuth/app/rest/buildTypes/<buildTypeLocator>

Build Configuration Locator

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

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

Wiki Markup
{hidden-data}
compatibleAgent
compatibleAgentsCount
parameter
filterByBuilds
{hidden-data}

Project Settings

Get project details: GET http://teamcity:8111/httpAuth/app/rest/projects/<projectLocator>
Delete a project: DELETE http://teamcity:8111/httpAuth/app/rest/projects/<projectLocator>
Create a new empty project: POST plain text (name) to http://teamcity:8111/httpAuth/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/httpAuth/app/rest/projects. Also see an example(warning) Note that editing via the TeamCity Web UI will ve disabled for projects created via the REST API. 

...

Project's parent project: GET/PUT XML http://teamcity:8111/httpAuth/app/rest/projects/<projectLocator>/parentProject

Project Features

Project features (issue trackers, versioned settings, custom charts, shared resources and third-party report tabs) are exposed since TeamCity 10.

Get/set/add/delete features and their parameters via the http://teamcity:8111/httpAuth/app/rest/projects/<projectLocator>/projectFeatures request.

Filter features of a project, e.g. find all GitHub issue trackers configured for a given project: GET http://teamcity:8111/httpAuth/app/rest/projects/<projectLocator>/projectFeatures?locator=type:IssueTracker,property(name:type,value:GithubIssues)

Filter projects by a project feature,  e.g. find all projects with GitHub configured as an issue tracker: GET http://buildserver/app/rest/projects?locator=projectFeature:(type:IssueTracker,property(name:type,value:GithubIssues))

VCS Roots

List all VCS roots: GET http://teamcity:8111/httpAuth/app/rest/vcs-roots
Get details of a VCS root/delete a VCS root: GET/DELETE http://teamcity:8111/httpAuth/app/rest/vcs-roots/<vcsRootLocator>, where <vcsRootLocator> is "id:<internal VCS root id>"
Create a new VCS root: POST VCS root XML (the one like retrieved for a GET request for VCS root details) to http://teamcity:8111/httpAuth/app/rest/vcs-roots

...

Anchor
vcs_root_instances
vcs_root_instances
List all VCS root instances: GET GET http://teamcity:8111/httpAuth/app/rest/vcs-root-instances
A "VCS root" is the setting configured in the TeamCity UI. , "VCS root instance" is the internal TeamCity entity which is derived from the "VCS root" to perform actual VCS operation.
If the VCS root has no %-references to a parameters parameters, a single VCS root corresponds to a single "VCS root instance".
f If a VCS root has %-reference to a parameter and the reference resolves to a different value when the VCS root is attached to different configurations or when custom builds are run, a single "VCS root" can generate several "VCS root instances".

Anchor
commit_hook_requests
commit_hook_requests
Since TeamCity 10.0:

There are two endpoints dedicated at using in commit hooks  from the version control repositories:
POST POST http://teamcity:8111/app/rest/vcs-root-instances/checkingForChangesQueue?locator=<locator> - returns the list of VCS root instances matched, just like GET http://teamcity:8111/httpAuth/app/rest/vcs-root-instances?locator=<locator>
POST http://teamcity:8111/app/rest/vcs-root-instances/commitHookNotification?locator=<locator> - returns plain-text textual 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 hit consider tweaking the <locator> to match less instances (recommended) or increase the limit e.g. by adding ",count:1000" to the locator.

Build Configuration And Template Settings

Get build configuration Build Configuration/Template details: GET GET http://teamcity:8111/httpAuth/app/rest/buildTypes/<buildTypeLocator> <buildConfigurationLocator> (check details about <buildTypeLocator>)details on the Build Configuration locator).

Please note that there is no transaction, etc. 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, etc. Please make sure you pause a build configuration before changing its settings if this aspect is important for your case.

...

Expand
titleSome examples: click to expand
No Format
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>.

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

Wiki Markup
{hidden-data}
compatibleAgent
compatibleAgentsCount
parameter
filterByBuilds
{hidden-data}

Build Requests

List builds: GET http://teamcity:8111/httpAuth/app/rest/builds/?locator=<buildLocator>

Anchor
buildDelete
buildDelete
Get details of a specific build: GET http://teamcity:8111/httpAuth/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/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.

...