TeamCity REST API Reference 2021.2 Help

Manage VCS Roots

This article lists REST API requests concerning VCS roots.

List VCS Roots

To get all VCS roots, use:

GET http://<TeamCity Server host>:<port>/app/rest/vcs-roots

Endpoint responds with VcsRoots entity which contains instances of VcsRoot.

To get specific root(s), use:

GET http://<TeamCity Server host>:<port>/app/rest/vcs-roots/<vcsRootLocator>

The vcsRootLocator is typed as a VcsRootLocator entity. For example, to get a VCS root with ID MyCustomRoot use:

GET http://<TeamCity Server host>:<port>/app/rest/vcs-roots/id:MyCustomRoot

To get all Git-based VCS roots, use:

GET http://<TeamCity Server host>:<port>/app/rest/vcs-roots/type:jetbrains.git

Create VCS Root

To create a new VCS root, POST a VcsRoot entity to:

POST http://<TeamCity Server host>:<port>/app/rest/vcs-roots

Example payload:

<vcs-root id="MyCustomRoot" name="MyCustomRoot" vcsName="jetbrains.git"> <project id="MyCustomProject"/> <properties count="3"> <property name="authMethod" value="ANONYMOUS"/> <property name="branch" value="refs/heads/master"/> <property name="url" value="https://mygitserver.com/myrepo"/> </properties> </vcs-root>
{ "id": "MyCustomRoot", "name": "MyCustomRoot", "vcsName": "jetbrains.git", "project": { "id": "MyCustomProject" }, "properties": { "property": [ { "name": "authMethod", "value": "ANONYMOUS" }, { "name": "branch", "value": "refs/heads/master" }, { "name": "url", "value": "https://mygitserver.com/myrepo" } ] } }

Delete VCS Root

To delete a VCS root, use:

DELETE http://<TeamCity Server host>:<port>/app/rest/vcs-roots/<vcsRootLocator>

Update VCS Root Definition

You can retrieve a certain VCS root property via:

GET http://<TeamCity Server host>:<port>/app/rest/vcs-roots/<vcsRootLocator>/properties/<property_name>

and update it with the PUT request using text/plain body:

PUT http://<TeamCity Server host>:<port>/app/rest/vcs-roots/<vcsRootLocator>/properties/<property_name>

Similarly, you can use GET/PUT to receive and update field values (id, name, or project — the latter accepts ProjectLocator for associating a VCS root with a specific project):

GET http://<TeamCity Server host>:<port>/app/rest/vcs-roots/<vcsRootLocator>/<property_name>
PUT http://<TeamCity Server host>:<port>/app/rest/vcs-roots/<vcsRootLocator>/<property_name>

List VCS Root Instances

To get VCS root instances, use:

GET http://<TeamCity Server host>:<port>/app/rest/vcs-root-instances?locator=<vcsRootInstanceLocator>

vcsRootInstanceLocator is typed as VcsRootInstanceLocator. For example, to get all instances of a VCS root with the MyVCSRoot ID use:

GET http://<TeamCity Server host>:<port>/app/rest/vcs-root-instances?locator=vcsRoot:(id:MyVCSRoot)

Post Commit Hook Notification

To notify TeamCity about a new commit from the commit hook context, use:

POST http://<TeamCity Server host>:<port>/app/rest/vcs-root-instances/commitHookNotification?locator=<vcsRootInstanceLocator>

It schedules checking for changes for the matched VCS root instances and returns a plain-text human-readable message on the action performed; HTTP response 202 in case of successful operation.

Last modified: 13 October 2021