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.
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/entitiesusually 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/entitiesURL. When posting XML, be sure to specify the
Content-Type: application/xmlHTTP header.
PUT: updates the data from the submitted payload. Accepts the same data format as retrieved via the
GETrequest to the same URL. Supported for some entities for URLs like
DELETE: removes the data at the URL, for example, for
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:
http://<TeamCity URL>:<port>/app/rest/serverand find the path to the
Enter the resulting URL in the address bar:
http://<TeamCity URL>:<port>/app/rest/users. This opens the list of
userobjects, including their IDs and total number.
To access the same information via curl, use:
If you want to create a user, use the
Check out the Common Use Cases section to see more complex examples.
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.
Locators apply filters to the scope of requested objects.
In general, a REST API URL looks like this:
portdefine the TeamCity server name and port.
<authType>(optional) is the authentication type to use.
app/restis 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.
<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:
<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.
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.
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.