REST API Quick Start
tip
This article gives all the information essential for starting with TeamCity REST API: how to compose a URL, authenticate, and send the first request. It also describes concepts of the API models, locators, and methods. For an extended guide, see this article.
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.
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.
tip
You can use the super user account with REST API: just provide no username and the super user password described here.
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 viaGET
) to the.../app/rest/entities
URL. When posting XML, be sure to specify theContent-Type: application/xml
HTTP header.PUT
: updates the data from the submitted payload. Accepts the same data format as retrieved via theGET
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>
.
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 theusers
endpoint.Enter the resulting URL in the address bar:
/app/rest/users
. This opens the list ofuser
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.
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.
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.
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.
Thanks for your feedback!