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.
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:
/app/rest/serverand find the path to the
Enter the resulting URL in the address bar:
/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 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.