About TeamCity REST API
TeamCity provides a REST API for integrating external applications and creating script interactions with the TeamCity server. It allows accessing resources (entities) via URL paths. To use the REST API, an external application makes an HTTP request to the TeamCity server and parses the response.
This documentation comprises general descriptions of TeamCity REST API and autogenerated sections Models, Locators, and Methods, which reflect the state of the current REST API version. This article gives a quick overview of the REST API principles.
REST API is an open-source plugin bundled since TeamCity 5.0.
General Usage Principles
You can start working with the REST API by opening
http://<TeamCity URL>:<port>/app/rest/server URL in your browser: this page gives several pointers to explore the API.
The full list of supported requests and names of parameters is exposed in the Swagger format via the
http://<TeamCity URL>:<port>/app/rest/swagger.json endpoint.
For the list of supported locator dimensions included into the error response, use the
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/request: see the authorized agent list, get the
defaultway of linking to an agent from the agent's element
Get individual agent details via the
/app/rest/agents/id:10URL (obtained from
hreffor one of the elements of the previous request).
If you send a request to
/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 (
authorized) can be used as the
app/rest/agents/<agentLocator>/<field_name>request. Moreover, if you issue a request to the
app/rest/agents/id:10/testURL, you will get a list of the supported fields in the error message.
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 URL>:<port>/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
Using access to the server as a guest user (if enabled) include
If you are checking REST
GETrequests from within a browser, and you are logged in to TeamCity in the browser, you can just use
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
Within a build, the request for current build details can look like:
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.
http://<TeamCity URL>:<port>/app/rest/ or
http://<TeamCity URL>:<port>/app/rest/latest URL the latest version is available.
Earlier versions might be available under the
http://<TeamCity URL>:<port>/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:
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.
The general structure of the URL in the TeamCity API is
portdefine the server name and the port used by TeamCity.
<authType>(optional) is the authentication type to be used, this is generic TeamCity functionality.
app/restis 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/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.
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 the TeamCity REST API.
The locators formats can be:
single value: text without the following symbols:
dimension allowing you to filter entities using multiple criteria:
Note that nested locators should be enclosed in parentheses. See the Common Use Cases section for the most popular locator descriptions. If in doubt what a specific locator supports, send a request with
$helpas the locator value. In the 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.
http://<TeamCity URL>:<port>/app/rest/projectsto get the list of projects.
http://<TeamCity URL>:<port>/app/rest/projects/<projectsLocator>, for example
http://<TeamCity URL>:<port>/app/rest/projects/id:RESTAPIPlugin(example ID is used) to get the full data for the REST API Plugin project.
http://<TeamCity URL>:<port>/app/rest/buildTypes/id:bt284/builds?locator=<buildLocator>, for example
http://<TeamCity URL>:<port>/app/rest/buildTypes/id:bt284/builds?locator=status:SUCCESS,tag:EAP(example IDs are used) to get builds.
http://<TeamCity URL>:<port>/app/rest/builds/?locator=<buildLocator>to get builds by build locator.
Supported HTTP Methods
GET: retrieves the requested data. For example,
.../app/rest/entitiesusually retrieves a list of entities,
.../app/rest/entities/<entity locator>retrieves a single entity
POST: creates the entity from the payload submitted. To create a new entity, one regularly needs to post a single entity data (i.e. as retrieved via GET) to the
.../app/rest/entitiesURL. When posting XML, be sure to specify the
Content-Type: application/xmlHTTP header.
PUT: updates the data from the payload submitted. Accepts the same data format as retrieved via GET request to the same URL. Supported for some entities for URLs like
DELETE: removes the data at the URL, for example, for the
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
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,
To enable support for a preflight OPTIONS request:
Restart the TeamCity server.
/app/rest/latestURL for the requests. Do not use
/app/rest, do not use the
httpAuthprefix. 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
TCSESSIONIDcookie 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
countattribute 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
nextHrefattribute 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
countis 0, it does not mean there are no more items if there is the "nextHref" attribute present.
Do not increase the
lookupLimitvalue 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.
The TeamCity REST APIs returns HTTP responses in the following formats according to the HTTP "Accept" header:
HTTP "Accept" header value
complex value responses
|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
field2 of the top-level entity and for
field2_subfield1 fields". The order of the fields specification plays no role.
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.
Roadmap and Feedback
This documentation is a work in progress. If you have any ideas or requests concerning its development, you are welcome to share it via any convenient feedback channel.
Our next plans:
Improve descriptions and add more details
Add usage examples for locator dimensions
Describe more example use cases
Add usage examples for methods