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.
To get a list of all projects on the server, use:
GET/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:
GET/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.
To get a specific project, use:
GET/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:
GET/app/rest/projects/id:MyCustomProject
The call returns an entity of Project (or an exception if the project has not been found).
This call will return a list of nested build configurations of the project found under projectLocator
:
GET/app/rest/projects/<projectLocator>/buildTypes
The type of response is BuildTypes.
This call will return a list of nested build templates of the project found under projectLocator
:
GET/app/rest/projects/<projectLocator>/templates
A build template is a special case of a build configuration, so the response type is also BuildTypes.
To get the project features associated with a project, use:
GET/app/rest/projects/<projectLocator>/projectFeatures
The type of response is ProjectFeatures.
tip
For editing, adding, or removing project features, refer to this article.
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:
GET/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:
GET/app/rest/projects/<projectLocator>/order/projects
To apply custom ordering, send an ordered list of build configurations to:
PUT/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:
PUT/app/rest/projects/<projectLocator>/order/projects
Thanks for your feedback!