REST API Quick Start

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:

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 Server host>:<port>/app/rest/server and find the path to the users endpoint.

2. Enter the resulting URL in the address bar: http://<TeamCity Server host>:<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:

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

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:

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:

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.