Manage Build Configurations

This article lists REST API requests concerning build configurations and build configuration templates.


Get build configuration/template details	GET http://<TeamCity URL>:<port>/app/rest/buildTypes/<buildConfigurationLocator> Read more on the build configuration locator. Note that there is no transaction, for example 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 and other issues. Make sure you pause a build configuration before changing its settings if this aspect is important for your case. To get aggregated status for several build configurations, see the Build Status Icon article.
Get/set paused build configuration state	GET/PUT http://<TeamCity URL>:<port>/app/rest/buildTypes/<buildTypeLocator>/paused Put `true` or `false` text as text/plain.
Build configuration settings	GET/DELETE/PUT http://<TeamCity URL>:<port>/app/rest/buildTypes/<buildTypeLocator>/settings/<setting_name>
Build configuration parameters	GET/DELETE/PUT http://<TeamCity URL>:<port>/app/rest/buildTypes/<buildTypeLocator>/parameters/<parameter_name> It produces XML, JSON, and plain text depending on the `Accept` header, accepts plain text, XML, and JSON. The `.../parameters/<parameter_name>/name` and `.../parameters/<parameter_name>/value` requests are also supported.
Build configuration steps	GET/DELETE http://<TeamCity URL>:<port>/app/rest/buildTypes/<buildTypeLocator>/steps/<step_id>
Create build configuration step	POST http://<TeamCity URL>:<port>/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.
Features, triggers, agent requirements, artifact, and snapshot dependencies follow the same pattern as steps (above) with the respective URLs	http://<TeamCity URL>:<port>/app/rest/buildTypes/<buildTypeLocator>/features/<id> http://<TeamCity URL>:<port>/app/rest/buildTypes/<buildTypeLocator>/triggers/<id> http://<TeamCity URL>:<port>/app/rest/buildTypes/<buildTypeLocator>/agent-requirements/ http://<TeamCity URL>:<port>/app/rest/buildTypes/<buildTypeLocator>/artifact-dependencies/<id> http://<TeamCity URL>:<port>/app/rest/buildTypes/<buildTypeLocator>/snapshot-dependencies/<id> Since TeamCity 10, it is possible to disable/enable artifact dependencies and agent requirements.
Disable/enable an artifact dependency	PUT http://<TeamCity URL>:<port>/app/rest/buildTypes/<buildTypeLocator>/artifact-dependencies/<id>/disabled Put `true` or `false` text as text/plain.
Build configuration VCS roots	GET/DELETE http://<TeamCity URL>:<port>/app/rest/buildTypes/<buildTypeLocator>/vcs-root-entries/<id>
Attach VCS root to a build configuration	POST http://<TeamCity URL>:<port>/app/rest/buildTypes/<buildTypeLocator>/vcs-root-entries The XML/JSON posted is the same as retrieved by GET request to `http://<TeamCity URL>:<port>/app/rest/buildTypes/<buildTypeLocator>/vcs-root-entries/<id>` except for the secure settings like password: these are not included into responses and should be supplied before POSTing back.
Create a new build configuration with all settings	POST http://<TeamCity URL>:<port>/app/rest/buildTypes The XML/JSON posted is the same as retrieved by GET request. Note that `/app/rest/project/XXX/buildTypes` still uses the previous version notation and accepts another entity.
Create a new empty build configuration	`POST` plain text (name) to `http://<TeamCity URL>:<port>/app/rest/projects/<projectLocator>/buildTypes`.
Copy a build configuration	POST XML <newBuildTypeDescription name='Conf Name' sourceBuildTypeLocator='id:XXX' copyAllAssociatedSettings='true' shareVCSRoots='false'/> to `http://<TeamCity URL>:<port>/app/rest/projects/<projectLocator>/buildTypes`.
Read, detach, and attach a build configuration from/to a template	Since TeamCity 2017.2: GET/DELETE/POST/PUT http://<TeamCity URL>:<port>/app/rest/buildTypes/<buildTypeLocator>/templates Before TeamCity 2017.2: GET/DELETE/POST/PUT http://<TeamCity URL>:<port>/app/rest/buildTypes/<buildTypeLocator>/template Put accepts template locator with the `text/plain` Content-Type).
Set build number counter	curl -v --basic --user <username>:<password> --request PUT http://<<TeamCity URL>:<port>>/app/rest/buildTypes/<buildTypeLocator>/settings/buildNumberCounter --data <new number> --header "Content-Type: text/plain"
Set build number format	curl -v --basic --user <username>:<password> --request PUT http://<<TeamCity URL>:<port>>/app/rest/buildTypes/<buildTypeLocator>/settings/buildNumberPattern --data <new format> --header "Content-Type: text/plain"

Build Configuration Locator

The most frequently used values for <buildTypeLocator> are id:<buildConfigurationOrTemplate_id> and name:<Build%20Configuration%20name>.

Since TeamCity 2017.2, the experimental type locator is supported with one of the values: regular, composite, or deployment.

Other supported dimensions are (these are in experimental state):

internalId – internal ID of the build configuration.
project – <projectLocator> to limit the build configurations to those belonging to a single project.
affectedProject – <projectLocator> to limit the build configurations under a single project (recursively).
template – <buildTypeLocator> of a template to list only build configurations using the template.
templateFlag – boolean value to get only templates or only non-templates.
paused – boolean value to filter paused/not paused build configurations.

Last modified: 21 December 2020