The URL examples on this page assume that your TeamCity server web UI is accessible via the
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.
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.
- Using basic HTTP authentication. Provide a valid TeamCity username and password with the request. You can force basic auth by including
"httpAuth" before the "
/app/rest" part: e.g.
- Using access to the server as a guest user (if enabled) include "
guestAuth" before the "
/app/rest" part: e.g.:
- if you are checking REST
GETrequests from within a browser and you are logged in to TeamCity in the browser, you can just use "
/app/rest" URL: e.g.
http://teamcity:8111/app/rest/latest URL the latest version is available.
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
portdefine 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/restis 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
<restApiPath> represents a collection of items
.../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.
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/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:
License key details:
Add license key(s):
POST text/plain newline-delimited keys to http://teamcity:8111/app/rest/server/licensingData/licenseKeys
Delete a license key:
List of projects:
GET http://teamcity:8111/app/rest/projects/<projectLocator>, where
<projectLocator> can be
Get project details:
Delete a project:
Create a new empty project:
POST plain text (name) to
Create (or copy) a project:
<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>
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 "
Project's parent project:
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:
List features with filtering:
GET/DELETE/PUT http://teamcity:8111/app/rest /projects/<projectLocator>/projectFeatures/<featureId>
List all VCS roots: GET
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
<field_name> is one of the following: name, shared, project (post project locator to "project" to associate a VCS root with a specific project).
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>
<vcsRootInstancesLocator>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")
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 "
Build Configuration And Template Settings
To get aggregated status for several build configurations, s ee 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:
Build configuration parameters:
.../parameters/<parameter_name>/value are also supported.
Build configuration steps:
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
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
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:
PUT accepts template locator with the "text/plain" Content-Type)