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: minor fixes (links, etc)

...

Info

The URL examples on this page assume that your TeamCity server web UI is accessible via the http://teamcity:8111/ URL.

General Usage Principles

...

You can start by opening http://teamcity:8111/app/rest URL in your browser: this page will give you several pointers to explorer explore the API.

Use http://teamcity:8111/app/rest/application.wadl to get the full list of supported requests and names of parameters. This is the primary source of discovery for the supported requests and their parameters.

You can start with http://teamcity:8111/app/rest/server request  request and then drill down following "href" attributes of the entities listed.
Please make sure you read through this "General information" section before using the API.

...

...

Under the http://teamcity:8111/app/rest/ or http://teamcity:8111/app/rest/latest URL the latest version is available.
Under the http://teamcity:8111/app/rest/<version> URL, the current version is available and earlier versions CAN be available. Our general policy is to supply TeamCity with at least one previous version.
In TeamCity 10.x for <version> you can use "10.0" for the current and "9.1", "9.0", "8.1" to get earlier versions of the protocol. Protocol version corresponds to the TeamCity version where it was first introduced.

...

The general structure of the URL in the TeamCity API is teamcityserver:port/<authType>/app/rest/<apiVersion>/<restApiPath>?<parameters>, where

  • teamcityserver and port define the server name and the port used by TeamCity. This page uses "http://teamcity:8111/" as example URL
  • <authType> (optional) is the authentication type to be used, this is generic TeamCity functionality
  • app/rest  is the root path of TeamCity REST API
  • <apiVersion> (optional) is a reference to specific version of REST API
  • <restApiPath>?<parameters> is the REST API part of the URL

When <restApiPath> represents a collection of items .../app/rest/<itmes> <items> (e.g. .../app/rest/builds), then the URL regularly accepts the "locator" parameter which can filter the items returned. Individual items can regularly be addressed by a URL in the form form of .../app/rest/<itmes>/<item_locators>. Both multiple and single items requests regularly support the fields parameter.

Locator

In a number of places, you can specify a filter string which defines what entities to filter/affect in the request. This string representation is referred to as "locator" in the scope of REST API.

...

http://teamcity:8111/app/rest/projects gets you the list of projects
http://teamcity:8111/app/rest/projects/<projectsLocator><projectsLocator>   http://teamcity:8111/app/rest/projects/id:RESTAPIPlugin  (the example id is used) gets you the full data for the REST API Plugin project.
http://teamcity:8111/app/rest/buildTypes/id:bt284/builds?locator=<buildLocator> <buildLocator> http://teamcity:8111/app/rest/buildTypes/id:bt284/builds?locator=status:SUCCESS,tag:EAP - (example ids are used) to get builds
http://teamcity:8111/app/rest/builds/?locator=<buildLocator> - to get builds by build locator.

...

  • Make root REST API URL configurable (e.g. allow to specify an alternative for "app/rest/<version>" part of the URL). This will allow to direct the client to another version of the 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 the 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 you need to process more (e.g. all) items, read and process "nextHref" attribute of the response entity for items collections. If the attribute is present it means there might be more items when queried by the URL provided. Related locator dimensions are "count" (page limit) and "lookupLimit" (depth of search).
  • Do not abuse the ability to execute automated requests for TeamCity API: do not query the API too frequently and restrict the data requested to only that necessary (using due locators and specifying necessary fields). Check the server behaviour under load from your requests. Make sure not to repeat the request frequently if it takes time to process the request.

...


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>

...

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>

...

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> name>  (produces XML, JSON and plain text depending on the "Accept" header, accepts plain text and XML and JSON) Also supported are 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> (accepts/produces text/plain) where <field_name> is one of "name", "description", "archived".

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

Project Features

Project features (e.g. 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
List features with filtering: http://teamcity:8111/app/rest/projects/<projectLocator>/projectFeatures?locator=<projectFeaturesLocator> e.g. to find all issue tracker features of GitHub type, use the locator "type:IssueTracker,property(name:type,value:GithubIssues)"
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-rootsadd locator=<vcsRootLocator> parameter to list only the VCS roots matched
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 like retrieved for 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 PUT http://teamcity:8111/app/rest/vcs-roots/<vcsRootLocator>/<field_name>name>, where <field_name> is one of the following: name, shared, project (post project locator to "project" to associate a VCS root with a specific project).

Anchor
vcs_root_instances
vcs_root_instances
List VCS root instances: GET http://teamcity:8111/app/rest/vcs-root-instances?locator=<vcsRootInstancesLocator> 
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 the actual VCS operation.
If the a VCS root has no %-references to parameters, a single VCS root corresponds to a single "VCS root instance".
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".

...

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

VCS root instance locator

Some of the supported "<vcsRootInstancesLocator>" from above:
type:<VCS root type> - VCS root instances of the specified version control (e.g. "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><name>" and value matching condition "<matchType>" (e.g. equals, contains) by the value "<value>".

Build Configuration And Template Settings

...

To get aggregated status for several build configurations, s ee  Build Status Icon section.

Anchor
buildTypePause
buildTypePause

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
PUT 
http://teamcity:8111/app/rest/buildTypes/<buildTypeLocator>/parameters/<parameter_name>
   (produces XML, JSON and plain text depending on the "Accept" header, accepts plain text and XML and JSON). The requests .../parameters/<parameter_name>/name and .../parameters/<parameter_name>/value are also supported.

Build configuration steps: GET/DELETE 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

...

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

...

Read, detach and attach a build configuration from/to a template: GET/DELETE/PUT http://teamcity:8111/app/rest/buildTypes/<buildTypeLocator>/template  (PUT accepts template locator with the "text/plain" Content-Type)

...