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.

 
Skip to end of metadata
Go to start of metadata

On this page:

General information

REST API is an open-source plugin bundled since TeamCity 5.0.

To use the REST API, an application makes an HTTP request to the TeamCity server and parses the response.

The TeamCity REST API can be used for integrating applications with TeamCity and for those who want to script interactions with the TeamCity server. TeamCity's REST API allows accessing resources (entities) via URL paths.

Icon

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

General Usage Principles

This documentation is not meant to be comprehensive, but just provide some initial knowledge useful for using the API.

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

 Example 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

REST Authentication

You can authenticate yourself for the REST API in the following ways:

Authentication can be slow when not built-in authentication module is used, consider applying 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%).

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.

REST API Versions

As REST API evolves from one TeamCity version to another, there can be incompatible changes in the protocol.

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

Breaking changes in the API are described in the related Upgrade Notes section.
Please note that additions to the objects returned (such as new XML attributes or elements) are not considered major changes and do not cause the protocol version to increment.
Also, the endpoints marked with "Experimental" comment in application.wadl may change without a special notice in future versions.

Note: The examples on this page use the "/app/rest" relative URL, replace it with the one containing the version if necessary.

URL Structure

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

The locators formats can be:

  • single value: a string without the following symbols: ,:-( )
  • dimension, allowing to filter entities using multiple criteria: <dimension1>:<value1>,<dimension2>:<value2>,<dimension3>:(<dimension3.1>:<value3.1>,<dimension3.2>:<value3.2>)

Refer to each entity description below for the most popular locator descriptions.
If in doubt what a specific locator supports, send a request with "$help" as the locator value. In response you will get a textual description of what the locator supports. If a request with invalid locators is sent, the error messages often hint at the error and list the supported locator dimensions as well.

Note: If the value contains the "," symbol, it should be enclosed into parentheses: "(<value>)". The value of a dimension can also be encoded as Base64url and sent as "<dimension>:($base64:<base64-encoded-value >)" instead of " <dimension>: <value>".

Examples:

http://teamcity:8111/app/rest/projects gets you the list of projects
http://teamcity:8111/app/rest/projects/<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> - 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.

Supported HTTP Methods

  • GET: retrieves the requested data. e.g. usually .../app/rest/entities retrieves a list of entities, .../app/rest/entities/<entity locator> retrieves a single entity
  • POST: creates the entity in the request adding it to the existing collection. When posting XML, be sure to specify the "Content-Type: application/xml" HTTP header. e.g. to create a new entity, one regularly needs to post  a single entity data to the .../app/rest/entities URL
  • PUT: based on the existence of the entity, creates or updates the entity in the request. e.g. supported for some entities, for URLS like .../app/rest/entities/<entity locator>
  • DELETE: removes the requested data e.g. for the .../app/rest/entities/<entity locator> URL

Response Formats

The TeamCity REST APIs returns HTTP responses in the following formats according to the HTTP "Accept" header:

Format

Response Type

HTTP "Accept" header value

plain text

single-value responses

text/plain

XML

complex value responses

application/xml

JSON

complex value responses

application/json

Full and Partial Responses

By default, when a list of entities is requested, only basic fields are included into the response. When a single entry is requested, all the fields are returned. The complex field values can be returned in full or basic form, depending on a specific entity.

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

At this time, the response can sometimes include the fields/elements not specifically requested. This can change in the future versions, so it is recommended to specify all the fields/elements used by the client.

Logging

You can get details on errors and REST request processing in logs\teamcity-rest.log server log.

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

CORS Support

TeamCity REST can be configured to allow cross-origin requests using the rest.cors.origins internal property.

To allow requests from a page loaded from a specific domain:

    • Add the page address (including the protocol and port , do not use wildcards)  to the comma-separated internal property rest.cors.origins, e.g. 

      rest.cors.origins=http://myinternalwebpage.org.com:8080,https://myinternalwebpage.org.com

To enable support for a preflight OPTIONS request:

  1. Add the rest.cors.optionsRequest.allowUnauthorized=true internal property.
  2. Restart the TeamCity server.
  3. Use the '/app/rest/latest' URL for the requests (warning) Do not use '/app/rest', do not use the 'httpAuth' prefix.

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.

API Client Recommendations

When developing a client using REST API, consider the following recommendations:

  • 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 behavior under load from your requests. Make sure not to repeat the request frequently if it takes time to process the request.

TeamCity Data Entities Requests

Projects and Build Configuration/Templates Lists

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>

List of Build Configurations: GET http://teamcity:8111/app/rest/buildTypes
List of Build Configurations of a project: GET http://teamcity:8111/app/rest/projects/<projectLocator>buildTypes 

Get projects with sub-projects/ Build Configurations data and their order as configured by the specified user on the Overview page: GET  http://teamcity:8111/app/rest/projects?locator=selectedByUser:current&fields=count,project(id,parentProjectId,projects(count,project(id),$locator(selectedByUser:current)),buildTypes(count,buildType(id),$locator(selectedByUser:current)))


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

Project Settings

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.

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

VCS Roots

List all VCS roots: GET http://teamcity:8111/app/rest/vcs-roots, add 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 retrieved 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 http://teamcity:8111/app/rest/vcs-roots/<vcsRootLocator>/<field_name>, where <field_name> is "id", "name", "project" (post project locator to "project" to associate a VCS root with a specific project).

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, 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> - 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> - 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, 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>" and value matching condition "<matchType>" (e.g. equals, contains) by the value "<value>".

Build Configuration And Template Settings

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.

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

Features, triggers, agent requirements, artifact and snapshot dependencies follow the same pattern as steps with URLs like:
http://teamcity:8111/app/rest/buildTypes/<buildTypeLocator>/features/<id>
http://teamcity:8111/app/rest/buildTypes/<buildTypeLocator>/triggers/<id>
http://teamcity:8111/app/rest/buildTypes/<buildTypeLocator>/agent-requirements/<id>
http://teamcity:8111/app/rest/buildTypes/<buildTypeLocator>/artifact-dependencies/<id>
http://teamcity:8111/app/rest/buildTypes/<buildTypeLocator>/snapshot-dependencies/<id>

Since TeamCity 10, it is possible to disable/enable artifact dependencies and agent requirements:
 Disable/enable an artifact dependency 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 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.) 

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:XXX' 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)

 Some examples: click to expand 
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>.

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 http://teamcity:8111/app/rest/builds/?locator=<buildLocator>
Get details of a specific build: GET http://teamcity:8111/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/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.

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 "defaultFilter:false" dimension to the build locator. Default filtering varies depending on the specified locator dimensions. e.g. 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 configuration


tag:<tag> - since TeamCity 10 get tagged builds. If a list of tags is specified, e.g. tag:<tag1>, tag:<tag2>, only the builds containing all the specified tags are returned. The legacy tags:<tags> locator is supported for compatibility

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, 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) 

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 following locator: 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, 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

sinceBuild:(<buildLocator>) - limit the list of builds only to those after the one specified
sinceDate:<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 (e.g. "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, e.g. (finishDate:(date:20151123T203446+0100,condition:after) - (finished after November 23, 2015, 20:34:46)

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 

Queued Builds

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

Supported locators:

  • project:<locator>
  • buildType:<locator>

Get details of a queued build:
GET http://teamcity:8111/app/rest/buildQueue/id:XXX

For queued builds with snapshot dependencies, the revisions are available in the revisions element of the queued build node if a revision is fixed (for regular builds without snapshot dependencies it is not).

Get compatible agents for queued builds (useful for builds having "No agents" to run on)
GET http://teamcity:8111/app/rest/buildQueue/id:XXX/compatibleAgents

Examples:
List queued builds per project:
GET http://teamcity:8111/app/rest/buildQueue?locator=project:<locator>

List queued builds per build configuration:
GET  http://teamcity:8111/app/rest/buildQueue?locator=buildType:<locator>

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 for a branch marked as personal with a fixed agent, comment and a custom parameter:

Queued build assignment to an agent pool:

 

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):

 Example command line for the build triggering: click to expand 
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: GET http://teamcity:8111/app/rest/builds/<buildLocator>/tags/
Replace tags: PUT http://teamcity:8111/app/rest/builds/<buildLocator>/tags/  (put the same XML or JSON as returned by GET)
Add tags: POST http://teamcity:8111/app/rest/builds/<buildLocator>/tags/  (post the same XML or JSON as returned by GET or just a plain-text tag name)
(<buildLocator> here should match a single build only)

Build Pinning

Get current pin status: GET http://teamcity:8111/app/rest/builds/<buildLocator>/pin/ (returns "true" or "false" text)
Pin: PUT http://teamcity:8111/app/rest/builds/<buildLocator>/pin/ (the text in the request data is added as a comment for the action)
Unpin: DELETE http://teamcity:8111/app/rest/builds/<buildLocator>/pin/ (the text in the request data is added as a comment for the action)
(<buildLocator> here should match a single build only)

Build Canceling/Stopping

Cancel a running or a queued build: POST the <buildCancelRequest comment='CommentText' readdIntoQueue='false' /> item to the URL of a running or a queued build:

 Example 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"

Stop a running build and readd it to the queue: POST the <buildCancelRequest comment='CommentText' readdIntoQueue='true' /> item to the URL of a running build:

 Example 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"

Expose cancelled build details:

See the canceledInfo element of the build item (available via GET http://teamcity:8111/app/rest/builds/<buildLocator>)

 

Build Artifacts

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

Media-Type: application/octet-stream or a more specific media type (determined from artifact file extension)
Possible error: 400 if the specified path references a directory

GET http://teamcity:8111/app/rest/builds/<build_locator>/artifacts/metadata/<path> (returns information about a build artifact)
Media-Type: application/xml or application/json

GET http://teamcity:8111/app/rest/builds/<build_locator>/artifacts/children/<path> (returns the list of artifact children for directories and archives)
Media-Type: application/xml or application/json
Possible error: 400 if the artifact is neither a directory nor an archive

GET http://teamcity:8111/app/rest/builds/<build_locator>/artifacts/archived/<path>?locator=pattern:<wildcard> (returns the archive containing the list of artifacts under the path specified. The optional locator parameter can have file <wildcard> to limit the files only to those matching the wildcard)
Media-Type: application/zip
Possible error: 400 if the artifact is neither a directory nor an archive<artifact relative name> supports referencing files under archives using "!/" delimiter after the archive name.

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

<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 of the changes included into the build: GET http://teamcity:8111/app/rest/changes?locator=build:(id:<buildId>)
 Get details of an individual change:  GET http://teamcity:8111/app/rest/changes/id:changeId
 Get information about a changed file action: the files node lists changed files. The information about the changed file action is reported via the  changeType  attribute for the files listed as one of the following:  added, edited, removed, copied or unchanged.

Filter all changes by a locator: GET http://teamcity:8111/app/rest/changes?locator=<changeLocator>
Note that the change id is the change's internal id, not the revision. The id can be seen in the change node listed by the REST API or in the URL of the change details (as modId).

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

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

Get all builds with the specified revision: http://teamcity:8111/app/rest/builds?locator=revision(version:XXXX)

<versionedSettingsRevision> 

Since TeamCity 10, <versionedSettingsRevision> is added to represent revision of the versioned settings of the build.

Snapshot dependencies

It is possible to retrieve the entire build chain (all snapshot-dependency-linked builds) for a particular build:

http://teamcity:8111/app/rest/builds?locator=snapshotDependency:(to:(id:XXXX),includeInitial:true),defaultFilter:false
This gets all the snapshot dependency builds recursively for the build with id XXXX

It possible to find all the snapshot-dependent builds for a particular build: 
http://teamcity:8111/app/rest/builds?locator=snapshotDependency:(from:(id:XXXX),includeInitial:true),defaultFilter:false   

Artifact dependencies

Since TeamCity 10.0.3, there is an experimental ability to:


Build Parameters

Get the parameters of a build: http://teamcity:8111/app/rest/builds/id:<build id>/resulting-properties

Build fields

Get single build's field: GET http://teamcity:8111/app/rest/builds/<buildLocator>/<field_name>  (accepts/produces text/plain) where <field_name> is one of "number", "status", "id", "branchName" and other build's bean attributes

Statistics

Get statistics for a single build: GET http://teamcity:8111/app/rest/builds/<buildLocator>/statistics/ only standard/bundled statistic values are listed. See also Custom Charts
Get single build statistics value: GET  http://teamcity:8111/app/rest/builds/<buildLocator>/statistics/<value_name>

Get statistics for a list of builds: GET http://teamcity:8111/app/rest/builds?locator=BUILDS_LOCATOR&fields=build(id,number,status,buildType(id,name,projectName),statistics(property(name,value)))

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: GET  http://teamcity:8111/app/rest/problemOccurrences?locator=build:(BUILD_LOCATOR)

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

Examples:
List all build's tests: GET http://teamcity:8111/app/rest/testOccurrences?locator=build:<buildLocator> 

Get individual test history:
GET  http://teamcity:8111/app/rest/testOccurrences?locator=test:<testLocator>

List build's tests which were muted when the build ran:
GET  http://teamcity:8111/app/rest/testOccurrences?locator=build:(id:XXX),muted:true

List currently muted tests (muted since the failure):
GET http://teamcity:8111/app/rest/testOccurrences?locator=build:(id:XXX),currentlyMuted:true

Supported test locators:

  • "id:<internal test id>" available as a part of the URL on the test history page
  • "name:<full test name>"

Since TeamCity 10 there is experimental support for exposing single test invocations / runs:

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/mutes. Use 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

Supported locators:

  • 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 assigned to a user: http://teamcity:8111/app/rest/investigations?locator=assignee:(<user locator>)

Get investigations for a build configuration: http://teamcity:8111/app/rest/investigations?locator=buildType:(id:XXXX) 

Since TeamCity 2017.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 investigations: POST/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 agents (only authorized agents are included by default): GET http://teamcity:8111/app/rest/agents
List all connected authorized agents: 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)

Add a comment when enabling/disabling and authorizing/unauthorising an agent (since TeamCity 10.0):
Agent enabled/authorized data is exposed in the enabledInfo and authorizedInfo nodes:

GET and PUT requests are supported to the following URLs: 
http://teamcity:8111/app/rest/agents/<agentLocator>/enabledInfo
http://teamcity:8111/app/rest/agents/<agentLocator>/authorized

On PUT only status and comment/text sub-items are taken into account:

 Example of disabling an agent with a comment: click to expand

curl -v -u user:password --request PUT "http://teamcity:8111/app/rest/agents/id:1/enabledInfo" --data "<enabledInfo status='false'><comment><text>commentText</text></comment></enabledInfo>" --header "Content-Type:application/xml"

Get/PUT agent's single field: GET/PUT http://teamcity:8111/app/rest/agents/<agentLocator>/<field name>
Delete a build agent: DELETE http://teamcity:8111/app/rest/agents/<agentLocator>

Agent Pools

Get/modify/remove agent pools:
GET/PUT/DELETE http://teamcity:8111/app/rest/projects/XXX/agentPools/ID

Add an agent pool:
POST the agentPool name='PoolName element to http://teamcity:8111/app/rest/projects/XXX/agentPools

Move an agent to the pool from the previous pool:
POST <agent id='YYY'/> to the pool's agents http://teamcity.url/app/rest/agentPools/id:XXX/agents

Example:

curl -v -u user:password 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:
POST the <project> node to http://teamcity.url/app/rest/agentPools/id:XXX/projects

Delete a project from a pool:
DELETE http://teamcity.url/app/rest/agentPools/id:XXX/projects/id:YYY

Users

List of users: GET http://teamcity:8111/app/rest/users
Get specific user details: GET http://teamcity:8111/app/rest/users/<userLocator>
Create a user: POST http://teamcity:8111/app/rest/users
Update/remove specific user: PUT/DELETE http://teamcity:8111/app/rest/users/ 
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: http://teamcity:8111/app/rest/users/<userLocator>/roles

<userLocator> can be of a form:

  • id:<internal user id> - to reference the user by internal ID
  • username:<user's username> - to reference the user by username/login name

User's single field: GET/PUT http://teamcity:8111/app/rest/users/<userLocator>/<field name>
User's single property: GET/DELETE/PUT http://teamcity:8111/app/rest/users/<userLocator>/properties/<property name>

User Groups

List of groups: GET http://teamcity:8111/app/rest/userGroups
List of users within a group: GET http://teamcity:8111/app/rest/userGroups/key:Group_Key

Create a group: POST http://teamcity:8111/app/rest/userGroups
Delete a group: DELETE http://teamcity:8111/app/rest/userGroups/key:Group_Key

Other

Data Backup

Start backup: POST http://teamcity:8111/app/rest/server/backup?includeConfigs=true&includeDatabase=true&includeBuildLogs=true&fileName=
where <fileName> is the prefix of the file to save backup to. The file will be created in the default backup directory (see more).
Get current backup status (idle/running): GET http://teamcity:8111/app/rest/server/backup

Typed Parameters Specification

List typed parameters:

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.

Since TeamCity 9.1, partial updates of a parameter are possible (currently in an experimental state):

Build Status Icon

Icon that represents a build status:

An .svg icon (recommended): GET http://teamcity:8111/app/rest/builds/<buildLocator>/statusIcon.svg

A .png icon: GET http://teamcity:8111/app/rest/builds/<buildLocator>/statusIcon

Icon that represents build status for several builds (since TeamCity 10.0):
GET request and "strob" build locator dimension:

Example requests:

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:

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:


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: GET http://teamcity:8111/app/rest/server/licensingData


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>

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 "locator" parameter instead with standard build configuration locator.

Request Examples

Request Sending Tool

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

1. Get super user token

3. 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" - 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

Icon

More examples (for TeamCity 8.0) are available in this external posting.

 

 

  • No labels

74 Comments

  1. Yegor Yarko

    A PowerSHell script to get the status of the last build in a project (contributed by one of TeamCity users):

    1. Rick de Pauw

      I tried this script with TeamCity 2017.1, but the locator command won't work.

      Also when I try the below command, I get all  buildTypeId's instead of the one I want:

      $command = "http://1.2.3.4/httpAuth/app/rest/builds/?buildTypeId=XXX_Package"

       

      Here is an updated version of the script which works, but is not perfect:

       

      # A PowerShell script to get the status of the last build in a TeamCity project
      # If there is a new build, download the artifacts as a .zip file.
      $username = "User"
      $password = "Password"
      $domain = ""
      $TcProjectId="XXX_Package"
      $serverAddress = "http://1.2.3.4"
      $command = $serverAddress + "/httpAuth/app/rest/builds/?buildTypeId='" + $TcProjectId + "'&locator=start:0,count:50"
      $downloadUrl = "http://1.2.3.4/repository/downloadAll/XXX_Package/.lastFinished"
      $downloadFile = "C:\Temp\XXXpackage"
      $buildnumber = 0
      If ( Test-Path -Path "TCdownload.txt" )
      {
       $buildnumber = Get-Content -Path "TCdownload.txt"
       Write-Host "Old build number = " $buildnumber
      }
      function Execute-HTTPPostCommand() {
          param(
              [string] $target = $null
          )
        
          $request = [System.Net.WebRequest]::Create($target)
          $request.PreAuthenticate = $true
          $request.Method = "GET"
          $request.Credentials = new-object system.net.networkcredential($username, $password)
          $response = $request.GetResponse()
          $sr = [Io.StreamReader]($response.GetResponseStream())
          $xmlout = $sr.ReadToEnd()
          return $xmlout;
      }
        
      $xml = [xml]$(Execute-HTTPPostCommand $command)
      $xml2 = $xml.builds.build | where { $_.buildTypeId.equals($TcProjectId) }
      Write-Host "TeamCity " $TcProjectId $xml2[0].number $xml2[0].status
      If ($xml2[0].number -gt $buildnumber)
      {
       $downloadFile += $xml2[0].number + ".zip"
       Write-Host "Downloading $downloadFile ..."
       $xml2[0].number | Out-File -FilePath "TCdownload.txt"
       $wc = New-Object System.Net.WebClient
       $wc.Credentials = new-object System.Net.NetworkCredential($username, $password, $domain)
       $wc.DownloadFile($downloadUrl, $downloadFile)
      }
      Write-Host "Done !"
      #Start-Sleep -s 10

       

  2. Slava Yozhkin

    Just found that "count:-1" eliminates size limit. It's really nice feature, and I wonder why "count:0" couldn't work such way.

    Anyway, could you please to mention this in the article?

    1. Yegor Yarko

      Slava,

      I'd not use "count:-1", but use "count:10000". If you really need to get more than 10000 items it does make sense to use paging.
      Also, "count:-1" can stop working in the future versions.

  3. Yegor Yarko

    Sample code to use NTLM authentication for REST request

  4. Yegor Yarko

    Useful comments in the forum on extending REST API

  5. Marc Abramowitz

    We have an open-source project which implements a command-line interface for TeamCity in Python:

    https://github.com/SurveyMonkey/teamcity_cli

    One thing I would love to have is an API function that lets us stream the build log so then we could trigger a job in the CLI and show the log in real-time.

  6. Boris Modylevsky

    Is there REST API for assigning a user to investigate a build or a test? 

    1. Yegor Yarko

      Hi Boris,

      So far no. As you've correctly discovered, there is a feature request for this ability.

      1. Tomer Cohen

        sorry but this can't be done with only the REST API, there is a parameter there named: Internal Build Configuration Id, it starts with btXXX and i can't see it anywhere except the HTML of the calling page.

        can someone verify what i found?

        is there a way to get that string? can i work without it?

         

        Thanks.

  7. Boris Modylevsky

    Is there API for changing name of Build Configuration?

    1. Julia Alexandrova

      Boris, Edson, please try the example below:

      curl -v --basic --user admin:admin --request PUT http://teamcity:8111/httpAuth/app/rest/buildTypes/<buildTypeLocator>/name --data <newName> --header "Content-Type: text/plain"

      1. Edson Castañeda

        it works!, thanks Julia Alexandrova

        1. Boris Modylevsky

          Thanks, Julia Alexandrova

  8. Edson Castañeda

    I also want to change the field "name" of a build configuration, is it possible?

    1. Yegor Yarko

      Yes, text/plain POST to .../app/rest/buildTypes/id:XXXX/name should work.

  9. Marc Abramowitz

     How do I promote a build using the API?

    1. Yegor Yarko

      Marc,

      You can set a build as artifact dependency when triggering a new build (basic idea is to trigger a build manually and check how it looks through REST API in the queue, then use alike presentation to queue new builds). Setting snapshot dependencies is also available, but that is less likely to produce desired results as the build should also be forced to use correct changes.

    2. JL

      With Build ID

      With Build Locator

      Will build with the last successful build of the snapshot dependency

  10. Tomer Cohen

    Hi,

    i'm getting timeout errors sometimes when calling the REST API, i'm calling the API from multiple threads at the same time, from multiple process.

    is there some kind of limitation on the maximum amount of calls the API can handle? i'm getting errors in the teamcity-rest.log about those calls.

    any direction will be very helpfull, Thanks.

    1. Yegor Yarko

      Hi Tomer,

      > is there some kind of limitation on the maximum amount of calls the API can handle?

      No. This needs to be looked into. Please post all the details into the forum or issue tracker.

      BTW, the forum and the tracker are much more suitable for questions than this page.

  11. Simon Breuer

    Hey,

    Can someone give me an example of creating an empty build configuration with powershell ? 

    I always get this Error Message (german): "Der Remoteserver hat einen Fehler zurückgegeben: (400) Ungültige Anforderung."

    1. Yegor Yarko

      Simon,

      The forum is better suited for asking for help. I'd start by making sure you can execute the requests with curl or another tool (see example) and then rewriting the request in PowerShell to get the same request. Also, the body of the 400 response might have more details as to what went wrong.

  12. Marc Abramowitz

    It would be useful I think to add second level headings to this page for particular tasks – e.g.: create a project, edit project parameters, etc.

    Then they would stand out a bit more and also they would appear in the TOC so people could quickly find something.

    It also would be very cool if the TeamCity UI had a button that you could click to show info about how to use the API to get the same info.

  13. Marc Abramowitz

    I wonder if you want to add some examples of posting JSON in the "Request Examples" section. It took me a while to realize that I could use JSON instead of XML.

  14. Boris Modylevsky

    Is there API for removing build from the queue?

    I need the ability to:

    1. Remove all the builds under a specific project
    2. Remove all the personal builds
    3. Remove personal builds of a specific user
    4. Remove builds triggered by specific user
    5. Remove scheduled builds

    1. Julia Alexandrova

      Boris, 
      Yes, it is possible to remove builds from the queue. The Build Requests section on this page (and Queued Builds specifically) detail the required information. Here is an example of deleting queued builds of a specific project:

      1. Boris Modylevsky

        Thank you for the answer. I already figured it out. By the way I developed a simple and fluent library for working with TeamCity API - FluentTc. https://github.com/QualiSystems/FluentTc/wiki/RemoteTc
        Here is a sample code to remove builds from queue by project Id recursively:

         

        FluentTc

         

         

  15. Igor

    1. According to the API (http://teamcity:8111/httpAuth/app/rest/agents/<agentLocator>/<field name>) I can get a single field of agent but when I try to get it (http://tc/httpAuth/app/rest/agents?locator=connected:false,authorized:true/name) I get the following exception: 

    "Error has occurred during request processing (Bad Request). Error: jetbrains.buildServer.server.rest.errors.LocatorProcessException: Invalid value of dimension 'authorized': 'true/name'. Should be 'true', 'false' or 'any'. Invalid request. Check locator is specified correctly."

    2. How can I get "Last communication" date of agent via REST API?

    Thank you.

     

    1. Julia Alexandrova

      Igor, thanks you for the comment. The forum is actually a better place to ask for assistance, this section is more suitable for comments on the documentation.

      1. The request you are referring to gets you a single field of an individual agent. To get the list of names for disconnected authorized agents, try the approach described in the Full and Partial Responses section:

        2.  At the moment the supported fields are: id, name, connected, enabled, authorized, ip.

  16. Jonathan Bilad-on

    Is it possible to filter the tests that contain a certain string? like test:(name:startswith(functional)) ?

  17. Vishwas

    I am writing a plugin for TeamCity. Can I add custom parameters (Like, serverUrl ,adapterUrl etc) in Global Setting under Administration for my plugin?  

  18. Ken Yee

    FYI, wrote a java app to poll teamcity stats and send them to graphite: https://github.com/kenyee/teamcity-graphite-stats

    Hope that helps someone...was really annoyed I couldn't get build queue size into graphite as part of the teamcity health monitoring dashboard so I wrote that (smile)

  19. Theo

    How can I move buildjobs and templates to other project via REST ?

    1. Julia Alexandrova

      Theo, the TeamCity REST API does not allow it at the moment. Please, vote for the related request in our tracker and see the comments for the available workarounds.

       

  20. Petr Skrivanek

    How can get an ID of a test that is used in URL for history of the test (id from table test_names)?

    I found a way through:

    1. http://teamcity:8111/app/rest/testOccurrences?locator=build:(id:<buildId>),test:name:<fullTestName>  - result contains testId
    2. http://teamcity:8111/app/rest/testOccurrences/id:<testId>,build:(id:<buildId>) - result contains required Id (id from table test_names)

    But I have problem with full name of parameterized tests in first query. What is the correct format of parameterized tests for full test name in REST query?

    For example here is full test name: 

    com.mycompany.product.CustomMainTest.testMethod([0][args: isAppliedOnTransactionTypes[0]->true, segmentPermission(onlyAdmin=true)->0)

    Thank you

  21. Shrek

    Hi,

    Can we manage Cloud agents profiles and agents using API. For example I have few agents in Cloud, as per current setup new agents are created if there is no build for certain time. Instead of this I want new agents to be spun up as per schedule. Can I achieve this using Rest API?

    1. Julia Alexandrova

      Hi Shrek,
      At the moment there is no ability to do that. Please vote for and watch the related issue in our tracker. 

  22. Vamshi

    Hi,

    I am trying to disable triggers for a copied project through REST API, is there a way to do that?

    Thanks

    1. Julia Alexandrova


      Vamshi, 
      Please try the following request described in this section above:



  23. Graham Zabel

    List of Build Configurations: GET http://teamcity:8111/httpAuth/app/rest/buildTypes

    Is there a way to GET only unarchived build types/projects?

    1. Graham Zabel

      We would like an option to return only unarchived builds/projects. So something like

      http://teamcity:8111/httpAuth/app/rest/buildTypes/unarchived, or

      http://teamcity:8111/httpAuth/app/rest/buildTypes?archived=false

       

      Thanks!

      1. Julia Alexandrova

        Please try the following:

         

  24. Mark Harold Rivera

    Hello,

    Is it possible to modify the value of an agent requirement using REST? I'm trying to modify it using the curl command below but I always get a Bad Command failure. 

    curl -X PUT -d "<properties><property name=\"property-value\" value=\"sample\"/></properties>" https://sample.com/tc/httpAuth/app/rest/buildTypes/<buildType_ID>/agent-requirements/<requirement_id> --header "Content-Type: application/xml" -H "Accept: application/json"

     

     

  25. Prateek Jain

    Hello,

    I am looking for some API which can return all the builds which are in failed status (i.e. red) for some parent project.

     

    for example : I have one main project with 4-5 sub modules and each and every module have its own build configuration. I need some API to return all the sub modules build status or only failed build status..!!

     

    Thanks in advance (smile) 

  26. Dennis Plöger

    Hi!

    Jetbrains, sorry. I love you, but the REST API documentation is shit. (smile)

    I saw, that there's a Swagger definition endpoint available and generated a structured documentation out of it.

    Have fun.

    Kind regards
    Dennis

  27. Sergey Danilov

    Hey folks,

    Could you please help me with one issue?

    I am struggling to get the complete list of artifacts in the ".lastSuccessful" build in my automatical script.

    The point is: get the list, find one exact artifact in it and get the download link only for this artifact (or just the name would be fine). The "downloadALL" just doesn't work for me since it's a huge waste of traffic and time. 

    i.e. http://<teamcity>/repository/download/<buildtypeid>/<buildid>/<myartifact>.zip

     

    Thanks in advance!

    Sergey

     

    1. Sergey Danilov

      nvm solved, there are build locators for this. 

  28. Dmitry Zagorovsky

    Hi!

    Is it possible to query multiple builds in single query by several build ids in locator? Something like this: /httpAuth/app/rest/builds/?locator=id:(32015,32014)

    Yegor Yarko, could you please help?

    1. Julia Alexandrova

      Dmitry, at present  only a single 'id' dimension is supported in a locator.

  29. Vlad

    Is it possible to get information from third-party reports tabs with API?

  30. Alexander Sokolov

    Can you describe, how to keep password parameter using teamcity rest api?

    i have hidden parameters with <type rawValue="password display='normal'"/> or <type rawValue="password display='hidden'">.

    GET Request returns only property name with type like type above.

    How can I GET value of password parameter value?

  31. Dmitriy Pavlov

    Hi, I am trying to display status icon of build in html page using statusIcon.svg feature

    But branch name displayed in UI includes '/' symbol because branch name comes from GitHub pull request: pull/2296/head

    Following URL works fine: http://teamcity/app/rest/latest/builds/buildType:(id:btId)/statusIcon.svg
    But the following fails with 404: http://teamcity/app/rest/latest/builds/buildType:(id:btId),branch:(name:pull%2F2296%2Fhead)/statusIcon.svg
    Version is 2017.1.2 (build 46812)

    Could you please advise how to build URL in this case? Thank you!

  32. Praveen

    TeamCity UI it shows only success rate. I would like to get historical data of a project (total builds, failed/success ...etc based on each day).  How to get BUILD_LOCATOR i didn't see any explanation in the docs and these are project details or constants id,number,status,buildType(id,name,projectName),statics(property(name,value)) How this API call works? - http://teamcity:8111/app/rest/builds?locator=BUILDS_LOCATOR&fields=build(id,number,status,buildType(id,name,projectName),statistics(property(name,value)))

  33. Anthony Kamau

    Is it possible to use x509 certificates for authentication as opposed to using ~/.curlrc or -u option with curl?

  34. Tushar

    Hi,

    I am running TeamCity Enterprise 2017.1.1, which has an integration set up with Github Enterprise (based on Integrating TeamCity with VCS Hosting Services). I'd like to know which Github repo webhook triggered which project's build in TeamCity. Is there an API to get this information? 

  35. francesco

    Can someone explain me what exactly is a "locator" with the explanation Locator I'm not able to understand it :-| . Problem is, that I suppose it is same for BuildLocator, BuildTypeLocator, etc. My Goal is to create a Build Config with a template via rest API / CURL. But I didn't get this Locator term. Thanks

    1. Julia Alexandrova

      francesco, a locator is essentially a filter for TeamCity entities. For example, GET http://teamcity:8111/app/rest/buildTypes will give you the list of build configurations. If you want details of a particular build configuration, you can use its id as the locator: GET http://teamcity:8111/app/rest/buildTypes?locator=id:<YourBuildConfigId>.
      Different entities support different locators. To get all supported locators for an entity, use $help as a locator, e.g. to get a list of locators for build configuration requests, use http://teamcity:8111/app/rest/buildTypes?locator=$help

  36. francesco

    Julia Alexandrova Thanks. I understood now the Locator (smile) But Is there anywhere an example or an older documentation where I can see how to create a BuildConfig with template and API? I still do not understand how the xml looks like and how I can hand over it through CURL ?? This would be great. Thanks in advance

    1. Julia Alexandrova

      francesco, first you need to get the xml for an existing build configuration based on a template, then you can use the resulting xml, make any required changes and post it.  Please see request examples.   If you need any further assistance,  you are welcome to use our forum or tracker, as this section is for comments on documentation.

  37. Rahul Arora

    Is there any way or api to get time taken by running builds on build agent, means long running build so that we can improve the build performance by taking care of build obstacles ?

  38. Aron Anders Velling

    How do I move a queued build to the top of the build queue using the REST API? 

  39. Slawomir Brzezinski

    How can I get the information that a Project build started to fail due to a 'VCS error' (access denied, in my case)?

    I thought that this will be returned when I use failedToStart:any, e.g.:

    /guestAuth/app/rest/2017.2/builds?locator=defaultFilter:false,failedToStart:any,canceled:any,branch:(default:any,unspecified:any,branched:any),buildType:(id:(XXXXXX))

    but this does not include that error.

     

    Context: I develop the tc-radiate radiator app which is meant to gather all build problems.

     

  40. Anton Anisimov

    I am trying to get a number of changes in a certain build.

    It seems that API is behaving differently whether the locator is passed as part of url or as a parameter. e.g.

    https://<ts-server>/guestAuth/app/rest/changes/build:(id:<build id>) will show the first change in a build

    and

    https://<ts-server>/guestAuth/app/rest/changes?locator=build:(id:<build id>) will show the list of all changes.

    Is it intentional? Is there a way to get all changes as a list using the "in url" notation?

  41. Maximus

    Is there an api to pause/resume the Build Queue on TC server?

  42. Yegor Yarko

    Please use the forum or other way to contact us to ask questions about REST API.

  43. francesco

    Hi all, 

    I'm not able to find soemthing how to create a build config from a template via API. When I try the above mentioned method (POST XML <newBuildTypeDescription name='Conf Name' sourceBuildTypeLocator='id:bt42' copyAllAssociatedSettings='true' shareVCSRoots='false'/> to http://teamcity:8111/app/rest/projects/<projectLocator>/buildTypes) get a "Could not create build type as a copy of a template."

     

    Any Ideas? 

    1. francesco

      For all who are looking for the same topic. The Documentation is unfortunately not so accurate. If you want to create a new Build Configuration from a template via REST API you first have to create an empty Build Configuration and in the 2nd step you have to attach this create Build Config to the template.

      1) Create a new empty build configuration: POST plain text (name) to http://teamcity:8111/httpAuth/app/rest/projects/<projectLocator>/buildTypes

      2) Attach a build configuration to a template:PUT  http://teamcity:8111/httpAuth/app/rest/buildTypes/<buildTypeLocator>/template (PUT accepts template locator with "text/plain" Content-Type)

      (this is not as here described. PUT operation worked for me like this:

      PUT /httpAuth/app/rest/buildTypes/{locator}/template -d "created_empty_build" --header "Content-Type: text/plain" )

      Hope this is helpful!

      Cheers

      1. Julia Alexandrova

        francesco, thank you for your feedback. The documentation is accurate, but I'll try to make the required steps clearer.

        It seems to me (from your first comment)  that you were following instructions on copying a build configuration.

        To create a build configuration based on a template, you can POST a similar XML as returned by GET of the desired template.

  44. Maria

    Hello.
    I try to send a POST request to trigger build with custom parameters, but it ignores the values written in 'node' xml file:

    <build>
     <buildType id="RUN_TESTS"/>
     <properties>
     <property name="BLOCK_OF_TESTS" value="all"/>
     <property name="KIND_OF_TESTS" value="madrugada -k 1"/>
     </properties>
    </build>

    it also ignores the specified buldType ID, it launches always the first build from the list.

    Instead it inherits values set by default for this build.

    Could you please help me to solve this issue.

     

  45. James Hyde

    Is there any way to filter builds to only include those with changes by a specific user? This would also be really useful for the new All Builds page.

  46. Indua

    Im trying to Update project build parameters through Team city API in C#, but I'm getting either 415 error or Underlying connetion closed.

     

    Where as Im able to make Get call to the rest API. 

    I have all required permission to update parameters and I'm passing the my creds while making PUT call to the API

     

  47. Philippe Gref-Viau

    Could you add an example for the 'compatible' agent locator? I had to dig very deep to find a reference to a working example, which turns out to be that one must use "build" and not necessarily "buildType" as the agent locator (like it was mentioned here)

  48. francesco

    Hi everyone,

    I tried everything and I have no idea what to do and the documention has not a solution for my problem. I want to add the following branch specs in the VCS Rott via Rest API:

    +:refs/tags/(*)
    +:refs/heads/*
    +:refs/heads/master

    Per definition, respectively as mentioned in documentation, Branches have to be as a newline-delimited, but everytime I try to PUT them as considered they're (+:refs/tags/(*) +:refs/heads/* +:refs/heads/master) side by side and branches are not recognized.

    I also tried to use the XML where it is set up correct with GET method, delete the VCS Root and to POST it again. But again, they're not as a newline-delimited as they were, they're side by side.

    Anyone an idea? maybe as paramaters?

    Thanks in advance,

    Cheers