Manage Build Configurations

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


Get build configuration/template details	GET http://<TeamCity Server host>:<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 Server host>:<port>/app/rest/buildTypes/<buildTypeLocator>/paused Put `true` or `false` text as text/plain.
Build configuration settings	GET/DELETE/PUT http://<TeamCity Server host>:<port>/app/rest/buildTypes/<buildTypeLocator>/settings/<setting_name>
Build configuration parameters	GET/DELETE/PUT http://<TeamCity Server host>:<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 Server host>:<port>/app/rest/buildTypes/<buildTypeLocator>/steps/<step_id>
Create build configuration step	POST http://<TeamCity Server host>:<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 Server host>:<port>/app/rest/buildTypes/<buildTypeLocator>/features/<id> http://<TeamCity Server host>:<port>/app/rest/buildTypes/<buildTypeLocator>/triggers/<id> http://<TeamCity Server host>:<port>/app/rest/buildTypes/<buildTypeLocator>/agent-requirements/ http://<TeamCity Server host>:<port>/app/rest/buildTypes/<buildTypeLocator>/artifact-dependencies/<id> http://<TeamCity Server host>:<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 Server host>:<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 Server host>:<port>/app/rest/buildTypes/<buildTypeLocator>/vcs-root-entries/<id>
Attach VCS root to a build configuration	POST http://<TeamCity Server host>:<port>/app/rest/buildTypes/<buildTypeLocator>/vcs-root-entries The XML/JSON posted is the same as retrieved by GET request to `http://<TeamCity Server host>:<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 Server host>:<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 Server host>:<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 Server host>:<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 Server host>:<port>/app/rest/buildTypes/<buildTypeLocator>/templates Before TeamCity 2017.2: GET/DELETE/POST/PUT http://<TeamCity Server host>:<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 Server host>:<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 Server host>:<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: 20 February 2021