REST API

General information

REST API is an open-source plugin bundled since TeamCity 5.0.

To use a REST API, an application makes an HTTP request to the TeamCity server and parses the response.

The TeamCity REST API can be used for integrating applications with TeamCity and for those who want to script interactions with the TeamCity server. TeamCity's REST API allows accessing resources (entities) via URL paths.

Note: URL examples on this page assume that your server web UI is accessible via the http://teamcity:8111/ URL.

General Usage Principles

This documentation is not meant to be comprehensive, but just provide some initial knowledge useful for using the API.

You can start by opening http://teamcity:8111/httpAuth/app/rest URL in your browser: this page will give you several pointers to explorer the API.

Use http://teamcity:8111/httpAuth/app/rest/application.wadl to get the full list of supported requests and names of parameters. This is the primary source of discovery for the supported requests and their parameters.

You can start with http://teamcity:8111/httpAuth/app/rest/server request and then drill down following "href" attributes of the entities listed. Please make sure you read through this "General information" section before using the API.

Experiment and read error messages returned: for the most part they should guide you to the right requests.

Suppose you want to know more on the agents and see (in "/app/rest/server" response) that there is a "/app/rest/agents" URL.

try "/app/rest/agents/" request - see the agent list, get the "default" way of linking to an agent from the agent's element href attribute.
get individual agent details via /app/rest/agents/id:10 URL (obtained form "href" for one of the elements of the previous request).
if you send a request to "/app/rest/agents/aaa:bbb" you will get a list of the supported dimensions to find an agent via agent #locator
most of the attributes of the returned agent data (name, connected, authorized) can be used as "<field name>" in "app/rest/agents/<agentLocator>/<field name>" request. Moreover, if you issue a request to "app/rest/agents/id:10/test" URL, you will get a list of the supported fields in the error message

REST Authentication

You can authenticate yourself for the REST API in the following ways:

Using basic HTTP authentication. Provide a valid TeamCity username and password with the request and include "httpAuth" before the "/app/rest" part: e.g.http://teamcity:8111/httpAuth/app/rest/builds
Using access to the server as a guest user (if enabled) include "guestAuth" before the "/app/rest" part: e.g.: http://teamcity:8111/guestAuth/app/rest/builds
if you are checking REST GET requests from within a browser and you are logged in to TeamCity in the browser, you can just use "/app/rest" URL: e.g.http://teamcity:8111/app/rest/builds

There is also a workaround for not sending credentials with every request.

If you perform a request from within a TeamCity build, consider using teamcity.auth.userId/teamcity.auth.password system properties as credentials (within TeamCity settings you can reference them like %system.teamcity.auth.userId% and %system.teamcity.auth.password%). Server URl is available as %teamcity.serverUrl% within a build.

Superuser access

You can use the super user account with REST API: just provide no user name and the generated password logged into the server log.You can use the super user account with REST API: just provide no user name and the generated password logged into the server log.

There is an obsolete REST API specific functionality to achieve the same effect (it will be dropped in the future TeamCity versions so it is not recommended to use it):

There is an obsolete REST API specific functionality to achieve the same effect (it will be dropped in the future TeamCity versions so it is not recommended to use it): If you add the rest.use.authToken=true internal property, any user can perform superuser operation if the authToken is passed in the URL parameter. The authToken will be logged into logs/teamcity-rest.log log. You will still need to supply valid user credentials to use this approach.

REST API Versions

As REST API evolves from one TeamCity version to another, there can be incompatible changes in the protocol.

Under the http://teamcity:8111/app/rest/ or http://teamcity:8111/app/rest/latest URL the latest version is available. Under the http://teamcity:8111/app/rest/ URL, earlier versions CAN be available. Our general policy is to supply TeamCity with at least ONE previous version. In TeamCity 8.0.x you can use "6.0" or "7.0" instead of <version> to get earlier versions of the protocol.

Breaking changes in the API are described in Upgrade Notes section. Please note that additions to the objects returned (such as new XML attributes or elements) are not considered major changes and do not cause the protocol version to increment. Also, the endpoints marked with "Experimental" comment in application.wadl may change without special notice in future versions.

Note: The examples on this page use "/app/rest" relative URL, replace it with the one containing the version if necessary.

URL Structure

The general structure of the URL in the TeamCity API is teamcityserver:port/<authType>/app/rest/<entity>, where

teamcityserver and port define the server name and the port used by TeamCity
<authType> is the authentication type to be used
app means that the request will be directed to the TeamCity application
rest means REST API
<entity> identifies the required entity. Requests that respond with lists (e.g. .../projects, .../buildTypes, .../builds, .../changes, etc.) serve partial items with only the most important item fields and list "href" s of the items within the list. To get the full item data, use the URL constructed with the value of the "href" item attribute.

Locator

In a number of places, you can specify a filter string which defines what entities to filter/affect in the request. This string representation is referred to as "locator" in the scope of REST API.

The locators formats can be:

single value: a string without the following symbols: ,:-( )
dimension, allowing to filter entities suing multiple criteria: <dimension1>:<value1>,<dimension2>:<value2>

Refer to each entity description for the supported locators.

If a request with invalid locators is sent, the error messages often hint on the error and list supported locator dimensions (only non-experimental ones) when an unknown dimension is detected.

Note: If the value contains the "," symbol, it should be enclosed into parentheses: "(<value>)".

Examples

http://teamcity:8111/httpAuth/app/rest/projects gets you the list of projects http://teamcity:8111/httpAuth/app/rest/projects/id:RESTAPIPlugin (example id is used) gets you the full data for the REST API Plugin project. http://teamcity:8111/httpAuth/app/rest/buildTypes/id:bt284/builds?status=SUCCESS&tag=EAP - (example ids are used) to get builds http://teamcity:8111/httpAuth/app/rest/builds/?locator=<buildLocator> - to get builds by build locator. http://teamcity:8111/httpAuth/app/rest/changes?buildType=id:bt133&sinceChange=id:24234 - to get all the changes in the build configuration since the change identified by the id.

Supported HTTP Methods

GET: retrieves the requested data
POST: creates the entity in the request adding it to the existing collection. When posting XML, be sure to specify the "Content-Type: application/xml" HTTP header.
PUT: based on the existence of the entity, creates or updates the entity in the request
DELETE: removes the requested data

Response Formats

The TeamCity REST APIs returns HTTP responses in the following formats:

Format	Response Type	Requested via
plain text	single-value responses	text/plain in the HTTP Accept header
xml	complex value responses	application/xml in the HTTP Accept header
json	complex value responses	application/json in the HTTP Accept header

Logging

You can get details on errors and REST request processing in logs\teamcity-rest.log server log.

If you get an error in response to your request and want to investigate the reason, look into rest-related server logs.

To get details about each processed request, turn on debug logging (e.g. set Logging Preset to "debug-rest" on the Administration/Diagnostics page or modify Log4J "jetbrains.buildServer.server.rest" category) .

CORS Support

TeamCity REST can be configured to allow cross-origin requests. If you want to allow requests from a page loaded from a specific domain, add the domain to comma-separated internal property rest.cors.origins. e.g.

If that does not work, enable debug logging and investigate the log.

TeamCity Data Entities Requests

Projects and Build Configuration/Templates Lists

List of projects: GET http://teamcity:8111/httpAuth/app/rest/projects Project details: GET http://teamcity:8111/httpAuth/app/rest/projects/ < project Locator> <projectLocator> can be id:<internal_project_id> or name:<project%20name>

List of Build Configurations: GET http://teamcity:8111/httpAuth/app/rest/buildTypes List of Build Configurations of a project: GET http://teamcity:8111/httpAuth/app/rest/projects/ < project Locator> /buildTypes List of templates for a particular project: http://teamcity:8111/httpAuth/app/projects/ < project Locator> /templates. List of all the templates on the server (since TeamCity 8.1): http://teamcity:8111/httpAuth/app/rest/buildTypes?locator=templateFlag:true

Build Configuration/Template details: GET http://teamcity:8111/httpAuth/app/rest/buildTypes/ < buildType Locator>

Build Configuration Locator

Most frequently used values for "<buildTypeLocator>" are id:<buildConfigurationOrTemplate_id> and name:<Build%\20Configuration%20name>.

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

Project Settings

Get project details: GET http://teamcity:8111/httpAuth/app/rest/projects/ < project Locator> Delete a project: DELETE http://teamcity:8111/httpAuth/app/rest/projects/ < project Locator> Create a new empty project: POST plain text (name) to http://teamcity:8111/httpAuth/app/rest/projects/

Since TeamCity 8.0: Create (or copy) a project: POST XML <newProjectDescription name='New Project Name' id='newProjectId' copyAllAssociatedSettings='true'><parentProject locator='id:project1'/><sourceProject locator='id:project2'/></newProjectDescription> to http://teamcity:8111/httpAuth/app/rest/projects. Also see an example.

Edit project parameters: GET/DELETE/PUT http://teamcity:8111/httpAuth/app/rest/projects/ < project Locator> /parameters/< parameter_name> (accepts/produces text/plain) Project name/description/archived status: GET/PUT http://teamcity:8111/httpAuth/app/rest/projects/ < project Locator> / <field_name> (accepts/produces text/plain) where <field_name> is one of "name", "description", "archived".

Since TeamCity 8.0 Project's parent project: GET/PUT XML http://teamcity:8111/httpAuth/app/rest/projects/ < project Locator> /parentProject

VCS Roots

List all VCS roots: GET http://teamcity:8111/httpAuth/app/rest/vcs-roots Get details of a VCS root/delete a VCS root: GET/DELETE http://teamcity:8111/httpAuth/app/rest/vcs-roots/ < vcsRoot Locator>, where <vcsRootLocator> is "id:<internal VCS root id>" Create a new VCS root: POST VCS root XML (the one like retrieved for a GET request for VCS root details) to http://teamcity:8111/httpAuth/app/rest/vcs-roots

Also supported: GET/PUT http://teamcity:8111/httpAuth/app/rest/vcs-roots/ < vcsRoot Locator> /properties/<property_name> GET/PUT http://teamcity:8111/httpAuth/app/rest/vcs-roots/ < vcsRoot Locator> / <field_name>, where <field_name> is one of the following: name, shared, project (post project locator to "project" to associate a VCS root with a specific project). Before TeamCity 8.0 project used to be a "projectId".

Build Configuration And Template Settings

Get build configuration details: GET http://teamcity:8111/httpAuth/app/rest/buildTypes/ <buildTypeLocator> (check details about <buildTypeLocator>)

Please note that there is no transaction, etc. 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, etc. Please make sure you pause a build configuration before changing its settings if this aspect is important for your case.

Get/set paused build configuration state: GET/PUT http://teamcity:8111/httpAuth/app/rest/buildTypes/ <buildTypeLocator> /paused (put "true" or "false" text as text/plain) Build configuration settings: GET/DELETE/PUT http://teamcity:8111/httpAuth/app/rest/buildTypes/ <buildTypeLocator> /settings/<setting_name> Build configuration parameters: GET/DELETE/PUT http://teamcity:8111/httpAuth/app/rest/buildTypes/ <buildTypeLocator> /parameters/<parameter_name> (accepts/produces text/plain) Build configuration steps: GET/DELETE http://teamcity:8111/httpAuth/app/rest/buildTypes/ <buildTypeLocator> /steps/<step_id> Create build configuration step: POST http://teamcity:8111/httpAuth/app/rest/buildTypes/ <buildTypeLocator> /steps The XML posted is the same as retrieved by GET request to .../steps/<step_id>

Features, triggers, agent requirements, artifact and snapshot dependencies follow the same pattern as steps with URLs like: http://teamcity:8111/httpAuth/app/rest/buildTypes/ <buildTypeLocator> /features/<id> http://teamcity:8111/httpAuth/app/rest/buildTypes/ <buildTypeLocator> /triggers/ <id> http://teamcity:8111/httpAuth/app/rest/buildTypes/ <buildTypeLocator> /agent-requirements/ <id> http://teamcity:8111/httpAuth/app/rest/buildTypes/ <buildTypeLocator> /artifact-dependencies/ <id> http://teamcity:8111/httpAuth/app/rest/buildTypes/ <buildTypeLocator> /snapshot-dependencies/ <id>

Build configuration VCS roots: GET/DELETE http://teamcity:8111/httpAuth/app/rest/buildTypes/ <buildTypeLocator> /vcs-root-entries/ <id> Attach VCS root to a build configuration: POST http://teamcity:8111/httpAuth/app/rest/buildTypes/ <buildTypeLocator> /vcs-root-entries The XML posted is the same as retrieved by GET request to http://teamcity:8111/httpAuth/app/rest/buildTypes/ <buildTypeLocator> /vcs-root-entries/ <id>

Since TeamCity 8.1 Create a new build configuration with all settings: POST http://teamcity:8111/httpAuth/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:8111/httpAuth/app/rest/projects/<projectLocator>/buildTypes Copy a build configuration: POST XML <newBuildTypeDescription name='Conf Name' sourceBuildTypeLocator='id:bt42' copyAllAssociatedSettings='true' shareVCSRoots='false'/> to http://teamcity:8111/httpAuth/app/rest/projects/ <projectLocator> /buildTypes

Read, detach and attach a build configuration from/to a template: GET/DELETE/PUT http://teamcity:8111/httpAuth/app/rest/buildTypes/ < buildType Locator> /template (PUT accepts a template locator with the "text/plain" Content-Type)

Build Requests

List builds: GET http://teamcity:8111/httpAuth/app/rest/builds/?locator=<buildLocator> Get details of a specific build: GET http://teamcity:8111/httpAuth/app/rest/builds/ <buildLocator> (also supports DELETE to delete a build)

Build Locator

Using a locator in build-related requests you can filter the builds to be returned in the build-related requests. It is referred to as "build locator" in the scope of REST API.

Examples of supported build locators:

id:<internal build id> - use internal build id when you need to refer to a specific build
number:<build number> - to find build by build number, provided build configuration is already specified
<dimension1>:<value1>,<dimension2>:<value2> - to find builds by multiple criteria

The list of supported build locator dimensions: buildType:(<buildTypeLocator>) - only the builds of the specified build configuration tags:<tags> - ","(comma) - a delimited list of build tags (only builds containing all the specified tags are returned) status:<SUCCESS/FAILURE/ERROR> - list builds with the specified status only user:(<userLocator>) - limit builds to only those triggered by the user specified personal:<true/false/any> - limit builds by a personal flag. canceled:<true/false/any> - limit builds by a canceled flag. running:<true/false/any> - limit builds by a running flag. pinned:<true/false/any> - limit builds by a pinned flag.

branch:<branch locator> - limit the builds by branch. <branch locator> can be the branch name (displayed in the UI, or "(name:<name>,default:<true/false/any>,unspecified:<true/false/any>,branched:<true/false/any>)". If not specified, only builds from the default branch are returned.

agentName:<name> - agent name to return only builds ran on the agent with name specified

sinceBuild:(<buildLocator>) - limit the list of builds only to those after the one specified sinceDate:<date> - limit the list of builds only to those started after the date specified. The date should in the same format as dates returned by REST API (e.g. "20130305T170030+0400").

project:<project locator> - limit the list to the builds of the specified project (belonging to any build type directly or indirectly under the project)

count:<number> - serve only the specified number of builds start:<number> - list the builds from the list starting from the position specified (zero-based) lookupLimit:<number> - limit processing to the latest N builds only. If none of the latest N builds match the other specified criteria of the build locator, 404 response is returned.

Note: If build configuration utilizes feature branches then, by default, only builds from default branch are returned. To retrieve all builds, add the following locator: branch:default:any. The whole path will look like this: /httpAuth/app/rest/builds/?locator=buildType:One_Git,branch:default:any

Queued Builds

The features listed in the section are available since TeamCity 8.1:

GET http://teamcity:8111/httpAuth/app/rest/buildQueue

Supported locators:

project:<locator>
buildType:<locator>

Get details of a queued build: GET http://teamcity:8111/httpAuth/app/rest/buildQueue/taskId:XXX For queued builds with snapshot dependencies, the revisions are available in the revisions element of the queued build node if a revision is fixed (for regular builds without snapshot dependencies it is not).

Get compatible agents for queued builds (useful for builds having "No agents" to run on) GET http://teamcity:8111/httpAuth/app/rest/buildQueue/taskId:XXX/compatibleAgents

Examples: List queued builds per project: GET http://teamcity:8111/httpAuth/app/rest/buildQueue?locator=project:<locator>

List queued builds per build configuration: GET http://teamcity:8111/httpAuth/app/rest/buildQueue?locator=buildType: <locator>

Triggering a Build

This is only available since TeamCity 8.1. For earlier versions see Accessing Server by HTTP.

To start a build, send POST request to http://teamcity:8111/httpAuth/app/rest/buildQueue with the "build" node in content - the same node as details of a queued build or finished build. The queued build details will be returned.

When the build is started, the request to the queued build (/app/rest/buildQueue/XXX) will return running/finished build data.

Build node examples

Basic build for a build configuration:

<build>
    <buildType id="buildConfID"/>
</build>

Build for a branch marked as personal with a fixed agent, comment and a custom parameter:

<build personal="true" branchName="logicBuildBranch">
    <buildType id="buildConfID"/>
    <agent id="3"/>
    <comment><text>build triggering comment</text></comment>
    <properties>
        <property name="env.myEnv" value="bbb"/>
    </properties>
</build>

Build on a specified change, forced rebuild of all dependencies and clean sources before the build, moved to the build queue top on triggering. (Please note that the change is set via the change's internal modification id, not revision. The id can be seen in the change node listed by the REST API or in the URL of the change detail UI page):

<build>
  <triggeringOptions cleanSources="true" rebuildAllDependencies="true" queueAtTop="true"/>
  <buildType id="buildConfID"/>
  <lastChanges>
    <change id="modificationId"/>
  </lastChanges>
</build>

Build Tags

Get tags: GET http://teamcity:8111/httpAuth/app/rest/builds/<buildLocator>/tags/ Replace tags: PUT http://teamcity:8111/httpAuth/app/rest/builds/ <buildLocator> /tags/ (put the same XML of JSON as returned by GET) Add tags: POST http://teamcity:8111/httpAuth/app/rest/builds/ <buildLocator> /tags/ (post the same XML of JSON as returned by GET or just a plain-text tag name) (<buildLocator> here should match a single build only)

Build Pinning

Get current pin status: GET http://teamcity:8111/httpAuth/app/rest/builds/<buildLocator>/pin/ (returns "true" or "false" text) Pin: PUT http://teamcity:8111/httpAuth/app/rest/builds/ <buildLocator> /pin/ (the text in the request data is added as a comment for the action) Unpin: DELETE http://teamcity:8111/httpAuth/app/rest/builds/ <buildLocator> /pin/ (the text in the request data is added as a comment for the action) (<buildLocator> here should match a single build only)

Build Canceling/Stopping

POST the <buildCancelRequest comment='CommentText' readdIntoQueue='true' /> item to the URL of a running or queued build.

Note: Readding of builds into the queue is supported for running builds only.

Expose cancelled build details: See the canceledInfo element of the build item (available via GET http://teamcity:8111/httpAuth/app/rest/builds/)

Artifacts

Since TeamCity 8.0 GET http://teamcity:8111/httpAuth/app/rest/builds/ <buildLocator> /artifacts/content/<artifact relative name> (returns the content of a build artifact) Media-Type: application/octet-stream or a more specific media type (determined from artifact name) Possible error: 400 if the specified path references a directory

GET http://teamcity:8111/httpAuth/app/rest/builds/ <buildLocator> /artifacts/metadata/<artifact relative name> (returns information about a build artifact) Media-Type: application/xml or application/json

GET http://teamcity:8111/httpAuth/app/rest/builds/ <buildLocator> /artifacts/children/<artifact relative name> (returns the list of artifact children for directories and archives) Media-Type: application/xml or application/json Possible error: 400 if the artifact is neither a directory nor an archive

<artifact relative name> supports referencing files under archives using "!/" delimiter after the archive name.

Examples: GET http://teamcity:8111/httpAuth/app/rest/builds/id:100/artifacts/children/my-great-tool-0.1.jar!/META-INF|http://teamcity:8111/httpAuth/app/rest/builds/id:100/artifacts/children/my-great-tool-0.1.jar!/META-INF GET http://teamcity:8111/httpAuth/app/rest/builds/id:100/artifacts/metadata/my-great-tool-0.1.jar!/META-INF/MANIFEST.MF|http://teamcity:8111/httpAuth/app/rest/builds/id:100/artifacts/metadata/my-great-tool-0.1.jar!/META-INF/MANIFEST.MF GET http://teamcity:8111/httpAuth/app/rest/builds/id:100/artifacts/metadata/my-great-tool-0.1.jar!/lib/commons-logging-1.1.1.jar!/META-INF/MANIFEST.MF GET http://teamcity:8111/httpAuth/app/rest/builds/id:100/artifacts/content/my-great-tool-0.1.jar!/lib/commons-logging-1.1.1.jar!/META-INF/MANIFEST.MF

Authentication

If you download the artifacts from within a TeamCity build, consider using teamcity.auth.userId/teamcity.auth.password system properties as credentials for the download artifacts request: this way TeamCity will have a way to record that one build used artifacts of another and will display it on the build's Dependencies tab.

Other Build Requests

Build fields

Get single build's field: GET http://teamcity:8111/httpAuth/app/rest/builds/<buildLocator>/<field_name> (accepts/produces text/plain) where <field_name> is one of "number", "status", "id", "branchName" and other build's bean attributes

Statistics

Get build statistics: GET http://teamcity:8111/httpAuth/app/rest/builds/ <buildLocator> /statistics/ only standard/bundled statistic values are listed. See also Custom Charts Get single build statistics value: GET http://teamcity:8111/httpAuth/app/rest/builds/ <buildLocator> /statistics/

Build problems

Since TeamCity 8.1.

GET http://teamcity:8111/httpAuth/app/rest/ problemOccurrences?locator=build:(BUILD_LOCATOR)

Tests

Since TeamCity 8.1

List tests: GET http:// teamcity :8111/app/rest/testOccurrences?locator=<locator dimension>:<value> Supported locators:

build
build:(id:buildId),muted:true (tests which were muted when the build ran)
build:(id:buildId),currentlyMuted:true (failures were not muted, but the tests were muted since the failure)
test
currentlyFailing:true,affectedProject:<project locator>
currentlyMuted:true,affectedProject:<project locator>

Examples: List all build's tests: GET http://teamcity:8111/app/rest/testOccurrences?locator=build:<build locator> http://localhost:8111/app/rest/testOccurrences?locator=build:%3Cbuild%20locator%3E

Get individual test history: GET http:// teamcity :8111/app/rest/testOccurrences?locator=test:<test locator>

List build's tests which were muted when the build ran: GET http://teamcity:8111/app/rest/testOccurrences?locator=build:(id:XXX),muted:true

List currently muted tests (muted since the failure): GEThttp://teamcity:8111/app/rest/testOccurrences?locator=build:(id:XXX),currentlyMuted:true

Investigations

Since TeamCity 8.1

List investigations in the Root project and its subprojects: http://localhost:8111/app/rest/investigations Supported locators:

test: (id:TEST_NAME_ID)
test: (name:FULL_TEST_NAME)
assignee: (<user locator>)
buildType:(id:XXXX)

Examples: Get investigations for a specific test: http://localhost:8111/app/rest/investigations?locator=test:(id:TEST_NAME_ID) http://localhost:8111/app/rest/investigations?locator=test:(name:FULL_TEST_NAME)

Get investigations assigned to a user: http://localhost:8111/app/rest/investigations?locator=assignee:(<user locator>)

Get investigations for a build configuration: http://localhost:8111/app/rest/investigations?locator=buildType:(id:XXXX)

Agents

List of agents: GET http://teamcity:8111/httpAuth/app/rest/agents List of connected agents: GET http://teamcity:8111/httpAuth/app/rest/agents?includeDisconnected=false List of authorized agents: GET http://teamcity:8111/httpAuth/app/rest/agents?includeUnauthorized=false

Agent's single field: GET/PUT http://teamcity:8111/httpAuth/app/rest/agents/<agentLocator>/<field name> See also an example for agent enabling/disabling Since TeamCity 8.1 Delete a build agent: DELETE http://teamcity:8111/httpAuth/app/rest/agents/<agentLocator> /

Agent Pools

Since TeamCity 8.1 Get/modify/remove agent pools: GET/PUT/DELETE http://teamcity:8111/httpAuth/app/rest/projects/XXX/agentPools/ID

Add an agent pool: POST the agentPool name='PoolName' element to http://teamcity:8111/httpAuth/app/rest/projects/XXX/agentPools

Move an agent to the pool from the previous pool: POST <agent id='YYY'/> to the pool's agents http://teamcity.url/app/rest/agentPools/id:XXX/agents

Example:

Assigning Projects to Agent Pools

Since TeamCity 8.1

Add a project to a pool: POST the plain text (name) to http://teamcity.url/app/rest/agentPools/id:XXX/projects

Delete a project from a pool: DELETE http://teamcity.url/app/rest/agentPools/id:XXX/projects/id:YYY

Users

List of users: GET http://teamcity:8111/httpAuth/app/rest/users Get specific user details: GET http://teamcity:8111/httpAuth/app/rest/users/<userLocator> Create a user: POST http://teamcity:8111/httpAuth/app/rest/users Update and since TeamCity 8.1 remove specific user: PUT/DELETE http://teamcity:8111/httpAuth/app/rest/users/ <userLocator> For POST and PUT requests for a user, post data in the form retrieved by the corresponding GET request. Only the following attributes/elements are supported: name, username, email, password, roles, groups, properties. Work with user roles: http://teamcity:8111/httpAuth/app/rest/users/ <userLocator> /roles

<userLocator> can be of a form:

id:<internal user id> - to reference the user by internal ID
username:<user's username> - to reference the user by username/login name

User's single field: GET/PUT http://teamcity:8111/httpAuth/app/rest/users/<userLocator>/<field name> User's single property: GET/DELETE/PUT http://teamcity:8111/httpAuth/app/rest/users/<userLocator>/properties/<property name>

User Groups

List of groups: GET http://teamcity:8111/httpAuth/app/rest/userGroups List of users within a group: http://teamcity:8111/httpAuth/app/rest/userGroups/key:Group_Key

Create a group: POST http://teamcity:8111/httpAuth/app/rest/userGroups Delete a group: DELETE http://teamcity:8111/httpAuth/app/rest/userGroups/key:Group_Key

Other

Data Backup

Start backup: POST http://teamcity:8111/httpAuth/app/rest/server/backup?includeConfigs=true&includeDatabase=true&includeBuildLogs=true&fileName= where <fileName> is the prefix of the file to save backup to. The file will be created in the default backup directory (see more). Get current backup status (idle/running): GET http://teamcity:8111/httpAuth/app/rest/server/backup

Typed Parameters Specification

Since TeamCity 8.1

List typed parameters:

for a project: http://teamcity:8111/httpAuth/app/rest/projects/<locator>/parameters
for a build configuration:http://teamcity:8111/httpAuth/app/rest/buildTypes/ <locator> /parameters The information returned is: parameters count, property name, value, and type. The rawValue of the type element is the parameter specification as defined in the UI.

Get details of a specific parameter: GET to http://teamcity:8111/httpAuth/app/rest/buildTypes/ <locator> /parameters/<name>. Accepts/returns plain-text, XML, JSON. Supply Response-Formats to the request.

Create a new parameter: POST the same XML or JSON or just plain-text as returned by GET to http://teamcity:8111/httpAuth/app/rest/buildTypes/ <locator> /parameters/. Secure data parameters, i.e type=password, are listed, but the values are not displayed.

Build Status Icon

Icon that represents build status: GET http://teamcity:8111/httpAuth/app/rest/builds/<buildLocator>/statusIcon This allows embedding a build status icon into any HTML page with a simple img tag:

For build configuration with internal id "btXXX":
Status of the last build: <img src="http://teamcity:8111/app/rest/builds/buildType:(id:btXXX)/statusIcon"/>
Status of the last build tagged with tag "myTag": <img src="http://teamcity:8111/app/rest/builds/buildType:(id:btXXX),tag:myTag/statusIcon"/>

All other Build-Locator are supported. If the returned image contains "no permission" text, ensure that one of the following is true:

the server has the guest user access enabled and the guest user has permissions to access the build configuration referenced, or
the build configuration referenced has the "enable status widget" option ON
you are logged in to the TeamCity server in the same browser and you have permissions to view the build configuration referenced

CCTray

CCTray-compatible XML is available via http://teamcity:8111/httpAuth/app/rest/cctray/projects.xml.

Without authentication (only build configurations available for guest user): http://teamcity:8111/guestAuth/app/rest/cctray/projects.xml.

Since TeamCity 8.1, CCTray-format XML does not include paused build configurations by default. The URL accepts "locator" parameter instead with standard build configuration locator.

Request Examples

Request Sending Tool

You can use curl command line tool to interact with the TeamCity REST API. Example command:

Where USERNAME, PASSWORD, "teamcity:8111" are to be substituted with real values and data.xml file contains the data to send to the server.

Creating a new project

Using curl tool

Making user a system administrator

1. Enable superuser in REST create a file <TeamCity Data Directory>\config\internal.properties with the content:

(add the line if the file already exists)

2. Get authToken restart the TeamCity server and look into <TeamCity home>\logs\teamcity-rest.log for a line:

Copy this "XXX-YYY-...-ZZZ" string. The string is unique for each server restart

3. Issue the request Get curl command line tool and use a command line:

where "USER" and "PASSWORD" - the credentials of a valid TeamCity user (that you can log in with) "teamcity:8111" - the TeamCity server URL "USERNAME" - the username of the user to be made the system administrator "XXX-YYY-...-ZZZ" - the authentication token retrieved earlier

Last modified: 20 April 2023