Icon

You are viewing the documentation of TeamCity 10.x and 2017.x, which is not the most recently released version of TeamCity.
View this page in the latest documentation or refer to the listing to choose the documentation corresponding to your TeamCity version.

 

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Fixed broken links

...

http://teamcity:8111/app/rest/projects gets you the list of projects
http://teamcity:8111/app/rest/projects/<projectsLocator>  <projectsLocator> http://teamcity:8111/app/rest/projects/id:RESTAPIPlugin  (the example id is used) gets you the full data for the REST API Plugin project.
http://teamcity:8111/app/rest/buildTypes/id:bt284/builds?locator=<buildLocator> - http://teamcity:8111/app/rest/buildTypes/id:bt284/builds?locator=status:SUCCESS,tag:EAP - (example ids are used) to get builds
http://teamcity:8111/app/rest/builds/?locator=<buildLocator> - to get builds by build locator.

...

TeamCity REST can be configured to allow cross-origin requests using the rest.cors.origins internal property.

 

To allow requests from a page loaded from a specific domain:

    • Add the page address (including the protocol and port , do not use wildcards)  to the comma-separated internal property rest.cors.origins, e.g. 

      rest.cors.origins=http://myinternalwebpage.org.com:8080,https://myinternalwebpage.org.com

 

To enable support for a preflight OPTIONS request:

  1. Add the rest.cors.optionsRequest.allowUnauthorized=true internal property.
  2. Restart the TeamCity server.
  3. Use the '/app/rest/latest' URL for the requests (warning) Do not use '/app/rest', do not use the 'httpAuth' prefix.

If that does not help, enable debug logging and look for related messages. If there are none, capture the browser traffic and messages to investigate the case.

API Client Recommendations

...

List of projects: GET http://teamcity:8111/app/rest/projects
Project details: GET GET http://teamcity:8111/app/rest/projects/<projectLocator>, where <projectLocator> can be id:<internal_project_id> or name:<project%20name>

...

Get project details: GET http://teamcity:8111/app/rest/projects/<projectLocator>/
Delete a project: DELETE http://teamcity:8111/app/rest/projects/<projectLocator>/
Create a new empty project: POST plain text (name) to http://teamcity:8111/app/rest/projects/
Create (or copy) a project: POST XML <newProjectDescription name='New Project Name' id='newProjectId' copyAllAssociatedSettings='true'><parentProject locator='id:project1'/><sourceProject locator='id:project2'/></newProjectDescription> to http://teamcity:8111/app/rest/projects. Also see an example.
Edit project parameters: GET/DELETE/PUT http://teamcity:8111/app/rest/projects/<projectLocator>/parameters/<parameter_name>  (produces XML, JSON and plain text depending on the "Accept" header, accepts plain text and XML and JSON) Also supported are requests .../parameters/<parameter_name>/name and .../parameters/<parameter_name>/value.

...

Project's parent project: GET/PUT XML http://teamcity:8111/app/rest/projects/<projectLocator>/parentProject

Project Features

...

List of project features: http://teamcity:8111/app/rest /projects/<projectLocator>/projectFeatures
List features with filtering: http://teamcity:8111/app/rest/projects/<projectLocator>/projectFeatures?locator=<projectFeaturesLocator> e.g. to find all issue tracker features of GitHub type, use the locator "type:IssueTracker,property(name:type,value:GithubIssues)"
Edit features: GET/DELETE/PUT http://teamcity:8111/app/rest /projects/<projectLocator>/projectFeatures/<featureId>

...

Anchor
vcs_root_instances
vcs_root_instances
List VCS root instances: GET http://teamcity:8111/app/rest/vcs-root-instances?locator=<vcsRootInstancesLocator> 

A " 'VCS root" ' is the setting configured in the TeamCity UI, a "VCS root instance" is the an internal TeamCity entity which is derived from the "VCS root" to perform the actual VCS operation.
If a VCS root has no %-references to parameters, a single VCS root corresponds to a single "VCS root instance".
If a VCS root has %-reference to a parameter and the reference resolves to a different value when the VCS root is attached to different configurations or when custom builds are run, a single "VCS root" can generate several "VCS root instances".

...

Build Configuration/Template details: GET  http://teamcity:8111/app/rest/buildTypes/<buildConfigurationLocator> (details on the Build Configuration locator).

...

To get aggregated status for several build configurations, see Build Status Icon section.

Anchor
buildTypePause
buildTypePause

Get/set paused build configuration state: GET/PUT PUT http://teamcity:8111/app/rest/buildTypes/<buildTypeLocator>/paused (put "true" or "false" text as text/plain)

...

Create build configuration step: POSThttp://teamcity:8111/app/rest/buildTypes/<buildTypeLocator>/steps. The XML/JSON posted is the same as retrieved by GET request to .../steps/<step_id> except for the secure settings like password: these are not included into responses and should be supplied before POSTing back

...

Build Requests

List builds: GET http://teamcity:8111/app/rest/builds/?locator=<buildLocator>

Anchor
buildDelete
buildDelete
Get details of a specific build: GET http://teamcity:8111/app/rest/builds/<buildLocator>  (also supports DELETE to delete a build)

Get the list of build configurations in a project with the status of the last finished build in each build configuration: 
GET http://teamcity:8111/app/rest/buildTypes?locator=affectedProject:(id:ProjectId)&fields=buildType(id,name,builds($locator(running:false,canceled:false,count:1),build(number,status,statusText)))

...

The list of supported build locator dimensions:

project:<project locator> locator> - limit the list to the builds of the specified project (belonging to any build type directly under the project). 
affectedProject:<project locator> locator> - limit the list to the builds of the specified project (belonging to any build type directly or indirectly under the project)
buildType:(<buildTypeLocator>) - only the builds of the specified build configuration

Anchor
tagged
tagged

tag:<tag> - since TeamCity 10 get tagged builds. If a list of tags is specified, e.g. tag:<tag1>, tag:<tag2>, only the builds containing all the specified tags are returned. The legacy tags:<tags> locator is supported for compatibility

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 the personal flag. By default, perfsonal builds are not included.

canceled:<true/false/any> - limit builds by the canceled flag. By default, canceled builds are not included.
failedToStart:<true/false/any> - limit builds by the failed to start flag. By default, canceled builds are not included.

state: <queued/running/finished> - - limit builds by the specified state.
running:<true/false/any> - limit builds by the running flag. By default, running builds are not included.
state:running,hanging:true - fetch hanging builds (since TeamCity 10.0

pinned:<true/false/any> - limit builds by the pinned flag.

Anchor
branchLocator
branchLocator
branch:<branch locator> - 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>)". By default only builds from the default branch are returned. To retrieve all builds, add the following locator: branch:default:any. The whole path will look like this: /app/rest/builds/?locator=buildType:One_Git,branch:default:any

revision:<REVISION> - find builds by revision, e.g. all builds of the given build configuration with the revision: /app/rest/builds?locator=revision:(REVISION),buildType:(id:BUILD_TYPE_ID). See more information below.
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> <date> - limit the list of builds only to those started after the date specified. The date should be in the same format as dates returned by REST API (e.g. "20130305T170030+0400").

Anchor
time
time
queuedDate/startDate/finishDate:(date:<time-date>,build:<build locator>,condition:<before/after>) - filter builds based on the time specified by the build locator, e.g. (finishDate:(date:20151123T203446+0100,condition:after) - (finished after November 23, 2015, 20:34:46)

 

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

Anchor
queuedBuilds
queuedBuilds

Queued Builds

GET http://teamcity:8111/app/rest/buildQueue

Supported locators:

  • project:<locator>
  • buildType:<locator>

Get details of a queued build:
GET http://teamcity:8111/app/rest/buildQueue/id:XXX

For queued builds with snapshot dependencies, the revisions are available in the revisions element of the queued build node if a revision is fixed (for regular builds without snapshot dependencies it is not).

Get compatible agents for queued builds (useful for builds having "No agents" to run on)
GET http://teamcity:8111/app/rest/buildQueue/id:XXX/compatibleAgents

Examples:
List queued builds per project:
GET  GET http://teamcity:8111/app/rest/buildQueue?locator=project:<locator>

List queued builds per build configuration:
GET   GET  http://teamcity:8111/app/rest/buildQueue?locator=buildType:<locator>

...

Triggering a Build

To start a build, send POST request to http://teamcity:8111/app/rest/buildQueue with the "build" node (see below) in content - the same node as details of a queued build or finished build. The queued build details will be returned.

...

Expand
titleExample command line for the build triggering: click to expand
No Format
curl -v -u user:password http://teamcity.server.url:8111/app/rest/buildQueue --request POST --header "Content-Type:application/xml" --data-binary @build.xml

Build Tags

Get tags: GET http://teamcity:8111/app/rest/builds/<buildLocator>/tags/
Replace tags: PUT http://teamcity:8111/app/rest/builds/<buildLocator>/tags/  (put the same XML or JSON as returned by GET)
Add tags: POST http://teamcity:8111/app/rest/builds/<buildLocator>/tags/  (post the same XML or JSON as returned by GET or just a plain-text tag name)
(<buildLocator> here should match a single build only)

...

Get current pin status: GET http://teamcity:8111/app/rest/builds/<buildLocator>/pin/ (returns "true" or "false" text)
Pin: PUT http://teamcity:8111/app/rest/builds/<buildLocator>/pin/ (the text in the request data is added as a comment for the action)
Unpin: DELETE http://teamcity:8111/app/rest/builds/<buildLocator>/pin/ (the text in the request data is added as a comment for the action)
(<buildLocator> here should match a single build only)

...

See the canceledInfo element of the build item (available via GET GET http://teamcity:8111/app/rest/builds/<buildLocator > <buildLocator>)

 

Anchor
build_artifacts
build_artifacts

Build Artifacts

<path> below GET http://teamcity:8111/app/rest/builds/<build_locator>/artifacts/content/<path> (returns the content of a build artifact)

(info)<path> above can be empty for the root of build's artifacts or be a path within the build's artifacts. The path can span into the archive content, e.g. dir/path/archive.zip!/path_within_archive

GET http://teamcity:8111/app/rest/builds/<build_locator>/artifacts/content/<path> (returns the content of a build artifact)

Media-Type: application/octet-stream or a more specific media type (determined from artifact file extension)
Possible error: 400 if the specified path references a directory

GET http://teamcity:8111/app/rest/builds/<build_locator>/artifacts/metadata/<path> (returns information about a build artifact)
Media-Type: application/xml or application/json

GET GET http://teamcity:8111/app/rest/builds/<build_locator>/artifacts/children/<path> (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

GET http://teamcity:8111/app/rest/builds/<build_locator>/artifacts/archived/<path>?locator=pattern:<wildcard> (returns the archive containing the list of artifacts under the path specified. The optional locator parameter can have file <wildcard> to limit the files only to those matching the wildcard)
Media-Type: application/zip
Possible error: 400 if the artifact is neither a directory nor an archive

Wiki Markup
{hidden-data}
Since *TeamCity 9.1*:
"locator" parameter is supported for the artifacts listing requests, e.g. "{{recursive:true,browseArchives:true}}". "recursive:true" dimension allows to list files recursively, "browseArchives:true" treat supported archives as "directories", listing their content
{hidden-data}
<artifact relative name> supports referencing files under archives using "!/" delimiter after the archive name.

Examples:

GET http://teamcity:8111/app/rest/builds/id:100/artifacts/children/my-great-tool-0.1.jar\!/META-INF 
GET http://teamcity:8111/app/rest/builds/id:100/artifacts/metadata/my-great-tool-0.1.jar\!/META-INF/MANIFEST.MF
GET http://teamcity:8111/app/rest/builds/id:100/artifacts/metadata/my-great-tool-0.1.jar!/lib/commons-logging-1.1.1.jar!/META-INF/MANIFEST.MF
GET http://teamcity:8111/app/rest/builds/id:100/artifacts/content/my-great-tool-0.1.jar!/lib/commons-logging-1.1.1.jar!/META-INF/MANIFEST.MF

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.

...

Get the list of all of the changes included into the build: GET http://teamcity:8111/app/rest/changes?locator=build:(id:<buildId>)
Get details of an individual change:  GET http://teamcity:8111/app/rest/changes/id:changeId
Get information about a changed file action : the files node lists changed files. The information about the changed file action is reported via the  changeType  attribute for the files listed as one of the following:  added, edited, removed, copied or unchanged.

Filter all changes by a locator: GET http://teamcity:8111/app/rest/changes?locator=<changeLocator><changeLocator>
Note that the change id is the change's internal id, not the revision. The id can be seen in the change node listed by the REST API or in the URL of the change details (as modId).

...

<lastChanges>
The  <lastChanges>  tag contains information about the last commit included into the build and is only good for re-triggering the build: it contains the TeamCity internal id (the id attribute) associated with the commit, which is necessary for TeamCity to trigger a custom build on the same commit (see the example  above   ).

Revisions

<revisions>

The <revisions> tag the same as revisions table on the build's Changes tab in TeamCity UI: it lists the revisions of all of the VCS repositories associated with this build that will be checked out by the build on the agent. 
A revision might or might not correspond to a change known to TeamCity. e.g. for a newly created build configuration and a VCS root, a revision will have no corresponding change.

...

Get the parameters of a build: http://teamcity:8111/app/rest/builds/id:<build id>/resulting-properties

...

Examples:
List all build's tests: GET http://teamcity:8111/app/rest/testOccurrences?locator=build:<build locator><buildLocator> 

Get individual test history:
GET  GET  http:// teamcity :8111/app/rest/testOccurrences?locator=test:<test locator><testLocator>

List build's tests which were muted when the build ran:
GET  http://teamcity:8111/app/rest/testOccurrences?locator=build:(id:XXX),muted:true

List currently muted tests (muted since the failure):
GET http://teamcity:8111/app/rest/testOccurrences?locator=build:(id:XXX),currentlyMuted:true

...

Get invocations of a test:
GET http://teamcity:8111/app/rest/testOccurrences? locator=build:(id:XXX),test:(id:XXX)&fields=$long,testOccurrence($short,invocations($long))

List all test runs with all the invocations flattened:
GET http://teamcity:8111/app/rest/testOccurrences?locator=build:(id:XXX),test:(id:XXX),expandInvocations:true

Investigations

List investigations in the Root project and its subprojects: http://teamcity:8111/app/rest/investigations

Supported locators:

  • test: (id:TEST_NAME_ID)
  • test: (name:FULL_TEST_NAME)
  • assignee: (<user locator>)
  • buildType:(id:XXXX)

Examples:
Get investigations for a specific test:
http://teamcity:8111/app/rest/investigations?locator=test:(id:TEST_NAME_ID) 
http://teamcity:8111/app/rest/investigations?locator=test:(name:FULL_TEST_NAME)

Get investigations assigned to a user: http://teamcity:8111/app/rest/investigations?locator=assignee:(<user locator>)

Get investigations for a build configuration:   http://teamcity:8111/app/rest/investigations?locator=buildType:(id:XXXX)  

Agents

List all agents: GET http://teamcity:8111/app/rest/agents
List all connected authorized agents: GET http://teamcity:8111/app/rest/agents?locator=connected:true,authorized:true
List all authorized agents: GET http://teamcity:8111/app/rest/agents?locator=authorized:true
List all enabled authorized agents: GET GET http://teamcity:8111/app/rest/agents?locator=enabled:true,authorized:true


Enable/disable an agent: PUT  PUT http://teamcity:8111/app/rest/agents/<agentLocator>/enabled  (put " true " or "false" text as text/plain).  See an example.
Authorize/unauthorize an agent: PUT  PUT http://teamcity:8111/app/rest/agents/<agentLocator>/authorized (put " true " or "false" text as text/plain)

...

Code Block
languagexml
<agent id="1" name="agentName" typeId="1" connected="true" enabled="true" authorized="true" uptodate="true" ip="..........." href="/app/rest/agents/id:1">
 <enabledInfo status="true">
  <comment>
   <user username="userName" id="1" href="/app/rest/users/id:1"/>
   <timestamp>20160406T175040+0300</timestamp>
   <text>newcomment</text>
  </comment>
 </enabledInfo>
 <authorizedInfo status="true">
  <comment>
   <user username="userName" id="1" href="/app/rest/users/id:1"/>
   <timestamp>20160406T183033+0300</timestamp>
  </comment>
 </authorizedInfo>
....
</agent>

GET and PUT requests are supported to the following URLs: 
http://teamcity:8111/app/rest/agents/<agentLocator>/enabledInfo
http://teamcity:8111/app/rest/agents/<agentLocator>/authorized

On PUT only status and comment/text sub-items are taken into account:

...

Get/PUT agent's single field: GET/PUT http://teamcity:8111/app/rest/agents/<agentLocator>/<field name>
Delete a build agent: DELETE DELETE http://teamcity:8111/app/rest/agents/<agentLocator>

Agent Pools

Get/modify/remove agent pools:
GET/PUT/DELETE http://teamcity:8111/app/rest/projects/XXX/agentPools/ID

...

Assigning Projects to Agent Pools

Add a project to a pool:
POST the <project> node to http://teamcity.url/app/rest/agentPools/id:XXX/projects

Delete a project from a pool:
DELETE http://teamcity.url/app/rest/agentPools/id:XXX/projects/id:YYY

Users

List of users: GET http://teamcity:8111/app/rest/users
Get specific user details: GET http://teamcity:8111/app/rest/users/<userLocator>
Create a user: POST http://teamcity:8111/app/rest/users
Update/remove specific user: PUT/DELETE http://teamcity:8111/app/rest/users/ 
For the POST and PUT requests for a user, post data in the form retrieved by the corresponding GET request. Only the following attributes/elements are supported: name, username, email, password, roles, groups, properties.
Work with user roles: http://teamcity:8111/app/rest/users/<userLocator>/roles

...

  • id:<internal user id> - to reference the user by internal ID
  • username:<user's username> - to reference the user by username/login name

User's single field: GET/PUT http://teamcity:8111/app/rest/users/<userLocator>/<field name>
User's single property: GET/DELETE/PUT PUT http://teamcity:8111/app/rest/users/<userLocator>/properties/<property name>

User Groups

List of groups: GET http://teamcity:8111/app/rest/userGroups
List of users within a group: GET http://teamcity:8111/app/rest/userGroups/key:Group_Key

Create a group: POST http://teamcity:8111/app/rest/userGroups
Delete a group: DELETE http://teamcity:8111/app/rest/userGroups/key:Group_Key

Other

Data Backup

Start backup: POST httphttp://teamcity:8111/app/rest/server/backup?includeConfigs=true&includeDatabase=true&includeBuildLogs=true&fileName=
where <fileName> is the prefix of the file to save backup to. The file will be created in the default backup directory (see more).
Get current backup status (idle/running): GET http://teamcity:8111/app/rest/server/backup

...

Get details of a specific parameter:
GET to http://teamcity:8111/app/rest/buildTypes/<locator>/parameters/<name> . Accepts/returns plain-text, XML, JSON. Supply the relevant Content-Type header to the request.

Create a new parameter:
POST the same XML or JSON or just plain-text as returned by GET to http://teamcity:8111/app/rest/buildTypes/<locator>/parameters/. Note that secure parameters, i.e. type=password, are listed, but the values not included into response, so the result should be amended before POSTing back.

...

...

Icon that represents a build status:

A .png icon: GET http://teamcity:8111/app/rest/builds/<buildLocator>/statusIcon
An .svg icon: GET http://teamcity:8111/app/rest/builds/<buildLocator>/statusIcon.svg

Icon that represents build status for several builds (since TeamCity 10.0):
GET  http://teamcity:8111/app/rest/builds/aggregated/<build locator>  request GET  request and "strob" build locator dimension:

...