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.
The URL examples on this page assume that your TeamCity server web UI is accessible via the
General Usage Principles
This documentation is not meant to be comprehensive, but just provide some initial knowledge useful for using the API.
The general structure of the URL in the TeamCity API is
portdefine 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
appmeans that the request will be directed to the TeamCity application
restmeans REST API
<entity>identifies the required entity. Requests that respond with lists
/restis 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/<itmes> (e.g. .../
), then the URL regularly accepts "locator" parameter which can filter the items returned. Individual items can regularly be addressed by URL in the form .../app/rest/<itmes>/<item_locators>. Both multiple and single items requests regularly support 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 REST API.
If that does not work, enable debug logging and investigate the log.
API Client Recommendations
When developing a client using REST API it is advised to follow the following recommendations:
- Make root REST API configurable (e.g. make the "app/rest/<version>" part of the URL configurable)
- Ignore (do not error out) item's attributes and sub-items which are unknown to the client
- 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)
- Beware of partial answers when requesting list of items: some requests are paged by default: if necessary, read and process "nextHref" attribute of the response entity for items collections. Related locator dimensions are "count" and "lookupLimit".
- Do not abuse ability to execute automated requests for TeamCity API: do not query 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