TeamCity REST API Reference 2023.05 Help

Get Project Details

This article contains use cases related to retrieving project details via TeamCity REST API:

  • Get a list of projects on a server or details of a specific project.

  • Get build configurations/templates under a specific project.

  • Get a list of project features.

List Projects

To get a list of all projects on the server, use:

/app/rest/projects

The server will respond with a Projects entity containing up to 100 recent Project entities.
The endpoint response is paginated. Use nextHref or prevHref properties of Projects to navigate the response pages. Alternatively, you can control which projects are returned with the count (number of returned projects) and start (position of the first returned project) dimensions:

/app/rest/projects?locator=count:10,start:15

In this example, the request will return 10 projects starting from the 15th element in the collection.

Get Project Details

To get a specific project, use:

/app/rest/projects/<projectLocator>

The projectLocator parameter is a locator string typed as ProjectLocator. For example, to retrieve a project with the ID MyCustomProject, use:

/app/rest/projects/id:MyCustomProject

The call returns an entity of Project (or an exception if the project has not been found).

List Build Configurations of Project

This call will return a list of nested build configurations of the project found under projectLocator:

/app/rest/projects/<projectLocator>/buildTypes

The type of response is BuildTypes.

List Build Templates of Project

This call will return a list of nested build templates of the project found under projectLocator:

/app/rest/projects/<projectLocator>/templates

A build template is a special case of a build configuration, so the response type is also BuildTypes.

List Project Features

To get the project features associated with a project, use:

/app/rest/projects/<projectLocator>/projectFeatures

The type of response is ProjectFeatures.

List Ordered Build Configurations and Subprojects

TeamCity allows defining custom ordering for build configurations and subprojects. By default, REST API will return these entities listed in the default order. To retrieve a list of build configurations as they appear in the UI, send:

/app/rest/projects/<projectLocator>/order/buildTypes

If there is a custom order defined for the project, the endpoint will return BuildTypes. Otherwise, it will respond with an empty collection.

Similarly, for the list of subprojects, use:

/app/rest/projects/<projectLocator>/order/projects

To apply custom ordering, send an ordered list of build configurations to:

/app/rest/projects/<projectLocator>/order/buildTypes

Here is an example of payload to update the order of build configurations A, B, and C so that C appears before B:

<buildTypes> <buildType id="A" /> <buildType id="C" /> <buildType id="B" /> </buildTypes>
{ "buildType": [ { "id": "A" }, { "id": "C" }, { "id": "B" } ] }

To order subprojects, use:

/app/rest/projects/<projectLocator>/order/projects
Last modified: 29 March 2022