REST API Reference
Projects and Build Configuration/Templates Lists
List of projects |
|
Project details |
where |
List of build configurations |
|
List of build configurations of a project |
|
Get projects with subprojects' build configurations data and their order as configured by the specified user on the Overview page |
|
List of templates for a particular project |
|
List of all the templates on the server |
|
Project Settings
Get project details |
|
Delete a project |
|
Create a new empty project |
|
Create (or copy) a project |
to
Also see an example. |
Edit project parameters |
Accepts plain text and XML and JSON. Produces XML, JSON, and plain text depending on the "Accept" header. Also supported requests: |
Project name/description/archived status |
where Accepts/produces text/plain. |
Project's parent project |
|
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 |
To filter features, add |
Create a feature |
|
Edit features |
|
VCS Roots
List all VCS roots |
Add the |
Get details of a VCS root/delete a VCS root |
where |
Create a new VCS root |
Also supported:
where |
List VCS root instances* |
|
tip
A 'VCS root' is the setting configured in the TeamCity UI, a VCS root instance is an internal TeamCity entity which is derived from the VCS root to perform the actual VCS operation. If 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.
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 |
|
List all cloud images |
|
List all cloud instances |
|
Start a new instance |
The posted XML/JSON contents are the same as returned by Example of XML for an instance:
|
Stop a running instance |
|
Build Configuration And Template Settings
Get build configuration/template details |
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 |
Put |
Build configuration settings |
|
Build configuration parameters |
It produces XML, JSON, and plain text depending on the |
Build configuration steps |
|
Create build configuration step |
The XML/JSON posted is the same as retrieved by GET request to |
Features, triggers, agent requirements, artifact, and snapshot dependencies follow the same pattern as steps (above) with the respective URLs |
Since TeamCity 10, it is possible to disable/enable artifact dependencies and agent requirements. |
Disable/enable an artifact dependency |
Put |
Build configuration VCS roots |
|
Attach VCS root to a build configuration |
The XML/JSON posted is the same as retrieved by GET request to |
Create a new build configuration with all settings |
The XML/JSON posted is the same as retrieved by GET request. Note that |
Create a new empty build configuration |
|
Copy a build configuration |
to |
Read, detach, and attach a build configuration from/to a template | Since TeamCity 2017.2:
Before TeamCity 2017.2:
Put accepts template locator with the |
Set build number counter |
|
Set build number format |
|
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 details of a specific build |
Also supports |
Get the list of build configurations in a project with the status of the last finished build in each build configuration |
|
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 configurationtag:<tag>
– since TeamCity 10, get tagged builds. If a list of tags is specified, for exampletag:<tag1>
,tag:<tag2>
, only the builds containing all the specified tags are returned. The legacytags:<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 followinglocator: 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 specifiedsinceDate:<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 |
Supported locators:
|
Get details of a queued build |
For queued builds with snapshot dependencies, the revisions are available in the |
Get compatible agents for queued builds (useful for builds having "No agents" to run on) |
|
Examples:
List queued builds per project |
|
List queued builds per build configuration |
|
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 |
|
Replace tags |
Put the same XML or JSON as returned by |
Add tags |
Post the same XML or JSON as returned by Example of XML for two tags:
|
Build Pinning
Get current pin status |
|
Pin a build |
The text in the request data is added as a comment for the action. |
Unpin a build |
The text in the request data is added as a comment for the action; |
Build Canceling/Stopping
Cancel a queued build | POST the
|
Stop a running build and readd it to the queue | POST the
Set |
See the | Available via |
Build Artifacts
Return the content of a build artifact file for a build determined by |
|
Return information about a build artifact |
|
Return the list of artifact children for directories and archives |
|
Return an archive containing the list of artifacts under the path specified |
The optional
|
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 the href, you'll get the required changes.
Get the list of all changes included into the build |
|
Get details of an individual change |
|
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 |
Filter all changes by a locator |
|
Get all changes for a project |
|
Get all the changes in a build configuration since a particular change identified by its ID |
|
Get pending changes for a build configuration |
|
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 |
|
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 |
|
Find all the snapshot-dependent builds in all build chains downstream for the build with the ID |
|
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 all the builds whose artifacts were downloaded by the build with the given ID (Downloaded artifacts in the TeamCity web UI) |
|
Build Parameters
Get the parameters of a build |
|
Build Fields
Get a single build's field |
This accepts/produces text/plain where |
Statistics
Get statistics for a single build |
Only standard/bundled statistic values are listed. See also Custom Charts. |
Get single build statistics value |
|
Get statistics for a list of builds |
|
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 |
|
List tests |
|
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.
Examples:
List all build's tests |
|
Get individual test history |
|
List build's tests which were muted when the build ran |
|
List currently muted tests (muted since the failure) |
|
Supported test locators:
id:<internal test id>
available as a part of the URL on the test history pagename:<full test name>
Since TeamCity 10, there is experimental support for exposing single test invocations / runs:
Get invocations of a test |
|
List all test runs with all the invocations flattened |
|
Muted Tests and Build Problems
Since TeamCity 2017.2
List all muted tests and build problems |
|
Unmute a test or build problems |
|
Mute a test or build problems |
Use the same XML or JSON as returned by Example of XML for muting a test:
|
Investigations
List investigations in the Root project and its subprojects |
Supported locators:
|
Get investigations for a specific test |
|
Get investigations assigned to a user |
|
Get investigations for a build configuration |
|
To assign/replace investigations | A single investigation:
Experimental support for multiple investigations: Use the same XML or JSON as returned by Example of XML for assigning an investigation:
|
Agents
List agents (only authorized agents are included by default) |
|
List all connected authorized agents |
|
List all authorized agents |
|
List all enabled authorized agents |
|
List all agents (including unauthorized) |
The request uses default filtering (depending on the specified locator dimensions, others can have default implied value). To disable this filtering, add |
Enable/disable an agent |
Put |
Authorize/unauthorize an agent |
Put |
Get/put an agent's single field |
|
Delete a build agent |
|
Add a comment when enabling/disabling and authorizing/unauthorizing an agent | Agent enabled/authorized data is exposed in the
On
|
Agent Pools
List all agent pools |
|
Get/modify/remove an agent pool with |
|
Add an agent pool |
|
Move an agent to the pool from the previous pool |
|
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 |
|
Delete a project from a pool |
|
Users
List of users |
|
Get specific user details |
|
Create a user |
|
Update/remove specific user |
|
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 |
|
User's single field |
|
User's single property |
|
User Groups
List of groups |
|
List of users within a group |
|
Create a group |
|
Delete a group |
|
User Access Tokens
List of access tokens |
|
Create an access token |
|
Delete an access token |
|
Audit Records
To access the records of user actions, also available on the Audit page in TeamCity |
|
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 |
where |
Get current backup status (idle/running) |
|
Typed Parameters Specification
List typed parameters | For a project:
For a build configuration:
The information returned is: |
Get details of a specific parameter |
Accepts/returns plain-text, XML, JSON. Supply the relevant Content-Type header to the request. |
Create a new parameter |
Example of XML for setting a 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 byGET
tohttp://teamcity:8111/app/rest/buildTypes/<locator>/parameters/NAME
Type:
GET/PUT
accepting XML and JSON as returned byGET
to the URLhttp://teamcity:8111/app/rest/buildTypes/<locator>/parameters/NAME/type
Type's rawValue:
GET/PUT
accepting plain texthttp://teamcity:8111/app/rest/buildTypes/<locator>/parameters/NAME/type/rawValue
Build Status Icon
Icon that represents a build status:
An .svg icon (recommended) |
|
A .png icon |
|
Icon that represents build status for several builds (since TeamCity 10.0) |
|
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"/>
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"/>
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:
[/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 |
|
List of license keys |
|
License key details |
|
Add license key(s) |
|
Delete a 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.
tip
More examples (for TeamCity 8.0) are available in this external posting.