On this page:
- General information
- TeamCity Licensing Information Requests
- TeamCity Data Entities Requests
- Projects and Build Configuration/Templates Lists
- Project Settings
- Project Features
- VCS Roots
- Build Configuration And Template Settings
- Build Requests
- Build problems
- User Groups
- Request Examples
REST API is an open-source plugin bundled since TeamCity 5.0.
To use the 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.
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.
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
- try the
"/app/rest/agents/" request - see the authorized agent list, get the "
default" way of linking to an agent from the agent's element
- get individual agent details via
/app/rest/agents/id:10URL (obtained from "
href" for one of the elements of the previous request).
- if you send a request to "
/app/rest/agents/aaa:bbb", you will get the list of the supported dimensions to find an agent via the agent's locator
- most of the attributes of the returned agent data (name, connected, authorized) can be used as "
<field name>" in the "
app/rest/agents/<agentLocator>/<field name>" request. Moreover, if you issue a request to the "
app/rest/agents/id:10/test" URL, you will get a list of the supported fields in the error message
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.
- Using access to the server as a guest user (if enabled) include "
guestAuth" before the "
/app/rest" part: e.g.:
- 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.
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 as
%system.teamcity.auth.password%). The server URl is available as
%teamcity.serverUrl% within a build.
You can use the super user account with REST API: just provide no user name and the generated password logged into the server log.
REST API Versions
As REST API evolves from one TeamCity version to another, there can be incompatible changes in the protocol.
http://teamcity:8111/app/rest/latest URL the latest version is available.
http://teamcity:8111/app/rest/<version> URL, the current version is available and earlier versions CAN be available. Our general policy is to supply TeamCity with at least one previous version.
In TeamCity 10.x for <version> you can use "10.0" for the current and "9.1", "9.0", "8.1" to get earlier versions of the protocol. Protocol version corresponds to the TeamCity version where it was first introduced.
Breaking changes in the API are described in the related 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 a special notice in future versions.
Note: The examples on this page use the "
/app/rest" relative URL, replace it with the one containing the version if necessary.
The general structure of the URL in the TeamCity API is
portdefine the server name and the port used by TeamCity. This page uses "http://teamcity:8111/" as example URL
<authType>(optional) is the authentication type to be used, this is generic TeamCity functionality
app/restis the root path of TeamCity REST API
- <apiVersion> (optional) is a reference to specific version of REST API
- <restApiPath>?<parameters> is the REST API part of the URL
When <restApiPath> represents a collection of items .../app/rest/<itmes> (e.g. .../app/rest/builds), then the URL regularly accepts "locator" parameter which can filter the items returned. Individual items can regularly be addressed by URL in the form .../app/rest/<itmes>/<item_locators>. Both multiple and single items requests regularly support fields parameter.
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 using multiple criteria:
Refer to each entity description below for the most popular locator descriptions.
If in doubt what a specific locator supports, send a request with "$help" as the locator value. In response you will get a textual description of what the locator supports. If a request with invalid locators is sent, the error messages often hint at the error and list the supported locator dimensions as well.
Note: If the value contains the "," symbol, it should be enclosed into parentheses: "(<value>)". The value of a dimension can also be encoded as Base64url and sent as "<dimension>:($base64:<base64-encoded-value>)" instead of "<dimension>:<value>".
http://teamcity:8111/httpAuth/app/rest/projects gets you the list of projects
http://teamcity:8111/httpAuth/app/rest/projects/id:RESTAPIPlugin (the 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?locator=<buildLocator> - http://teamcity:8111/httpAuth/app/rest/buildTypes/id:bt284/builds?locator=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.
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
The TeamCity REST APIs returns HTTP responses in the following formats:
text/plain in the HTTP Accept header
complex value responses
application/xml in the HTTP Accept header
complex value responses
application/json in the HTTP Accept header
Full and Partial Responses
By default, when a list of entities is requested, only basic fields are included into the response. When a single entry is requested, all the fields are returned. The complex field values can be returned in full or basic form, depending on a specific entity.
It is possible to change the set of fields returned for XML and JSON responses for the majority of requests.
This is done by supplying the fields request parameter describing the fields of the top-level entity and sub-entities to return in the response. An example syntax of the parameter is:
field,field2(field2_subfield1,field2_subfield1). This basically means "include field and field2 of the top-level entity and for field2 include field2_subfield1 and field2_subfield1 fields". The order of the fields specification plays no role.
At this time, the response can sometimes include the fields/elements not specifically requested. This can change in the future versions, so it is recommended to specify all the fields/elements used by the client.
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 the Log4J "
jetbrains.buildServer.server.rest" category) .
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 page address (including protocol and port) to comma-separated internal property
To enable support for preflight OPTIONS request, add "rest.cors.optionsRequest.allowUnauthorized=true" internal property, restart the server and use "/app/rest/latest" URL for the requests (not "/app/rest").
If that does not help, enable debug logging and look for related messages. If there are none, capture the browser traffic and messages to investigate the case.
API Client Recommendations
When developing a client using REST API, consider the following recommendations:
- Make root REST API URL configurable (e.g. allow to specify alternative for "app/rest/<version>" part of the URL). This will allow to direct the client to another version of the API if necessary.
- Ignore (do not error out) item's attributes and sub-items which are unknown to the client. New sub-items are sometimes added to the API without version change and this will ensure the client is not affected by the change.
- Set large (and make them configurable) request timeouts. Some API calls can take minutes, especially on a large server.
- Use HTTP sessions to make consecutive requests (use TCSESSIONID cookie returned from the first authenticated response instead of supplying raw credentials all the time). This saves time on authentication which can be significant for external authentication providers.
- Beware of partial answers when requesting list of items: some requests are paged by default. If necessary, read and process "nextHref" attribute of the response entity for items collections. Related locator dimensions are "count" and "lookupLimit".
- Do not abuse the ability to execute automated requests for TeamCity API: do not query the API too frequently and restrict the data requested to only that necessary (using due locators and specifying necessary fields). Check the server behavior under load from your requests. Make sure not to repeat the request frequently if it takes time to process the request.
TeamCity Licensing Information Requests
Since TeamCity 10:
List of license keys:
License key details:
Add license key(s):
POST text/plain newline-delimited keys to
Delete a license key:
TeamCity Data Entities Requests
Projects and Build Configuration/Templates Lists
List of projects: GET
Project details: GET
<projectLocator> can be
List of Build Configurations: GET
List of Build Configurations of a project: GET
Get projects with sub-projects/Build Configurations data and their order as configured by the specified user on the Overview page: GET
List of templates for a particular project:
List of all the templates on the server:
Get project details: GET
Delete a project: DELETE
Create a new empty project: POST plain text (name) to
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. Note that editing via the TeamCity Web UI will ve disabled for projects created via the REST API.
Edit project parameters: GET/DELETE/PUT
http://teamcity:8111/httpAuth/app/rest/projects/<projectLocator>/parameters/<parameter_name> (produces XML, JSON and plain text depending on the "Accept" header, accepts plain text and XML and JSON) Also supported are requests
Project name/description/archived status: GET/PUT
http://teamcity:8111/httpAuth/app/rest/projects/<projectLocator>/<field_name> (accepts/produces text/plain) where <field_name> is one of "name", "description", "archived".
Project's parent project: GET/PUT XML
Project features (issue trackers, versioned settings, custom charts, shared resources and third-party report tabs) are exposed since TeamCity 10.
Filter features of a project, e.g. find all GitHub issue trackers configured for a given project: GET
Filter projects by a project feature, e.g. find all projects with GitHub configured as an issue tracker: GET
List all VCS roots: GET
Get details of a VCS root/delete a VCS root: GET/DELETE
<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
<field_name> is one of the following: name, shared, project (post project locator to "project" to associate a VCS root with a specific project).
List all VCS root instances: GET
A "VCS root" is the setting configured in the TeamCity UI, "VCS root instance" is the internal TeamCity entity which is derived from the "VCS root" to perform actual VCS operation.
If the VCS root has no %-references to parameters, a single VCS root corresponds to a single "VCS root instance".
If a VCS root has %-reference to a parameter and the reference resolves to a different value when the VCS root is attached to different configurations or when custom builds are run, a single "VCS root" can generate several "VCS root instances".
Since TeamCity 10.0:
There are two endpoints dedicated at using in commit hooks from the version control repositories:
POST Both perform the same action (put the VCS root instances matched by the <locator>) to the queue for "checking for changes" process and differ only in responses they produce.
Note that since the matched VCS root instances are the same as for .../app/rest/vcs-root-instances?locator=<locator> request and that means that by default only the first 100 are matched and the rest are ignored. If this limit is hit consider tweaking the <locator> to match less instances (recommended) or increase the limit e.g. by adding ",count:1000" to the locator.
Build Configuration And Template Settings
Build Configuration/Template details: GET
http://teamcity:8111/httpAuth/app/rest/buildTypes/<buildConfigurationLocator> (details on the Build Configuration locator).
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.
To get aggregated status for several build configurations, see Build Status Icon section.
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
Build configuration parameters: GET/DELETE/PUT
http://teamcity:8111/httpAuth/app/rest/buildTypes/<buildTypeLocator>/parameters/<parameter_name> (produces XML, JSON and plain text depending on the "Accept" header, accepts plain text and XML and JSON). The requests
.../parameters/<parameter_name>/value are also supported.
Build configuration steps: GET/DELETE
Create build configuration step: POST
http://teamcity:8111/httpAuth/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 with URLs like:
Since TeamCity 10, it is possible to disable/enable artifact dependencies and agent requirements:
Disable/enable an artifact dependency PUT
http://teamcity:8111/httpAuth/app/rest/buildTypes/<buildTypeLocator>/artifact-dependencies/<id>/disabled (put "true" or "false" text as text/plain)
Disable/enable an agent requirement PUT
http://teamcity:8111/httpAuth/app/rest/buildTypes/<buildTypeLocator>/agent-requirements/<id>/disabled (put "true" or "false" text as text/plain)
Build configuration VCS roots: GET/DELETE
Attach VCS root to a build configuration: POST
The XML/JSON posted is the same as retrieved by GET request to
http://teamcity:8111/httpAuth/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: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.) Note that editing via the TeamCity Web UI will ve disabled for build configurations created via the REST API.
Create a new empty build configuration: POST plain text (name) to
Copy a build configuration: POST XML
<newBuildTypeDescription name='Conf Name' sourceBuildTypeLocator='id:bt42' copyAllAssociatedSettings='true' shareVCSRoots='false'/> to
Read, detach and attach a build configuration from/to a template: GET/DELETE/PUT
http://teamcity:8111/httpAuth/app/rest/buildTypes/<buildTypeLocator>/template (PUT accepts template locator with "text/plain" Content-Type)
Build Configuration Locator
The most frequently used values for "
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
List builds: GET
Get details of a specific build: GET
http://teamcity:8111/httpAuth/app/rest/builds/<buildLocator> (also supports DELETE to delete a build)
Get the list of build configurations in a project with the status of the last finished build in each build configuration:
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.
There is "default" filter which returns only "normal" builds. To return all builds, use "defaultFilter:false" dimension.
The default filter is that only finished builds which are not canceled, not failed-to-start, not personal, and on default branch (in branched build configurations) are included. If only not finished builds are requested (e.g. via "running:true"), "agent" or "user" dimensions are present - default filtering is not applied.
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:
project:<project locator> - limit the list to the builds of the specified project (belonging to any build type directly under the project).
affectedProject:<project locator> - limit the list to the builds of the specified project (belonging to any build type directly or indirectly under the project)
buildType:(<buildTypeLocator>) - only the builds of the specified build configuration
tag:<tag> - since TeamCity 10 get tagged builds. If a list of tags is specified, e.g. tag:<tag1>, tag:<tag2>, only the builds containing all the specified tags are returned. The legacy tags:<tags> locator is supported for compatibility
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 the personal flag. By default, perfsonal builds are not included.
canceled:<true/false/any> - limit builds by the canceled flag. By default, canceled builds are not included.
failedToStart:<true/false/any> - limit builds by the failed to start flag. By default, canceled builds are not included.
running:<true/false/any> - limit builds by the running flag. By default, running builds are not included.
state:running,hanging:true - fetch hanging builds (since TeamCity 10.0)
pinned:<true/false/any> - limit builds by the 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>)". By default only builds from the 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
revision:<REVISION> - find builds by revision. The whole path is: /httpAuth/app/rest/app/rest/builds?locator=revision:(REVISION),buildType:(id:BUILD_TYPE_ID)
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 be in the same format as dates returned by REST API (e.g. "20130305T170030+0400").
queuedDate/startDate/finishDate:(date:<time-date>,build:<build locator>,condition:<before/after>) - filter builds based on the time specified by the build locator, e.g. (finishDate:(date:20151123T203446+0100,condition:after) - (finished after November 23, 2015, 20:34:46)
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 (the default is 5000). If none of the latest N builds match the other specified criteria of the build locator, 404 response is returned.
Get details of a queued build:
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)
List queued builds per project:
List queued builds per build configuration:
Triggering a Build
To start a build, send POST request to
http://teamcity:8111/httpAuth/app/rest/buildQueue with the "build" node (see below) 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. This way, you can monitor the build completeness by querying build details using the "
href" attribute of the build details returned on build triggering, until the build has the
Build node example
Basic build for a build configuration:
Build for a branch marked as personal with a fixed agent, comment and a custom parameter:
Queued build assignment to an agent pool:
Build on a specified change, forced rebuild of all dependencies and clean sources before the build, moved to the build queue top on triggering. (Note that the change is set via the change's internal modification id; see more below):
Get tags: GET
Replace tags: PUT
http://teamcity:8111/httpAuth/app/rest/builds/<buildLocator>/tags/ (put the same XML or JSON as returned by GET)
Add tags: POST
http://teamcity:8111/httpAuth/app/rest/builds/<buildLocator>/tags/ (post the same XML or JSON as returned by GET or just a plain-text tag name)
<buildLocator> here should match a single build only)
Get current pin status: GET
/ (returns "true" or "false" text)
/ (the text in the request data is added as a comment for the action)
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)
Cancel a running or a queued build: POST the
<buildCancelRequest comment='CommentText' readdIntoQueue='false' /> item to the URL of a running or a queued build:
curl -v -u user:password --request POST "http://teamcity:8111/app/rest/buildQueue/<buildLocator
>" --data "<buildCancelRequest comment='' readdIntoQueue='false' />" --header "Content-Type: application/xml"
Stop a running build and readd it to the queue: POST the
<buildCancelRequest comment='CommentText' readdIntoQueue='true' /> item to the URL of a running build:
curl -v -u user:password --request POST ">" --data "<buildCancelRequest comment='' readdIntoQueue='true' />" --header "Content-Type: application/xml"
Expose cancelled build details:
canceledInfo element of the build item (available via
<path> below can be empty for the root of build's artifacts or be a path within the build's artifacts. The path can span into the archive content, e.g.
http://teamcity:8111/httpAuth/app/rest/builds/ (returns the content of a build artifact)
Media-Type: application/octet-stream or a more specific media type (determined from artifact file extension)
Possible error: 400 if the specified path references a directory
http://teamcity:8111/httpAuth/app/rest/builds/ (returns information about a build artifact)
Media-Type: application/xml or application/json
http://teamcity:8111/httpAuth/app/rest/builds/ (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
http://teamcity:8111/httpAuth/app/rest/builds/<build_locator>/artifacts/archived/<path>?locator=pattern:<wildcard> (returns the archive containing the list of artifacts under the path specified. The optional locator parameter can have file <wildcard> to limit the files only to those matching the wildcard)
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.
If you download the artifacts from within a TeamCity build, consider using
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
Since TeamCity 9.1 there is an experimental ability to retrieve entire build chain (all snapshot-dependency-linked builds) for a particular build:
This gets all the snapshot dependency builds recursively for the build with id XXXX.
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
Get statistics for a single build: 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
Get statistics for a list of builds: GET
Downloading build logs via a REST request is not supported, but there is a way to download the log files described here.
id, project, buildType, build, vcsRoot, vcsRootInstance, username, user, version, internalVersion, comment, file, sinceChange, single value, start, count, lookupLimit
Please note that the change id is the change's internal modification id, not the revision. The id can be seen in the change node listed by the REST API or in the URL of the change details (as modId).
Get all changes for a project: GET
http://teamcity:8111/app/rest/changes?locator=project:projectIdGet all the changes in a build configuration since a particular change identified by its id: http://teamcity:8111/httpAuth/app/rest/changes?locator=buildType:(id:buildConfigurationId),sinceChange:(id:changeId)
Get pending changes for a build configuration
Get details of an individual change: GET
Get information about a changed file action : the
files node lists changed files. Since TeamCity 10.0, the information about the changed file action is reported via the
changeType attribute for the files listed as one of the following:
added, edited, removed, copied or
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)
List all build's tests: GET
Get individual test history:
List build's tests which were muted when the build ran:
List currently muted tests (muted since the failure):
Supported test locators:
"id:<internal test id>" available as a part of the URL on the test history page
"name:<full test name>"
Since TeamCity 10 there is experimental support for exposing single test invocations / runs:
Get invocations of a test:
List all test runs with all the invocations flattened:
assignee: (<user locator>)
Get investigations for a specific test:
Get investigations assigned to a user:
Get investigations for a build configuration:
List all agents: GET
List all connected authorized agents: GET
List all authorized agents: GET
List all enabled authorized agents: GET
Enable/disable an agent: PUT
http://teamcity:8111/httpAuth/app/rest/agents/<agentLocator>/enabled (put "true" or "false" text as text/plain). See an example.
Authorize/unauthorize an agent: PUT
http://teamcity:8111/httpAuth/app/rest/agents/<agentLocator>/authorized (put "true" or "false" text as text/plain)
Add a comment when enabling/disabling and authorizing/unauthorising an agent (since TeamCity 10.0):
Agent enabled/authorized data is exposed in the
GET and PUT requests are supported to the following URLs:
On PUT only status and comment/text sub-items are taken into account:
curl -v -u user:password --request PUT "http://teamcity:8111/app/rest/agents/id:1/enabledInfo" --data "<enabledInfo status='false'><comment><text>commentText</text></comment></enabledInfo>" --header "Content-Type:application/xml"
Get/PUT agent's single field: GET/PUT
Delete a build agent: DELETE
Get/modify/remove agent pools:
Add an agent pool:
agentPool name='PoolName element to
Move an agent to the pool from the previous pool:
<agent id='YYY'/> to the pool's agents
curl -v -u user:password http://teamcity.url/app/rest/agentPools/id:XXX/agents --request POST --header "Content-Type:application/xml" --data "<agent id='1'/>"
Assigning Projects to Agent Pools
Add a project to a pool:
POST the <project> node to
Delete a project from a pool:
List of users: GET
Get specific user details: GET
Create a user: POST
Update/remove specific user: PUT/DELETE
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:
<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
User's single property: GET/DELETE/PUT
List of groups: GET
List of users within a group:
Create a group: POST
Delete a group: DELETE
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
Typed Parameters Specification
List typed parameters:
- for a project:
- for a build configuration:
The information returned is:
typeelement is the parameter specification as defined in the UI.
Get details of a specific parameter:
http://teamcity:8111/httpAuth/app/rest/buildTypes/<locator>/parameters/<name>. Accepts/returns plain-text, XML, JSON. Supply the relevant
Content-Type header 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/. Note that secure parameters, i.e.
type=password, are listed, but the values included into response, so the result should be amended before POSTing back.
Since TeamCity 9.1, partial updates of a parameter are possible (currently in an experimental state):
- name: PUT the same XML or JSON as returned by GET to
- type: GET/PUT accepting XML and JSON as returned by GET to the URL
- type's rawValue: GET/PUT accepting plain text
Build Status Icon
Icon that represents a build status:
Icon that represents build status for several builds (since TeamCity 10.0):
http://teamcity:8111/httpAuth/app/rest/builds/aggregated/<build locator> request and "
strob" build locator dimension:
For request /app/rest/builds/aggregated/<build locator> the status is calculated by list of the builds: app/rest/builds?locator=<build locator>
This allows embedding a build status icon into any HTML page with a simple
<buildLocator> options 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-compatible XML is available via
Without authentication (only build configurations available for guest user):
The CCTray-format XML does not include paused build configurations by default. The URL accepts "locator" parameter instead with standard build configuration locator.
Request Sending Tool
You can use curl command line tool to interact with the TeamCity REST API.
curl -v --basic --user USERNAME:PASSWORD --request POST "http://teamcity:8111/httpAuth/app/rest/users/" --data @data.xml --header "Content-Type: application/xml"
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
curl -v -u USER:PASSWORD http://teamcity:8111/app/rest/projects --header "Content-Type: application/xml" --data-binary
"<newProjectDescription name='New Project Name' id='newProjectId'><parentProject locator='id:project1'/></newProjectDescription>"
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
>\logs\teamcity-rest.log for a line:
Authentication token for superuser generated: 'XXX-YYY-...-ZZZ'.
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:
"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
Note that editing via the TeamCity Web UI will ve disabled for projects created via the REST API