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.

...

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

Use http://teamcity:8111/app/rest/application.wadl to  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. The same data is also exposed in Swagger format via .../app/rest/swagger.json endpoint 

hidden-data
 Swagger issue: https://youtrack.jetbrains.com/issue/TW-44962
You can start with http://teamcity:8111/app/rest/server 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.

For the list of supported locator dimensions, use "$help" locator.

Experiment and read the error messages returned: for the most part they should guide you to the right requests.

Expand
titleExample on how to explore the API

Suppose you want to know more on the agents and see (in "/app/rest/server" response) that there is a "/app/rest/agents" URL.

  • try the "/app/rest/agents/" request - see the authorized agent list, get the "default" way of linking to an agent from the agent's element href attribute.
  • get individual agent details via /app/rest/agents/id:10 URL (obtained from "href" for one of the elements of the previous request).
  • if you send a request to "/app/rest/agents/$help, or "/app/rest/agents/aaa:bbb" (supplying unsupported locator dimension), you will get the list of the supported dimensions to find an agent via the agent's locator
  • most of the attributes of the returned agent data (name, connected, authorized) can be used as "<field name>" in the "app/rest/agents/<agentLocator>/<field name>" request. Moreover, if you issue a request to the "app/rest/agents/id:10/test" URL, you will get a list of the supported fields in the error message

...

Authentication can be slow when not built-in authentication module is used, consider applying a workaround the session reuse approach for reusing authentication between sequential requests.

If you perform a request from within a TeamCity build, for a limited set of build-related operations (like downloading artifacts) you can use values of teamcity.auth.userId/teamcity.auth.password system properties as credentials (within TeamCity settings you can reference them as %system.teamcity.auth.userId% and %system.teamcity.auth.password%).

The server URl is available as %teamcity.serverUrl% within a build.Within a build, a request for current build details can look like:
curl -u "%system.teamcity.auth.userId%:%system.teamcity.auth.password%" "%teamcity.serverUrl%/httpAuth/app/rest/builds/id:%teamcity.build.id%"

Superuser access

You can use the super user account with REST API: just provide no user name and the generated password logged into the server log.

...

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 e.g. in TeamCity 10.x for <version> you can use "10.0" for the current and "9.1", "9.0", "8.1", "6.0" to get earlier versions of the protocol. Protocol version corresponds to the TeamCity version where it was first introduced.

...

  • 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/<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 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.

...

It is possible to change the set of fields returned for XML and JSON responses for the majority of requests.
This is done by supplying the fields request parameter describing the fields of the top-level entity and sub-entities to return in the response. An example syntax of the parameter is: field,field2(field2_subfield1,field2_subfield1). This basically means "include field and field2 of the top-level entity and for field2 include field2_subfield1 and field2_subfield1 fields". The order of the fields specification plays no role.

hidden-data
(not public as this is still experimental, needs unification of these locators)
When collection of items is included, some entities support providing additional locator to affect the items in those collections. That is performed by adding "$locator(<locator>)" into the fields under the collection field.
Examples:
http://teamcity.jetbrains.com/app/rest/buildTypes?locator=affectedProject:(id:TeamCityPluginsByJetBrains)&fields=buildType(id,name,project)
http://teamcity.jetbrains.com/app/rest/builds?locator=buildType:(id:bt345),count:10&fields=count,build(number,status,statusText,agent,lastChange,tags,pinned)

...

If you get an error in response to your request and want to investigate the reason, look into rest-related server logs.

To get details about each processed request, turn on debug logging (e.g. set Logging Preset to "debug-rest" on the Administration/Diagnostics page or modify the Log4J "jetbrains.buildServer.server.rest" category) .

...

If that does not help, enable debug logging and look for related messages. If there are none, capture the browser traffic and messages to investigate the case.

...

  • 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. Value of the "count" attribute in the response indicate the number of the items on the current page and there can be more pages available. 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). Even when the returned "count" is 0, it does not mean there are no more items if there is "nextHref" attribute present.
  • Do not increase the  "lookupLimit" value in the locators without a second thought. Doing so has the direct effect of loading the server more and may require increased amounts of CPU and memory. It is assumed that those increasing the default limit understand the negative consequences for the server performance.
  • 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 behavior under load from your requests. Make sure not to repeat the request frequently if it takes time to process the request.

...

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> (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.

...

List of project features:  http://teamcity:8111/app/rest/projects/<projectLocator>/projectFeatures
List features with filtering: http://teamcity:8111/app/rest/projects/<projectLocator>/projectFeatures To filter features, add "?locator=<projectFeaturesLocator>" to the URL e.g. to find all issue tracker features of GitHub type, use the locator "type:IssueTracker,property(name:type,value:GithubIssues)"

Create feature: POST to  http://teamcity:8111/app/rest/projects/<projectLocator>/projectFeatures

Edit features: GET/DELETE/PUT http://teamcity:8111/app/rest/projects/<projectLocator>/projectFeatures/<featureId>

...

Build Configuration/Template details: GET  http://teamcity:8111/app/rest/buildTypes/<buildConfigurationLocator> (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.

To get aggregated status for several build configurations, see 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)

...

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:bt42XXX' copyAllAssociatedSettings='true' shareVCSRoots='false'/> to http://teamcity:8111/app/rest/projects/<projectLocator>/buildTypes

Since TeamCity 2017.2: Read, detach and attach a build configuration from/to a template: GET/DELETE/POST/PUT http://teamcity:8111/app/rest/buildTypes/<buildTypeLocator>/templates 
Before 2017.2: 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)

...

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

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

...

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.

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

Examples of supported build locators:

...

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

...

status:<SUCCESS/FAILURE/ERROR> - 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, perfsonal 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, canceled 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

...

revision:<REVISION> - find builds by revision, e.g. 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 name specified

...

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 related note in the section abov

Anchor
queuedBuilds
queuedBuilds
 

Queued Builds

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

...

Anchor
buildOnSpecificChange
buildOnSpecificChange
Build on a specified change, forced rebuild of all dependencies and clean sources before the build, moved to the build queue top on triggering. (Note that the change is set via the change's internal modification id; see more below):

Code Block
xml
xml
<build>
  <triggeringOptions cleanSources="true" rebuildAllDependencies="true" queueAtTop="true"/>
  <buildType id="buildConfID"/>
  <lastChanges>
    <change id="modificationId" personal="false"/>
  </lastChanges>
</build>

...

Expand
titleExample of cancelling a queued build: click to expand

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

...

Expand
titleExample of cancelling a running build: click to expand

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

...

GET http://teamcity:8111/app/rest/builds/<build_locator>/artifacts/content/<path> (returns the content of a build artifact file for a build determined by <buid_locator>)

(info)<path> above 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, e.g. dir/path/archive.zip!/path_within_archive

...

If you download artifacts from within a TeamCity build, consider using 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.

...

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

Anchor
lastChanges
lastChanges
<lastChanges>
The  <lastChanges>  tag contains information about the last commit included into the build and is only good for re-triggering the build: it contains the TeamCity internal id (the id attribute) associated with the commit, which is necessary for TeamCity to trigger a custom build on the same commit (see the example  above).

Revisions

<revisions>

The <revisions> tag the same as revisions table on the build's Changes tab in TeamCity UI: it lists the revisions of all of the 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. e.g. for a newly created build configuration and a VCS root, a revision will have no corresponding change.

...

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

Anchor
Buildproblems
Buildproblems
Anchor
Tests
Tests

Tests and Build problems

GET List build problems: GET  http://teamcity:8111/app/rest/problemOccurrences?locator=build:(BUILD_LOCATOR)

Tests

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 project's Muted Problems tab

...

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

(only 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 to http://teamcity:8111/app/rest/mutesUse the same XML or JSON as returned by GET

Investigations

List investigations in the Root project and its subprojects: http://teamcity:8111/app/rest/investigations

...

  • 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 for a build configuration: http://teamcity:8111/app/rest/investigations?locator=buildType:(id:XXXX) 

Anchor
assignInvestigation
assignInvestigation
Since TeamCity 2017.2 EAP2 it 2 it is possible to assign/replace investigations: 

POST/PUT to  http://teamcity:8111/app/rest/investigations (accepts a single investigation) and experimental support for multiple investigationsPOST/PUT to http://teamcity:8111/app/rest/investigations/multiple (accepts a list of investigations). Use the same XML or JSON as returned by GET.

 

Agents

List all agents: GET agents (only authorized agents are included by default): GET http://teamcity:8111/app/rest/agents
List all connected authorized agents: GET 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 details of a specific parameter:
GET to 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, i.e. type=password, are listed, but the values not included into response, so the result should be amended before POSTing back.

...

Code Block
html
html
For build configuration with internal id "btXXX":
Status of the last build: <img src="http://teamcity:8111/app/rest/builds/buildType:(id:btXXX)/statusIcon"/>
Status of the last build tagged with tag "myTag": <img src="http://teamcity:8111/app/rest/builds/buildType:(id:btXXX),tag:myTag/statusIcon"/>

All other  <buildLocator> options are supported.

e.g. 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:

Code Block
[![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 CCTray-format XML does not include paused build configurations by default. The URL accepts "locator" parameter instead with standard build configuration locator.

Request Examples

Request Sending Tool

...