TeamCity REST API Reference 2024.03 Help

Manage Finished Builds

In this article, we explore common use cases of managing finished builds via TeamCity REST API:

  • Operating build tags.

  • Pining and unpinning builds.

  • Retrieving artifacts and build parameters.

  • Labeling builds.

Manage Build Tags

To get tags for a specific build, use:


where buildLocator is a BuildLocator entity. The endpoint responds with a Tags entity.

To add new tags, use:


It accepts either Tags:

<tags> <tag name="tag1"/> <tag name="tag2"/> </tags>
{ "tag": [ { "name": "tag1" }, { "name": "tag2" } ] }

or a text/plain tag name as a body.

To replace existing tags, send Tags entity via


Pin Build

To check if the build is pinned, use:


To pin a build, use:


Any text (text/plain) sent with this request will be used as a comment.

To unpin a build, use:


Any text (text/plain) sent with this request will be used as a comment.

Manage VCS Labels

To find all existing VCS labels of a build, use:


Or use a dedicated endpoint:


To add a new VCS label, use:


where vcsRootInstanceLocator is typed as VcsRootInstanceLocator. The request accepts text/plain.

Get Build Artifacts

To get a content of a specific artifact, use:


where path can be empty for the root of the build's artifacts or be a path within the build's artifacts. The path can span into the archive content, for example, dir/path/!/path_within_archive.

Media-Type of response is usually application/octet-stream or a more specific type (determined by the artifact file extension).

To get the file metadata, use:


To fetch all child items for a directory or archive, use:


To download a certain archived subpath, use:


An optional locator's parameter is wildcard that allows limiting files only to those matching the wildcard. artifact relative name supports referencing files under archives using the !/ delimiter after the archive name.

Media-Type of response is application/zip.


  • Download all zip archives combined into a single .zip. Since the path is empty, artifacts are downloaded from the root artifact directory. The target build is the specific build with the "7703" ID.

  • Combine three specific files from the bin/debug folder into a single "" archive and download it. The artifacts are downloaded from the latest successful finished build.

  • Download a file stored inside the "subfolder1/subfolder2" directory of the "" archive.


Get Build Parameters of Finished Build

To get resulting build parameters of a specific finished build, use:

Last modified: 27 March 2024