TeamCity 2021.1 Help

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