REST API

General Usage Principles

This documentation is not a complete guide and will only provide some initial knowledge useful for working with the API.

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

You can start by opening http://teamcity:8111/app/rest/server 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 the Swagger format via the http://teamcity:8111/app/rest/swagger.json endpoint.

For the list of supported locator dimensions included into the error response, use the $help locator.

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

Suppose you want to know more on the agents and see (in the /app/rest/server response) that there is an /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 the /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 the <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 in the REST API in the following ways:

• The preferred way to access REST API is by using the token-based HTTP authentication. Provide your personal TeamCity access token generated on My Settings & Tools | Access Tokens in the HTTP header Authorization: Bearer <token-value>. For example:

  curl --header "Authorization: Bearer <token-value>" http://teamcity:8111/app/rest/builds

• Using basic HTTP authentication (it can be slow with certain authentications, see below). Provide a valid TeamCity username and password with the request. You can force basic auth by including httpAuth before the /app/rest part, e.g. http://teamcity:8111/httpAuth/app/rest/builds.

• Using access to the server as a guest user (if enabled) include guestAuth before the /app/rest part, e.g. http://teamcity:8111/guestAuth/app/rest/builds.

• If you are checking REST GET requests from within a browser, and you are logged in to TeamCity in the browser, you can just use /app/rest URL, e.g. http://teamcity:8111/app/rest/builds.

Authentication can be slow when a basic HTTP authentication with a non-built-in module is used. If you want to use basic HTTP authentication instead of token-based one, 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 basic credentials (within TeamCity settings you can reference them as %system.teamcity.auth.userId% and %system.teamcity.auth.password%).

Within a build, the request for current build details can look like:

Superuser access

You can use the super user account with REST API: just provide no username 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.

Earlier versions might be available under the http://teamcity:8111/app/rest/<version> URL. Our general policy is to supply TeamCity with at least one previous version. The REST API protocol version is the TeamCity version where this protocol was first introduced.
The latest legacy version of the protocol is 2018.1: use 2018.1 instead of <version> to access it. Other bundled versions are: 2017.2, 2017.1, 10.0, 9.1, 9.0, 8.1, 8.0.

Breaking changes in the API are described in the related Upgrade Notes section. 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.

URL Structure

The general structure of the URL in the TeamCity API is http://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 an example URL.

• <authType> (optional) is the authentication type to be used, this is generic TeamCity functionality.

• app/rest is the root path of the TeamCity REST API

• <apiVersion> (optional) is a reference to a specific version of REST API.

• <restApiPath>?<parameters> is the REST API part of the URL.
  A typical way to get multiple items is to use <restApiPath> in the form of .../app/rest/<items> (for example, ".../app/rest/builds"). These URLs regularly accept the locator parameter which can filter the items returned. Individual items can regularly be addressed by a URL in the form of .../app/rest/<items>/<item_locator>. This URL always returns a single item. If the <item_locator> locator matches several items, the first one is returned. Both multiple and single items requests regularly support the fields parameter.

Logging

You can get details on errors and REST request processing in the 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 (for example, set Logging Preset to debug-rest on the Administration/Diagnostics page or modify the Log4J jetbrains.buildServer.server.rest category).

CORS Support

The TeamCity REST API 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, wildcards are not supported) to the comma-separated internal property rest.cors.origins. For example, 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. 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 the REST API, consider the following recommendations:

• Make the root REST API URL configurable (for example, allow specifying an alternative for app/rest/<version> part of the URL). This will allow directing 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 the 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 (or all) items, read and process the 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 the "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.

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:

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.

Projects and Build Configuration/Templates Lists

Project Settings

Project Features

Project features (for example, issue trackers, versioned settings, custom charts, shared resources and third-party report tabs) are exposed as entries under the "project" node and via dedicated requests.

VCS Roots

Since TeamCity 10.0:

There are two endpoints dedicated to being used in commit hooks from the version control repositories: POST http://teamcity:8111/app/rest/vcs-root-instances/checkingForChangesQueue?locator=<vcsRootInstancesLocator>

It schedules checking for changes for the matched VCS root instances and returns the list of VCS root instances matched (just like GET http://teamcity:8111/app/rest/vcs-root-instances?locator=<vcsRootInstancesLocator>): POST http://teamcity:8111/app/rest/vcs-root-instances/commitHookNotification?locator=<vcsRootInstancesLocator>

It schedules checking for changes for the matched VCS root instances and returns plain-text human-readable message on the action performed, HTTP response 202 in case of successful operation.

Both perform the same action (put the VCS root instances matched by the <locator>) to the queue for "checking for changes" process and differ only in responses they produce.

Note that since the matched VCS root instances are the same as for ../app/rest/vcs-root-instances?locator=<locator> request and that means that by default only the first 100 are matched and the rest are ignored. If this limit is reached, consider tweaking the <locator> to match fewer instances (recommended) or increase the limit, for example by adding ,count:1000 to the locator.

Cloud Profiles

TeamCity REST API exposes the same cloud integration details as those provided in the TeamCity UI.

Build Configuration And Template Settings

Build Requests

Tests and Build Problems

Supported locators:

• build:(<build locator>) – test run in the build.

• build:(<build locator>),muted:true – failed tests which were muted in the build.

• currentlyFailing:true,affectedProject:<project_locator> – tests currently failing under the project specified (recursively).

• currentlyMuted:true,affectedProject:<project_locator> – tests currently muted under the project specified (recursively). See also the project's Muted Problems tab.

Examples:

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:

Investigations

Agents

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.

User Groups

User Access Tokens

Audit Records

You can filter records by user, system action, build type, and so on (use GET http://teamcity:8111/app/rest/audit?locator=$help to see all available filters).

Data Backup

Typed Parameters Specification

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

• Name: PUT the same XML or JSON as returned by GET to http://teamcity:8111/app/rest/buildTypes/<locator>/parameters/NAME

• Type: GET/PUT accepting XML and JSON as returned by GET to the URL http://teamcity:8111/app/rest/buildTypes/<locator>/parameters/NAME/type

• Type's rawValue: GET/PUT accepting plain text http://teamcity:8111/app/rest/buildTypes/<locator>/parameters/NAME/type/rawValue

Build Status Icon

Icon that represents a build status:

Example request:

For project with the PROJECT_ID ID:

For all active branches in a build configuration with the BUILD_CONF_ID ID:

For request /app/rest/builds/aggregated/<build locator> the status is calculated by list of the builds: app/rest/builds?locator=<build locator>. This allows embedding a build status icon into any HTML page with a simple img tag:

For build configuration with the BUILD_CONF_ID ID:

Status of the last build:

Status of the last build tagged with the myTag tag:

All other build locators are supported.

For example, you can use the following markdown markup to add the build status for GitHub repository for the build configuration with ID TeamCityPluginsByJetBrains_TeamcityGoogleTagManagerPlugin_Build and server https://teamcity.jetbrains.com with guest authentication enabled:

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:

CCTray

CCTray-compatible XML is available via http://teamcity:8111/app/rest/cctray/projects.xml.

Without authentication (only build configurations available for guest user): http://teamcity:8111/guestAuth/app/rest/cctray/projects.xml.

The CCTray-format XML does not include paused build configurations by default. The URL accepts the locator parameter instead with standard build configuration locator.

Creating a new project

Using curl tool:

Making user a system administrator

1. Get super user token.

2. Issue the request.

3. Get curl command line tool and use a command line:

where SUPERUSER_TOKEN is the super user token unique for each server start; teamcity:8111 – the TeamCity server URL; USERNAME – the username of the user to be made the system administrator.