This page describes using TeamCity REST API in TeamCity versions 5.x-7.x. For information on REST API in the latest TeamCity version, refer to TeamCity 10.x and 2017.1, for other versions see the corresponding documentation version.

General information

To use a REST API, an application makes an HTTP request to the TeamCity server and parses the response.

The TeamCity REST API can be used for integrating applications with TeamCity and for those who want to script interactions with the TeamCity server. TeamCity's REST API allows accessing resources (entities) via URL paths.

If you perform a request from within a TeamCity build, consider using teamcity.auth.userId/teamcity.auth.password system properties as credentials (within TeamCity settings you can reference them like %system.teamcity.auth.userId% and %system.teamcity.auth.password%).

Superuser access

If you add the "rest.use.authToken=true" internal property, any user can perform superuser operation if the authToken is passed in the URL parameter. The authToken will be logged into logs/teamcity-rest.log log. You will still need to supply valid user credentials to use this approach.

As a rule, single value responses are "text/plain" and complex value responses support both "application/xml" and "application/json". Supply appropriate "Accept" header in the request to get the necessary response type.

If you get an error in response to your request and want to investigate the reason, please look into rest-related server logs.

General Notes

When posting XML, be sure to specify the "Content-Type: application/xml" HTTP header. Requests that respond with collections (.../projects, .../buildTypes, .../builds, .../changes) serve partial items with only the most important item fields. Use URL constructed with the value of the "href" item attribute to get the full item data.

The list of supported build dimensions: buildType:(<buildTypeLocator>) - only the builds of the specified build configuration tags:<tags> - ","(comma) - a delimited list of build tags (only builds containing all the specified tags are returned) status:<SUCCESS/FAILURE/ERROR> - list builds with the specified status only user:(<userLocator>) - limit builds to only those triggered by the user specified personal:<true/false/any> - limit builds by a personal flag. canceled:<true/false/any> - limit builds by a canceled flag. running:<true/false/any> - limit builds by a running flag. pinned:<true/false/any> - limit builds by a pinned flag.

branch:<branch locator> - since TeamCity 7.1 limit the builds by branch. <branch locator> can be the branch name (displayed in the UI, or "(name:<name>,default:<true/false/any>,unspecified:<true/false/any>,branched:<true/false/any>)". If not specified, only builds from the default branch are returned.

agentName:<name> - agent name to return only builds ran on the agent with name specified

sinceBuild:(<buildLocator>) - limit the list of builds only to those after the one specified sinceDate:<date> - limit the list of builds only to those started after the date specified. The date should in the same format as dates returned by REST API (e.g. "20130305T170030+0400").

project:<project locator> - since TeamCity 8.0 limit the list to the builds of the specified project (belonging to any build type directly or indirectly under the project)

count:<number> - serve only the specified number of builds start:<number> - list the builds from the list starting from the position specified (zero-based) lookupLimit:<number> - since TeamCity 7.0 limit processing to the latest N builds only. If none of the latest N builds match the other specified criteria of the build locator, 404 response is returned.

If the value is to contain the "," symbol, it should be enclosed into parentheses: "(<value>)".

Artifacts

Since TeamCity 8.0 GET http://teamcity:8111/httpAuth/app/rest/builds/<buildLocator>/artifacts/content/<artifact relative name> (returns the content of a build artifact) Media-Type: application/octet-stream or a more specific media type (determined from artifact name) Possible error: 400 if the specified path references a directory

GET http://teamcity:8111/httpAuth/app/rest/builds/<buildLocator>/artifacts/children/<artifact relative name> (returns the list of artifact children for directories and archives) Media-Type: application/xml or application/json Possible error: 400 if the artifact is neither a directory nor an archive

Authentication

If you download the artifacts from within a TeamCity build, consider using teamcity.auth.userId/teamcity.auth.password system properties as credentials for the download artifacts request: this way TeamCity will have a way to record that one build used artifacts of another and will display it on the build's Dependencies tab.

Other Build Requests

Build fields: Get single build's field: GET http://teamcity:8111/httpAuth/app/rest/builds/<buildLocator>/<field_name> (accepts/produces text/plain) where <field_name> is one of "number", "status", "id", "branchName" and other build's bean attributes

Build Configuration And Template Settings

Please note that there is no transaction, etc. support for settings editing in TeamCity, so all the settings modified via REST API are taken into account at once. This can result in half-configured builds triggered, etc. Please make sure you pause a build configuration before changing its settings if this aspect is important for your case.

CORS Support

Since TeamCity 7.1, REST can be configured to allow Cross-origin requests. If you want to allow requests from a page loaded from a specific domain, add the domain to comma-separated internal propertyrest.cors.origins. e.g.

rest.cors.origins=google.com,myinternalwebpage.org.com

If that does not work, please enable debug logging and investigate the log lines, which are usually descriptive.

Request Sending Tool

One may use curl command line tool to try REST API from a command line. Example command:

where "USER" and "PASSWORD" - the credentials of a valid TeamCity user (that you can log in with) "teamcity:8111" - the TeamCity server URL "USERNAME" - the username of the user to be made the system administrator "XXX-YYY-...-ZZZ" - the authentication token retrieved earlier