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 /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>" /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:

Open /app/rest/server and find the path to the users endpoint.
Enter the resulting URL in the address bar: /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>" /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 /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 an agent requirement.

The Autogenerated REST API Reference | Models documentation section lists all object models 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 the correct value type.

About locators

Locators apply filters to the scope of requested objects. See the REST API Locators article for a detailed description of this concept.

The Autogenerated REST API Reference | Locators section contains an autogenerated documentation for locators available in the TeamCity REST API. Each document in this section lists all available dimensions of a locator with their type and format, and provides examples of the locator usage.

About methods

Methods are operations available for a given object. You can find all methods' descriptions in the Autogenerated REST API Reference | Methods documentation section. 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: 01 June 2022