Icon

You are viewing the documentation of TeamCity 9.x, which is not the most recently released version of TeamCity.
View this page in TeamCity 10.x and 2017.1 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/httpAuth/app/rest URL in your browser: this page will give you several pointers to explorer the API.

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

You can start with http://teamcity:8111/httpAuth/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.

Experiment and read 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/aaa:bbb", 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:

There is also a workaround for not sending credentials with every request.

If you perform a request from within a TeamCity build, consider using teamcity.auth.userId/teamcity.auth.password system properties as credentials (within TeamCity settings you can reference them as %system.teamcity.auth.userId% and %system.teamcity.auth.password%). The server URl is available as %teamcity.serverUrl% within a build.

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, earlier versions CAN be available. Our general policy is to supply TeamCity with at least ONE previous version.
In TeamCity 9.0.x you can use "8.1" or "7.0" instead of <version> to get earlier versions of the protocol.

Breaking changes in the API are described in 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/<entity>, where

  • teamcityserver and port define the server name and the port used by TeamCity
  • <authType> is the authentication type to be used
  • app means that the request will be directed to the TeamCity application
  • rest means REST API
  • <entity> identifies the required entity. Requests that respond with lists (e.g. .../projects, .../buildTypes, .../builds, .../changes, etc.) serve partial items with only the most important item fields and list "href" s of the items within the list. To get the full item data, use the URL constructed with the value of the "href" item attribute.

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>

Refer to each entity description for the supported locators.

If a request with invalid locators is sent, the error messages often hint on the error and list supported locator dimensions (only non-experimental ones) when an unknown dimension is detected.

Note: If the value contains the "," symbol, it should be enclosed into parentheses: "(<value>)".

Examples

http://teamcity:8111/httpAuth/app/rest/projects gets you the list of projects
http://teamcity:8111/httpAuth/app/rest/projects/<projectsLocator> - http://teamcity:8111/httpAuth/app/rest/projects/id:RESTAPIPlugin (the example id is used) gets you the full data for the REST API Plugin project.
http://teamcity:8111/httpAuth/app/rest/buildTypes/id:bt284/builds?locator=<buildLocator> - http://teamcity:8111/httpAuth/app/rest/buildTypes/id:bt284/builds?locator=status:SUCCESS,tag:EAP - (example ids are used) to get builds
http://teamcity:8111/httpAuth/app/rest/builds/?locator=<buildLocator> - to get builds by build locator.
http://teamcity:8111/httpAuth/app/rest/changes?locator=<changeLocator> - http://teamcity:8111/httpAuth/app/rest/changes?locator=buildType:(id:bt133),sinceChange:(id:24234) - to get all the changes in the build configuration since the change identified by the id.

Supported HTTP Methods

  • GET: retrieves the requested data
  • 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.
  • PUT: based on the existence of the entity, creates or updates the entity in the request
  • DELETE: removes the requested data

Response Formats

The TeamCity REST APIs returns HTTP responses in the following formats:

Format

Response Type

Requested via

plain text

single-value responses

text/plain in the HTTP Accept header

XML

complex value responses

application/xml in the HTTP Accept header

JSON

complex value responses

application/json in the HTTP Accept header

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.
If you want to allow requests from a page loaded from a specific domain, add the domain to comma-separated internal property rest.cors.origins.
e.g.

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

If that does not work, enable debug logging and investigate the log.

TeamCity Data Entities Requests

Projects and Build Configuration/Templates Lists

List of projects: GET http://teamcity:8111/httpAuth/app/rest/projects
Project details: GET http://teamcity:8111/httpAuth/app/rest/projects/<projectLocator>
<projectLocator> can be id:<internal_project_id> or name:<project%20name>

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

Build Configuration/Template details: GET http://teamcity:8111/httpAuth/app/rest/buildTypes/<buildTypeLocator>

Build Configuration Locator

Most frequently used values for "<buildTypeLocator>" are id:<buildConfigurationOrTemplate_id> and name:<Build%20Configuration%20name>.

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

Project Settings

Get project details: GET http://teamcity:8111/httpAuth/app/rest/projects/<projectLocator>
Delete a project: DELETE http://teamcity:8111/httpAuth/app/rest/projects/<projectLocator>
Create a new empty project: POST plain text (name) to http://teamcity:8111/httpAuth/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/httpAuth/app/rest/projects. Also see an example.

Edit project parameters: GET/DELETE/PUT http://teamcity:8111/httpAuth/app/rest/projects/<projectLocator>/parameters/<parameter_name> (produces XML, JSON and plain text depending on the "Accept" header, accepts plan text and (since 9.1) 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/httpAuth/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/httpAuth/app/rest/projects/<projectLocator>/parentProject

VCS Roots

List all VCS roots: GET http://teamcity:8111/httpAuth/app/rest/vcs-roots
Get details of a VCS root/delete a VCS root: GET/DELETE http://teamcity:8111/httpAuth/app/rest/vcs-roots/<vcsRootLocator>, where <vcsRootLocator> is "id:<internal VCS root id>"
Create a new VCS root: POST VCS root XML (the one like retrieved for a GET request for VCS root details) to http://teamcity:8111/httpAuth/app/rest/vcs-roots

Also supported:
GET/PUT http://teamcity:8111/httpAuth/app/rest/vcs-roots/<vcsRootLocator>/properties/<property_name>
GET/PUT  http://teamcity:8111/httpAuth/app/rest/vcs-roots/<vcsRootLocator>/<field_name>, where <field_name> is one of the following: name, shared, project (post project locator to "project" to associate a VCS root with a specific project). Before TeamCity 8.0 project used to be a "projectId".

Build Configuration And Template Settings

Get build configuration details: GET http://teamcity:8111/httpAuth/app/rest/buildTypes/<buildTypeLocator> (check details about <buildTypeLocator>)

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.

Get/set paused build configuration state: GET/PUT http://teamcity:8111/httpAuth/app/rest/buildTypes/<buildTypeLocator>/paused (put "true" or "false" text as text/plain)

Build configuration settings: GET/DELETE/PUT http://teamcity:8111/httpAuth/app/rest/buildTypes/<buildTypeLocator>/settings/<setting_name>
Build configuration parameters: GET/DELETE/PUT
http://teamcity:8111/httpAuth/app/rest/buildTypes/<buildTypeLocator>/parameters/<parameter_name> (produces XML, JSON and plan text depending on the "Accept" header, accepts plain text and (since TeamCity 9.1) 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/httpAuth/app/rest/buildTypes/<buildTypeLocator>/steps/<step_id>

Create build configuration step: POST http://teamcity:8111/httpAuth/app/rest/buildTypes/<buildTypeLocator>/stepsThe 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/httpAuth/app/rest/buildTypes/<buildTypeLocator>/features/<id>
http://teamcity:8111/httpAuth/app/rest/buildTypes/<buildTypeLocator>/triggers/<id>
http://teamcity:8111/httpAuth/app/rest/buildTypes/<buildTypeLocator>/agent-requirements/<id>
http://teamcity:8111/httpAuth/app/rest/buildTypes/<buildTypeLocator>/artifact-dependencies/<id>
http://teamcity:8111/httpAuth/app/rest/buildTypes/<buildTypeLocator>/snapshot-dependencies/<id>

Build configuration VCS roots: GET/DELETE http://teamcity:8111/httpAuth/app/rest/buildTypes/<buildTypeLocator>/vcs-root-entries/<id>
Attach VCS root to a build configuration: POST http://teamcity:8111/httpAuth/app/rest/buildTypes/<buildTypeLocator>/vcs-root-entries. The XML/JSON posted is the same as retrieved by GET request to http://teamcity:8111/httpAuth/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/httpAuth/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/httpAuth/app/rest/projects/<projectLocator>/buildTypes
Copy a build configuration: POST XML <newBuildTypeDescription name='Conf Name' sourceBuildTypeLocator='id:bt42' copyAllAssociatedSettings='true' shareVCSRoots='false'/> to http://teamcity:8111/httpAuth/app/rest/projects/<projectLocator>/buildTypes

Read, detach and attach a build configuration from/to a template: GET/DELETE/PUT  http://teamcity:8111/httpAuth/app/rest/buildTypes/<buildTypeLocator>/template (PUT accepts template locator with "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 Requests

List builds: GET http://teamcity:8111/httpAuth/app/rest/builds/?locator=<buildLocator>
Get details of a specific build: GET http://teamcity:8111/httpAuth/app/rest/builds/<buildLocator>  (also supports DELETE to delete a build)

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.
By default excluded are: not-finished, canceled, failed-to-start, personal, on non-default branch in branched build configurations builds. To return all builds, use "defaultFilter:false" dimension.

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:
buildType:(<buildTypeLocator>) - only the builds of the specified build configuration
tags:<tags> - ","(comma) - a delimited list of build tags. Only builds containing all the specified tags are returned)
status:<SUCCESS/FAILURE/ERROR> - list builds with the specified status only
state: <queued/running/finished> - limit builds by the specified state.
running:<true/false/any> - limit builds by the running flag.
user:(<userLocator>) - limit builds to only those triggered by the user specified
personal:<true/false/any> - limit builds by the personal flag.
canceled:<true/false/any> - limit builds by the canceled flag.
failedToStart:<true/false/any> -  limit builds by the failed to start flag (since TeamCity 9.1)
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>)". 

Note: If a build configuration utilizes feature branches, 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: /httpAuth/app/rest/builds/?locator=buildType:One_Git,branch:default:any

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

project:<project locator> - limit the list to the builds of the specified project (belonging to any build type directly under the project). Before TeamCity 9.1 this traversed projects recursively: with meaning "belonging to any build type directly or indirectly under the project".
affectedProject:<project locator> - (since TeamCity 9.1limit the list to the builds of the specified project (belonging to any build type directly or indirectly under the project) 

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. If none of the latest N builds match the other specified criteria of the build locator, 404 response is returned.

Queued Builds

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

Supported locators:

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

Get details of a queued build:
GET http://teamcity:8111/httpAuth/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/httpAuth/app/rest/buildQueue/id:XXX/compatibleAgents

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

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

Triggering a Build

To start a build, send POST request to http://teamcity:8111/httpAuth/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. (There is a related outstanding issue.)

Build node examples

Basic build for a build configuration:

Build for a branch marked as personal with a fixed agent, comment and a custom parameter:

Build on a specified change, forced rebuild of all dependencies and clean sources before the build, moved to the build queue top on triggering. (Please note that the change is set via the change's internal modification id, not revision. The id can be seen in the change node listed by the REST API or in the URL of the change detail UI page):

 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/httpAuth/app/rest/builds/<buildLocator>/tags/
Replace tags: PUT http://teamcity:8111/httpAuth/app/rest/builds/<buildLocator>/tags/ (put the same XML or JSON as returned by GET)
Add tags: POST http://teamcity:8111/httpAuth/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/httpAuth/app/rest/builds/<buildLocator>/pin/  (returns "true" or "false" text)
Pin: PUT http://teamcity:8111/httpAuth/app/rest/builds/<buildLocator>/pin/ (the text in the request data is added as a comment for the action)
Unpin: DELETE http://teamcity:8111/httpAuth/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/httpAuth/app/rest/builds/<buildLocator>)

 

Build Artifacts

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

GET http://teamcity:8111/httpAuth/app/rest/builds/<build_locator>/artifacts/content/<path> (returns the content of a build artifact)

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/httpAuth/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/httpAuth/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/httpAuth/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/httpAuth/app/rest/builds/id:100/artifacts/children/my-great-tool-0.1.jar\!/META-INF
GET http://teamcity:8111/httpAuth/app/rest/builds/id:100/artifacts/metadata/my-great-tool-0.1.jar\!/META-INF/MANIFEST.MF
GET http://teamcity:8111/httpAuth/app/rest/builds/id:100/artifacts/metadata/my-great-tool-0.1.jar!/lib/commons-logging-1.1.1.jar!/META-INF/MANIFEST.MF
GET http://teamcity:8111/httpAuth/app/rest/builds/id:100/artifacts/content/my-great-tool-0.1.jar!/lib/commons-logging-1.1.1.jar!/META-INF/MANIFEST.MF

Authentication

If you download the 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

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/httpAuth/app/rest/changes?locator=buildType:(id:buildConfigurationId),sinceChange:(id:changeId)
Get pending changes for a build configuration http://teamcity:8111/httpAuth/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)

Snapshot dependencies

Since TeamCity 9.1 there is an experimental ability to retrieve entire build chain (all snapshot-dependency-linked builds) for a particular build:

http://teamcity:8111/httpAuth/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.

Build Parameters

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

Build fields

Get single build's field: GET http://teamcity:8111/httpAuth/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/httpAuth/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/httpAuth/app/rest/builds/<buildLocator>/statistics/<value_name>

Get statistics for a list of builds: GET http://teamcity:8111/httpAuth/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.

Build problems

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

Tests

List tests:
GET http://teamcity:8111/app/rest/testOccurrences?locator=<locator dimension>:<value>
Supported locators:

  • build

  • build:(id:buildId),muted:true (tests which were muted when the build ran)

  • build:(id:buildId),currentlyMuted:true (failures were not muted, but the tests were muted since the failure)

  • test

  • currentlyFailing:true,affectedProject:<project locator>

  • currentlyMuted:true,affectedProject:<project locator>

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

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

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

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)

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

Agents

List of agents: GET http://teamcity:8111/httpAuth/app/rest/agents
List of connected authorized agents: GET http://teamcity:8111/httpAuth/app/rest/agents?locator=connected:true,authorized:true
List of authorized agents: GET http://teamcity:8111/httpAuth/app/rest/agents?locator=authorized:true
Since Teamcity 9.1: List of enabled authorized agents: GET http://teamcity:8111/httpAuth/app/rest/agents?locator=enabled:true,authorized:true

Agent's single field: GET/PUT http://teamcity:8111/httpAuth/app/rest/agents/<agentLocator>/<field name>
See also an example for agent enabling/disabling
Delete a build agent:
DELETE http://teamcity:8111/httpAuth/app/rest/agents/<agentLocator>

Agent Pools

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

Add an agent pool:
POST the agentPool name='PoolName element to http://teamcity:8111/httpAuth/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/httpAuth/app/rest/users
Get specific user details: GET http://teamcity:8111/httpAuth/app/rest/users/<userLocator>
Create a user: POST http://teamcity:8111/httpAuth/app/rest/users
Update/remove specific user: PUT/DELETE http://teamcity:8111/httpAuth/app/rest/users/
For 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/httpAuth/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/httpAuth/app/rest/users/<userLocator>/<field name>
User's single property: GET/DELETE/PUT http://teamcity:8111/httpAuth/app/rest/users/<userLocator>/properties/<property name>

User Groups

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

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

Other

Data Backup

Start backup: POST http://teamcity:8111/httpAuth/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/httpAuth/app/rest/server/backup

Typed Parameters Specification

List typed parameters:

Get details of a specific parameter:
GET to http://teamcity:8111/httpAuth/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/httpAuth/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 build status:

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

Since TeamCity 9.1.2 .svg icon is avaialble: GET http://teamcity:8111/httpAuth/app/rest/builds/<buildLocator>/statusIcon.svg

This allows embedding a build status icon into any HTML page with a simple img tag:

All other <buildLocator> options are supported.
If the returned image contains "no permission" 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

CCTray

CCTray-compatible XML is available via http://teamcity:8111/httpAuth/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/httpAuth/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. Enable superuser in REST
create a file <TeamCity Data Directory>\config\internal.properties with the content:

rest.use.authToken=true

(add the line if the file already exists)

 

2. Get authToken
restart the TeamCity server and look into <TeamCity home>\logs\teamcity-rest.log for a line:

Authentication token for superuser generated: 'XXX-YYY-...-ZZZ'.

Copy this "XXX-YYY-...-ZZZ" string. The string is unique for each server restart

3. Issue the request
Get curl command line tool and use a command line:

curl -v --request PUT http://USER:PASSWORD@teamcity:8111/httpAuth/app/rest/users/username:USERNAME/roles/SYSTEM_ADMIN/g/?authToken=XXX-YYY-...-ZZZ

where
"USER" and "PASSWORD" - the credentials of a valid TeamCity user (that you can log in with)
"teamcity:8111" - the TeamCity server URL
"USERNAME" - the username of the user to be made the system administrator
"XXX-YYY-...-ZZZ" - the authentication token retrieved earlier

Icon

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

 

 

  • No labels

50 Comments

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

  2. 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. 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. Sample code to use NTLM authentication for REST request

  4. Useful comments in the forum on extending REST API

  5. 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. Is there REST API for assigning a user to investigate a build or a test? 

    1. Hi Boris,

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

      1. 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. Is there API for changing name of Build Configuration?

    1. 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"
  8. I also want to change the field "name" of a build configuration, is it possible?

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

  9.  How do I promote a build using the API?

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

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

  15. 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. 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. Is it possible to filter the tests that contain a certain string? like test:(name:startswith(functional)) ?

  17. 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. Is there a way to return all build types or configurations that do not have a compatible agent?

    1. It is not possible to retrieve this information using REST API. Please vote for request: https://youtrack.jetbrains.com/issue/TW-40461. Currently you can use Agents Matrix and the cell's color to check the agents/build configuration compatibility.

  19. Is it possible to retrieve the muted tests for a build while it's still running? In one build step we run all the tests, then run the failing ones again to check against certain unavoidable environmental issues, but we'd prefer not to re-run tests which are muted.

    The trouble is, running the build:id:xxxx,currentlyMuted:true query results in no tests at all, until the build is over, which is kind-of stupid given that I can see the list of muted tests categorised by scope from the top-level project page. I'd rather find that information out through the API rather than parsing HTML for it.

  20. I am new to both TeamCity and also the usage of API's. We have a requirement for an API to search all builds for a specified file, so we can see it's dependencies. any assistance greatly appreciated.

  21. Hi, I'm trying to import projects via API, and I can't fine the way. Is there any call for that? Thanks.

    1. There is no such feature at the moment. Feel free to submit request in our tracker.

  22. Can I get a list of compatible agents for a build type? I know I can ask about compatible agents for a queued build, but I want to set up a dashboard that will warn if someone accidentally locks out a whole pile of builds by changing a meta-runner or something similar  - and preferably before our users start complaining to us!

    1. Currently it's not possible to get this information via REST API. Please vote for the request: https://youtrack.jetbrains.com/issue/TW-40461.

      There is an experimental way to get compatible build configurations for an agent: in theory you can get all the build configurations and iterate agents to get their compatible configurations. Then build a report on those configurations not listed by any agent.

       Also TeamCity provides "Queued builds without compatible agents" server health item when there are queued builds which have no compatible agents.

  23. How to convert the following cURL example in section "Triggering a Build" into an equivalent Python script? 

    curl cmd `curl -v -u user:password http://teamcity.server.url:8111/app/rest/buildQueue --request POST --header "Content-Type:application/xml" --data-binary @build.xml

    I tried the following script (using Python requests module) but got such a response code 400 (Bad Request):

    url = "http://myteamcity.com:8111/httpAuth/app/rest/buildQueue/"
    headers = {'Content-Type': 'application/json'}
    data = json.dumps({'buildTypeId': 'MyTestBuild'})
    r = requests.post(url, headers=headers, data=data, auth=("username", "password"), timeout=10)
    print "r = ", r
    >> r =  <Response [400]>

    If change the Content-Type in headers into Accept, got another response code 415 (Unsupported Media Type):

    headers = {'Accept': 'application/json'}

    >> r = <Response [415]>

    [Update] If send data in xml instead of in json, can get build id and open the build page at my TeamCity. Here is the updated code and returned data in xml:

    headers = {'Content-Type': 'application/xml'}
    data = "<build><buildType id=\"MyTestBuild\"/></build>"
    print "r.text = ", r.text
    >> r.text = <?xml version="1.0" encoding="UTF-8" standalone="yes"?><build id="1121412" buildTypeId="...
     
  24. is there a way to get build times per project w/o getting all finished jobs and looping through everything?

     

    What would really be nice is if you folks had a collectd plugin that could send info like this and queue length to Graphite.

  25. As one of your larger enterprise customers, we would like to see the following information available via REST:

    • GET licence keys of server and agents. so we can map known licence keys to our inventory
    • GET agent utilization statistics, so we can determine under-utilised agents
    • GET database usage, so we can monitor when we are low on disk space
    • etc, etc. lots of metadata could be made available

     

    1. Hi Graham,

      Issue tracker and/or email are more appropriate places to request features and get our responses. I would suggest continuing in a related issue or forum/support ticket if you have further coments.

      > GET licence keys of server and agents. so we can map known licence keys to our inventory

      TW-29236

       > GET agent utilization statistics, so we can determine under-utilised agents

      If Agents/Matrix and Agents/Statistics reports does not address your needs, you can get the raw data by listing all the builds on an agent (via request like .../app/rest/builds?locator=agent:(name:...),defaultFilter:false,state:(finished:true)&fields=$long,build(id,buildTypeId,startDate,finishDate) ) and building your report based on that.

       > GET database usage, so we can monitor when we are low on disk space

      Apart from using built-in disk usage report and server disk space warning, actual disk space on the server machine is best monitored using common OS tools. A report can then be constructed using the actual disk usage numbers and project hierarchy structure data obtained via REST API.

       > etc, etc. lots of metadata could be made available

      Specific feature requests with detailed use cases are welcome in our issue tracker.

  26. Can I specify "Add build to favorites" In the XML for the trigger build API call?

    1. Currently it's not supported, please vote for the request: https://youtrack.jetbrains.com/issue/TW-45745.

  27. How to get builds by specifying multiple tags by TeamCity REST API? 

    I have some builds. Each build has two tags. Tags show module name and version. So tags loogs like one-module and 1.2.3 or two-module and 4.5.6.

    I can do this:

    /httpAuth/app/rest/builds/?locator=tags:one-module,branch:unspecified:any&fields=build(tags(tag))

    I will get this:

    { "build": [ { "tags": { "tag": [ { "name": "1.2.4" }, { "name": "one-module" } ] } }, { "tags": { "tag": [ { "name": "1.2.3" }, { "name": "one-module" } ] } } ] }

    Now I want to get latest build with tags one-module and 1.2.4. How I can do this?

    I try this:

    /httpAuth/app/rest/builds/?locator=tags:one-module,1.2.4,branch:unspecified:any&fields=build(tags(tag))

    But I got this:

    Error has occurred during request processing (Bad Request).
    Error: jetbrains.buildServer.server.rest.errors.LocatorProcessException: Bad locator syntax: Invalid dimension name :'1.2.4'. Should contain only alpha-numeric symbols or be known one. Details: locator: 'tags:one-module,1.2.4,branch:unspecified:any', at position 16
    Invalid request. Check locator is specified correctly.

    I have TeamCity version 9.1.6. TeamCity REST API BuildLocator documentation says:

    tags:<tags> - ","(comma) - a delimited list of build tags (only builds
    containing all the specified tags are returned)

    So, I try to select build by 2 or more tags like this. This doesn't work?

    What I am doing wrong? How I can get build latest build by 2 or more tags?

    1. I just tried tags:(one-build,1.2.3) and this worked. Is this correct syntax? So you just forget to update docs right?

      1. Vladislav Sharikov, sorry if the explanation seems confusing, but as it is stated in the locator section, "If the value contains the "," symbol, it should be enclosed into parentheses: "(<value>)". We changed the tag locator to support multiple tags in TeamCity 10 (see a related issue).

  28. hello everyone, 

    Does any one has know how I get and disabled all triggers in projects?

  29. Hi Julia Alexandrova

    What is the Rest API URL which can be used on Post-Receive bitbucket plugin to poll Team City VCS whenever there is a commit/push/change made to project branches.

    For example: Post-Receive plugin in Bitbucket require a Webhook/Rest API url from Team City to poll when it receive any changes or commits.

     

    http://<user name>:<user password>@<server address>/httpAuth/action.html?add2Queue=<build type Id> is working fine. But, can only be used for one build configuration.
    What is the REST API URL pattern to poll Team City VCS?
    Thanks

     

    1. Rakz, see if this is what you are looking for. Available since TeamCity 10, though.