TeamCity REST API 2020.2 Help

REST API Quick Start

REST API allows accessing TeamCity resources (entities) via their URL paths. To use the REST API, an external application makes an HTTP request to the TeamCity server and parses the response.

To see the main API endpoints, open http://<TeamCity URL>:<port>/app/rest/server in your browser.

Authentication

To perform a successful request to the server, you need to provide credentials for authentication. The best way to do this is to use access tokens. You can generate a token for your user in My Settings & Tools | Access Tokens in TeamCity. Pass this token in the HTTP header Authorization: Bearer <token_value>. For example:

curl --header "Authorization: Bearer <token-value>" http://<TeamCity URL>:<port>/app/rest/builds

Based on the provided token, TeamCity will return a payload only if the scope of the request is permitted to the user who owns this token.

Read about other supported authentication methods in the extended quide.

Supported HTTP methods

  • GET: retrieves the requested data. For example, .../app/rest/entities usually retrieves a list of entities, .../app/rest/entities/<entity_locator> retrieves a single entity.

  • POST: creates the entity from the submitted payload. To create a new entity, one regularly needs to post a single entity data (that is as retrieved via GET) to the .../app/rest/entities URL. When posting XML, be sure to specify the Content-Type: application/xml HTTP header.

  • PUT: updates the data from the submitted payload. Accepts the same data format as retrieved via the GET request to the same URL. Supported for some entities for URLs like .../app/rest/entities/<entity_locator>.

  • DELETE: removes the data at the URL, for example, for .../app/rest/entities/<entity_locator>.

Sending first request

You can try requesting data via REST API right in your browser, via the address bar. Let's request the data about all users registered on the server:

  1. Open http://<TeamCity URL>:<port>/app/rest/server and find the path to the users endpoint.

  2. Enter the resulting URL in the address bar: http://<TeamCity URL>:<port>/app/rest/users. This opens the list of user objects, including their IDs and total number.

To access the same information via curl, use:

curl --header "Authorization: Bearer <token_value>" http://<TeamCity URL>:<port>/app/rest/users

If you want to create a user, use the POST method:

curl -H "Authorization: Bearer <token_value>" -H "Content-Type: application/xml" -v http://<TeamCity URL>:<port>/app/rest/users --data-binary "<user username='john.smith' name='John Smith' email='john.smith@teamcity.com' password='secvalue'></user>"

Check out the Common Use Cases section to see more complex examples.

About models

Models are blueprints for TeamCity entities. They specify a data schema for each object: from a project to agent requirement. In this doсumentation, models of objects are grouped by the major object they relate to.

This documentation allows you to:

  • see all the fields of the object to be created;

  • check the proper object name of the required entity;

  • verify that you use a correct value type.

About locators

Locators apply filters to the scope of requested objects.

In general, a REST API URL looks like this:

http://teamcityserver:port/<authType>/app/rest/<apiVersion>/<restApiPath>?<parameters>

where

  • teamcityserver and port define the TeamCity server name and port.

  • <authType> (optional) is the authentication type to use.

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

  • <apiVersion> (optional) allows selecting a specific version of REST API.

  • <restApiPath>?<parameters> is the REST API part of the URL.

The <restApiPath> part can contain a locator: either a single value or multiple dimensions.

To return a single entity, pass its locator as a text without the ,:-( ) symbols: .../app/rest/<items>/<item_locator>. Usually, <item_locator> is an object ID which you can receive via a GET request or find in the object settings or URL when viewing it in the UI. If <item_locator> matches several items, the first one is returned.

To filter entities by multiple criteria, use locator dimensions in the following format:

<dimension1>:<value1>,<dimension2>:<value2>,<dimension3>:(<dimension3.1>:<value3.1>,<dimension3.2>:<value3.2>)

To learn what dimensions a specific locator supports, you can send a request with $help as the locator value or refer to its description in this documentation.

This documentation:

  • helps to check if the single value is available for a given locator;

  • provides examples of the locator usage;

  • lists all available dimensions of a locator with their type and format.

About methods

Methods are operations available for a given object. For each method, this documentation provides:

  • A short description

  • An endpoint it must be applied to

  • A respective HTTP method

  • Supported parameters with their types

  • A model of a response entity, if applicable

This allows you to:

  • find an exact name of the required operation;

  • make sure you receive the expected entity in the response;

  • see what parameters are required for a method.

Last modified: 21 December 2020